Installing Mailtrain on an Ubuntu Instance

• compute
• mail
• newsletter
• Mailtrain
• Ubuntu

Mailtrain is a self-hosted open-source newsletter application built in Node.js and using MariaDB as datastore.

Before you start

To complete the actions presented below, you must have:

• A Scaleway account logged into the console
• Owner status or IAM permissions allowing you to perform actions in the intended Organization
• An SSH key
• An Instance running on Ubuntu Bionic or later
• Unlocked the SMTP ports
• sudo privileges or access to the root user

Preparing the server

1. Connect to your server via SSH.
2. Install sudo on the server:

   apt install sudo
   

3. Create a regular user account with sudo access and switch into it. Replace my_new_user with your username.

   adduser my_new_user --gecos "My New User"
   usermod -aG sudo my_new_user
   su - my_new_user
   

4. Update the already installed software on the system to the latest version:

   sudo apt update && apt upgrade -y
   

5. Install the required tools:

   sudo apt install -y build-essential unzip
   

6. Install Node.js and NPM:

   sudo curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
   sudo apt install -y nodejs
   

Installing Postfix

To send Mail from your server, an SMTP server is required.

1. Install Postfix via apt:

   sudo apt install -y postfix
   

2. When asked choose Internet Site in the list of options:
   
3. Enter the mail name for your Instance and confirm. The mail name should be a fully qualified domain name (FQDN) resolving to your Instance’s IP address:
   

Installing MariaDB

1. Download the MariaDB repositories to make sure you have the latest version of the database engine available:

   sudo curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash
   

2. Install MariaDB, an open source MySQL fork:

   sudo apt install -y mariadb-server
   

3. Initialize the MariaDB server:

   sudo  mysql_secure_installation
   

4. Connect to the database server as root user with the password you have set previously:

   mysql -u root -p
   

5. Create an empty database for Mailtrain:

   CREATE DATABASE mailtrain;
   

6. Create a database user for Mailtrain and grant all privileges of the database to the user. Then create another user with read-only access to the database:

   GRANT ALL PRIVILEGES ON mailtrain.* TO mailtrain_user@localhost IDENTIFIED BY 'user_password';
   GRANT SELECT ON mailtrain.* TO mt_readonly@localhost IDENTIFIED BY 'readonly_password';
   

   Note

   Replace the demo user and password in the commands above with your preferred username and password.

7. Flush the new privileges and leave the database prompt:

   FLUSH PRIVILEGES;
   EXIT;
   

Installing Nginx

1. Install nginx via apt:

   sudo apt install -y nginx
   

2. Create three configuration files for Nginx:

   sudo nano /etc/nginx/sites-available/mailtrain.example.com.conf
   sudo nano /etc/nginx/sites-available/sbox-mailtrain.example.com.conf
   sudo nano /etc/nginx/sites-available/newsletter.example.com.conf
   

   and put the following content into it:

   • mailtrain.example.com.conf

     server {
         listen [::]:80;
         listen 80;
         server_name mailtrain.example.com;
         charset utf-8;
         client_max_body_size 50M;
         location / {
             proxy_set_header Host $http_host;
             proxy_set_header X-Real-IP $remote_addr;
             proxy_pass http://127.0.0.1:3000;
             proxy_http_version 1.1;
             proxy_set_header Upgrade $http_upgrade;
             proxy_set_header Connection "upgrade";
             proxy_next_upstream error timeout http_502 http_503 http_504;
         }
     }
   

   • sbox-mailtrain.example.com.conf

   server {
           listen 80;
           server_name sbox-mailtrain.example.com;
           access_log /var/log/nginx/sbox-mailtrain.access;
           error_log /var/log/nginx/sbox-mailtrain.error;
         location / {
             proxy_pass http://127.0.0.1:3003;
             proxy_set_header Host $host;
             proxy_set_header X-Real-IP $remote_addr;
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         }
   }
   

   • newsletter.example.com.conf*

   server {
           listen 80;
           server_name newsletter.example.com;
           access_log /var/log/nginx/newsletter.access;
           error_log /var/log/nginx/newsletter.error;
         location / {
             proxy_pass http://127.0.0.1:3004;
             proxy_set_header Host $host;
             proxy_set_header X-Real-IP $remote_addr;
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         }
   }
   

3. Activate the configuration by linking the files in the sites-enabled directory:

   sudo ln -s /etc/nginx/sites-available/mailtrain.example.com.conf /etc/nginx/sites-enabled/
   sudo ln -s /etc/nginx/sites-available/sbox-mailtrain.example.com.conf /etc/nginx/sites-enabled/
   sudo ln -s /etc/nginx/sites-available/newsletter.example.com.conf /etc/nginx/sites-enabled/
   

4. Reload the nginx configuration to enable the new virtual host:

   sudo systemctl reload nginx.service
   

Installing Mailtrain

1. Enter the www directory:

   cd /var/www/
   

2. Download and unzip Mailtrain:

   wget https://github.com/Mailtrain-org/mailtrain/archive/refs/tags/v2.20210609.0.zip
   unzip v2.20210609.0.zip
   rm v2.20210609.0.zip
   mv mailtrain-2.20210609.0 mailtrain
   

3. Change the ownership of the directory to your Mailtrain user:

   chown -R my_new_user:my_new_user /var/www/mailtrain
   

4. Enter the Mailtrain directory:

   cd mailtrain
   

5. Import the database scheme into the Mailtrain database using the following command. Remember to replace mailtrain_user with your database user.

   mysql -u mailtrain_user -p mailtrain < ./server/setup/sql/mailtrain.sql
   

6. Create a production.yaml file by opening it in a text editor. This file allows you to overwrite the default configuration values in the file ./server/config/default.yaml.

   nano ./server/config/production.yaml
   

7. Copy the following configuration into the file and edit it towards your requirements. Then save the file and exit the text editor:

     user: my_new_user
     group: my_new_user
     roUser: nobody
     roGroup: nobody
     www:
       host: 127.0.0.1
       proxy: true
       secret: "Enter secret and random text here"
       trustedUrlBase: http://mailtrain.example.com
       sandboxUrlBase: http://sbox-mailtrain.example.com
       publicUrlBase: http://newsletter.example.com
     mysql:
       user: mailtrain_user
       password: user_password
       database: mailtrain
     redis:
       enabled: true
     log:
       level: info
     builtinZoneMTA:
       enabled: false
     queue:
       processes: 5
   

   Note

   The Mailtrain configuration requires you to specify the following URL endpoints.

   • mailtrain.example.com: The configuration interface for logged-in users.
   • sbox-mailtrain.example.com: This is used to host template editors. This URL is not shown to any user.
   • newsletter.example.com: The public URL as seen by visitors.

8. Create a configuration file for the report worker by opening it in a text editor like nano.

   sudo nano ./server/services/workers/reports/config/production.yaml
   

9. Copy the following configuration in the editor, save the file and exit.

   log:
     level: warn
   mysql:
     user: mailtrain_user
     password: user_password
     database: mailtrain
   

10. Install the required Node packages by running the following command:

    for idx in client shared server mvis/client mvis/server mvis/test-embed mvis/ivis-core/client mvis/ivis-core/server mvis/ivis-core/shared mvis/ivis-core/embedding; do
    (cd $idx && npm install)
    done
    

    Tip

    Do not use sudo when running the command above.

Building Mailtrain

1. Change into the client directory from the mailtrain main directory:

   cd client
   

2. Run the following command to build the application:

   npm run build
   

3. Set the permissions of the config directory:

   sudo chmod o-rwx /var/www/mailtrain/server/config/
   

4. Create a systemd service file for Mailtrain by opening it in a text editor like nano:

   sudo nano /etc/systemd/system/mailtrain.service
   

5. Copy the following configuration into the file, save it and exit the text editor:

   [Unit]
   Description=Mailtrain server
   After=syslog.target network.target mariadb.service redis-server.service
   [Service]
   Environment="NODE_ENV=production"
   WorkingDirectory=/var/www/mailtrain/server
   ExecStart=/usr/bin/node index.js
   Type=simple
   Restart=always
   RestartSec=10
   [Install]
   WantedBy=multi-user.target
   

6. Enable and start the Mailtrain service:

   sudo systemctl enable --now mailtrain.service
   

Accessing the Mailtrain web interface

1. Open your web browser and type the domain name of your Mailtrain Instance.
2. Click Login in the top bar to connect to Mailtrain.
   
3. Login with the username admin and password test. _Do not forget to change the password after your first login._2. Click Login in the top bar to connect to Mailtrain.
   
4. Login with the username admin and password test. Do not forget to change the password after your first login.
   

You have now specified other parameters like your company name, service URL etc. before starting your first e-marketing campaign. For more information on how to plan your campaigns, refer to the official documentation.