Mailtrain¶
Mailtrain is a self-hosted open-source newsletter app built on top of Nodemailer.
Note
For this guide you should be familiar with the basic concepts of
Prerequisites¶
This guide uses Node.js version 12, which is the default at at the moment.
Set up your URL:
[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$
You’ll need your MySQL credentials. Get them with my_print_defaults:
[isabell@stardust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
[isabell@stardust ~]$
Installation¶
Clone the GitHub repository:
[isabell@stardust ~]$ git clone git://github.com/Mailtrain-org/mailtrain.git
[isabell@stardust ~]$
Install the required dependencies:
[isabell@stardust ~]$ cd mailtrain
[isabell@stardust mailtrain]$ npm install --production
[isabell@stardust mailtrain]$
Configuration¶
Database Setup¶
Create a new database:
[isabell@stardust mailtrain]$ mysql -e "CREATE DATABASE ${USER}_mailtrain;"
[isabell@stardust mailtrain]$
Mailtrain Config¶
Copy the example config file:
[isabell@stardust mailtrain]$ cp config/default.toml config/production.toml
[isabell@stardust mailtrain]$
Update production.toml with your MySQL settings; look for the [mysql] block:
...
[mysql]
host="localhost"
user="isabell"
password="MySuperSecretPassword"
database="isabell_mailtrain"
...
Web Backend Config¶
Note
Mailtrain is running on port 3000.
To make the application accessible from the outside, configure a web backend:
[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$
Supervisord Daemon Setup¶
Create ~/etc/services.d/mailtrain.ini with the following content:
[program:mailtrain]
directory=%(ENV_HOME)s/mailtrain/
command=env NODE_ENV=production /bin/node index.js
autostart=yes
autorestart=yes
After creating the configuration, tell supervisord to refresh its configuration and start the service:
[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE RUNNING pid 26020, uptime 0:03:14
[isabell@stardust ~]$
If it’s not in state RUNNING, check your configuration.
Login and Change Admin Credentials¶
Warning
Change the default admin credentials to prevent unauthorized access of your data!
Your Mailtrain installation should now be reachable on https://isabell.uber.space. Log in with the username admin and the password test.
Go to https://isabell.uber.space/users/account and change your email address as well as your password.
Note
It is not possible to change the username in the GUI. If you want to change the default username admin to something else or add additional users, you have to do it directly in the database.
Finishing installation¶
Warning
We do not allow mass mailings from our servers (see the Uberspace House Rules). However, you can use Mailtrain as the admin interface for your mailing needs. Use the SMTP services from AWS SES, Sendgrid, Mailgun, etc. for the actual mailing.
Go to https://isabell.uber.space/settings. In the General Settings section change the Service Address (URL) to https://isabell.uber.space/.
In the Mailer Settings section change the following entries according to the documentation of your mailing service:
Hostname,
Port,
Encryption,
username,
password and
test your settings by pressing the Button Check Mailer Config.
Best Practices¶
Test the configuration by creating a new list and subscribing yourself to it.
Craft your campaign with love and dedication.
Don’t spam users that don’t want your newsletter.
Tested on Uberspace v7.7.0 with NodeJS v12 and MariaDB 10.3.23.
Written by: Felix Förtsch <https://felixfoertsch.de>