Getting started with MSUI

Managed service user interface (MSUI) is an add-on component to Halon MTA. It enables end-users or domain administrators to carry out email-related tasks such as changing settings, trace messages in real time, or look at statistics. It's ideal for organisations that doesn't have their own customer portal.

Requirements

• Halon MTA >= 5.5
• Linux server (LTS version of Ubuntu, Debian, Centos or RHEL)
• MySQL server >= 5.7.8, MariaDB server >= 10.5
• Email tracking and statistics (optional) 
  • web-logui
  • Remote logging to Elasticsearch

Installation

Halon MSUI is provided in our package mirror for Ubuntu and RHEL (CentOS) distributions. In order to install packages from this mirror you need to add it to the system.

Ubuntu

1. Add our GPG key
   

   wget -qO - https://raw.githubusercontent.com/halon/changelog/master/pgp-keys/7F0A73B5.asc | sudo apt-key add -

2. Install the mirror
   Replace username and password with the provided credentials before running.
   

   . /etc/lsb-release && echo "deb [arch=amd64] https://repo.halon.io/ $DISTRIB_CODENAME stable" | sudo tee /etc/apt/sources.list.d/halon.list

   echo "machine repo.halon.io login <username> password <password>" | sudo tee /etc/apt/auth.conf

   sudo apt-get update

3. Install the package
   

   sudo apt-get install halon-msui

RHEL

Follow these steps to add our rpm mirror.

1. Install the yum mirror. Replace username and password with the provided credentials before running.
   

   cat <<'EOF' | sudo tee /etc/yum.repos.d/Halon.repo
   [halon]
   name=Halon repository
   baseurl=https://<username>:<password>@repo.halon.io/dists/rhel8/amd64/stable
   gpgcheck=1
   gpgkey=https://raw.githubusercontent.com/halon/changelog/master/pgp-keys/7F0A73B5.asc
   enabled=1
   EOF

2. Install the package

   sudo yum install halon-msui

Setting it up

1. Create a new database and give full permissions to a new or existing user.
2. Import the database schema from /opt/halon/msui/share/msui_database_schema.sql. 
3. (Optional) The file /opt/halon/msui/share/msui_default_setup.sql includes pre-built settings and roles that can be imported to the new database.
4. Create a new settings file for MSUI by copy the example file from /opt/halon/msui/share/docs/examples/node/msui-example.yaml to /etc/halon/msui.yaml.

   The example file only include some of the available settings, please see /opt/halon/msui/share/msui.schema.json for more documentation.

5. Edit /etc/halon/msui.yaml and follow these steps:
   • Update the server properties.
   • Update all database properties with the credentials and database name you created earlier.
   • Update the credentials for the superuser, password needs to be a hash that can be generated by running: /opt/halon/msui/node/bin/node /opt/halon/msui/dist/bin/generatepass.js.
   • (Optional) To enable Email tracking and statistics you need to provide credentials to web-logui (enduser property in msui.yaml).
     • Make sure that you have set a unique API key in settings.php under the web-logui folder. 
     • Make sure that you have enabled session transfer in web-logui by renaming session-transfer.php.txt to session-transfer.php in the web-logui folder.
     • If a self-signed certificate is used for web-logui, you can set the option to reject unauthorized to false:
       

       enduser:
         [...]
         tls:
           rejectUnauthorized: false

6. Start the service by running systemctl start halon-msui.
7. Integrate MSUI with Halon MTA.

In some scenarios you may want to set up MSUI behind a reverse proxy, useful when you want to share the same server and IP address with e.g. web-logui, please see Set up a reverse proxy (NGINX/Apache) for more information.