Self hosted newsletter app
Mailtrain v2
Mailtrain is a self hosted newsletter application built on Node.js (v14+) and MySQL (v8+) or MariaDB (v10+).
This is version 2 of Mailtrain. It mostly implements all features of v1 and add some more. It is a complete rewrite, so you will have to install it from scratch.
If you are upgrading from Mailtrain v1, backup the DB and use it for Mailtrain v2. Mailtrain v2 should be able to upgrade the DB to the new schema.
Features
Recommended minimal hardware Requirements
Quick Start Preparation
Mailtrain creates three URL endpoints, which are referred to as "trusted", "sandbox" and "public". This allows Mailtrain to guarantee security and avoid XSS attacks in the multi-user settings. The function of these three endpoints is as follows:
The recommended deployment of Mailtrain would use 3 DNS entries that all points to the same IP address. For example as follows:
lists
under example.com
domain)mailtrain
under example.com
domain that points to lists
)sbox-mailtrain
under example.com
domain that points to lists
)Installation on fresh CentOS 7 or Ubuntu 18.04 LTS (public website secured by SSL)
This will setup a publicly accessible Mailtrain instance. All endpoints (trusted, sandbox, public) will provide both HTTP (on port 80) and HTTPS (on port 443). The HTTP ports just issue HTTP redirect to their HTTPS counterparts.
The script below will also acquire a valid certificate from Let's Encrypt. If you are hosting Mailtrain on AWS or some other cloud provider, make sure that before running the installation script you allow inbound connection to ports 80 (HTTP) and 443 (HTTPS).
Note, that this will automatically accept the Let's Encrypt's Terms of Service. Thus, by running this script below, you agree with the Let's Encrypt's Terms of Service (https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf).
Login as root. (I had some problems running npm as root on CentOS 7 on AWS. This seems to be fixed by the seemingly extraneous su
within sudo
.)
sudo su -
Install GIT
For Centos 7 type:
yum install -y git
For Ubuntu 18.04 LTS type
apt-get install -y git
Download Mailtrain using git to the /opt/mailtrain
directory
cd /opt
git clone https://github.com/Mailtrain-org/mailtrain.git
cd mailtrain
git checkout v2
Run the installation script. Replace the urls and your email address with the correct values. NOTE that running this script you agree Let's Encrypt's conditions.
For Centos 7 type:
bash setup/install-centos7-https.sh mailtrain.example.com sbox-mailtrain.example.com lists.example.com admin@example.com
For Ubuntu 18.04 LTS type:
bash setup/install-ubuntu1804-https.sh mailtrain.example.com sbox-mailtrain.example.com lists.example.com admin@example.com
Start Mailtrain and enable to be started by default when your server starts.
systemctl start mailtrain
systemctl enable mailtrain
Open the trusted endpoint (like https://mailtrain.example.com
)
Authenticate as admin
:test
Update your password under admin/Account
Update your settings under Administration/Global Settings.
If you intend to sign your email by DKIM, set the DKIM key and DKIM selector under Administration/Send Configurations.
Installation on fresh CentOS 7 or Ubuntu 18.04 LTS (local installation)
This will setup a locally accessible Mailtrain instance (primarily for development and testing). All endpoints (trusted, sandbox, public) will provide only HTTP as follows:
Login as root. (I had some problems running npm as root on CentOS 7 on AWS. This seems to be fixed by the seemingly extraneous su
within sudo
.)
sudo su -
Install git
For Centos 7 type:
yum install -y git
For Ubuntu 18.04 LTS type:
apt-get install -y git
Download Mailtrain using git to the /opt/mailtrain
directory
cd /opt
git clone https://github.com/Mailtrain-org/mailtrain.git
cd mailtrain
git checkout v2
Run the installation script. Replace the urls and your email address with the correct values. NOTE that running this script you agree Let's Encrypt's conditions.
For Centos 7 type:
bash setup/install-centos7-local.sh
For Ubuntu 18.04 LTS type:
bash setup/install-ubuntu1804-local.sh
Start Mailtrain and enable to be started by default when your server starts.
systemctl start mailtrain
systemctl enable mailtrain
Open the trusted endpoint http://localhost:3000
Authenticate as admin
:test
Deployment with Docker and Docker compose
This setup starts a stack composed of Mailtrain, MongoDB, Redis, and MariaDB. It will setup a locally accessible Mailtrain instance with HTTP endpoints as follows.
To make this publicly accessible, you should add reverse proxy that makes these endpoints publicly available over HTTPS. If using the proxy, you also need to set the URL bases and --withProxy
parameter via MAILTRAIN_SETTING
as shown below.
An example of such proxy would be:
To deploy Mailtrain with Docker, you need the following two dependencies installed:
These are the steps to start Mailtrain via docker-compose:
Download Mailtrain's docker-compose build file
curl -O https://raw.githubusercontent.com/Mailtrain-org/mailtrain/v2/docker-compose.yml
Deploy Mailtrain via docker-compose (in the directory to which you downloaded the docker-compose.yml
file). This will take quite some time when run for the first time. Subsequent executions will be fast.
docker-compose up
Open the trusted endpoint http://localhost:3000
Authenticate as admin
:test
The instructions above use an automatically built Docker image on DockerHub (https://hub.docker.com/r/mailtrain/mailtrain). If you want to build the Docker image yourself (e.g. when doing development), use the docker-compose-local.yml
located in the project's root directory.
Deployment with Docker and Docker compose (for development)
This setup starts a stack like above, but is tweaked to be used for local development using docker containers.
Clone this repository
Bring up the development stack
docker-compose -f docker-compose-develop.yml up -d
Connect to a shell inside the container
docker-compose exec mailtrain bash
Run these commands once to install all the node modules and build the client webapp
cd /app
bash setup/reinstall-modules.sh
cd /app/client && npm run build && cd /app
Start the server for the first time with this command, to generate the server/config/production.yaml
bash docker-entrypoint.sh
Docker Environment Variables
When using Docker, you can override the default Mailtrain settings via the following environment variables. These variables have to be defined in the docker-compose config
file. You can give them a value directly in the docker-compose.yml
config file.
Alternatively, you can just declare them there leaving their value empty
(see https://docs.docker.com/compose/environment-variables/#pass-environment-variables-to-containers). In that case, the
value can be provided via a file called .env
or via environment
variables (e.g. URL_BASE_TRUSTED=https://mailtrain.domain.com (and more env-vars..) docker-compose -f docker-compose.yml build (or up)
)
!!!WARNING!!! Always set ADMIN_PASSWORD, as it will leave your instance otherwise vurnerable with the default password being test
!
Parameter Description
ADMIN_PASSWORD
sets Admin Password, Admin users name can be changed, but password will always be overwritten by this, please set it always, as it otherwise defaults to test
ADMIN_ACCESS_TOKEN sets Access Token for API, this is optional
PORT_TRUSTED sets the trusted port of the instance (default: 3000)
PORT_SANDBOX sets the sandbox port of the instance (default: 3003)
PORT_PUBLIC sets the public port of the instance (default: 3004)
URL_BASE_TRUSTED sets the external trusted url of the instance (default: http://localhost:3000), e.g. https://mailtrain.example.com
URL_BASE_SANDBOX sets the external sandbox url of the instance (default: http://localhost:3003), e.g. https://sbox-mailtrain.example.com
URL_BASE_PUBLIC sets the external public url of the instance (default: http://localhost:3004), e.g. https://lists.example.com
WWW_HOST sets the address that the server binds to (default: 0.0.0.0)
WWW_PROXY use if Mailtrain is behind an http reverse proxy (default: false)
WWW_SECRET
sets the secret for the express session (default: $(pwgen -1)
)
MONGO_HOST sets mongo host (default: mongo)
WITH_REDIS enables or disables redis (default: true)
REDIS_HOST sets redis host (default: redis)
REDIS_PORT sets redis host (default: 6379)
MYSQL_HOST sets mysql host (default: mysql)
MYSQL_PORT sets mysql port (default: 3306)
MYSQL_DATABASE sets mysql database (default: mailtrain)
MYSQL_USER sets mysql user (default: mailtrain)
MYSQL_PASSWORD sets mysql password (default: mailtrain)
WITH_LDAP use if you want to enable LDAP authentication
LDAP_HOST LDAP Host for authentication (default: ldap)
LDAP_PORT LDAP port (default: 389)
LDAP_SECURE use if you want to use LDAP with ldaps protocol
LDAP_BIND_USER User for LDAP connexion
LDAP_BIND_PASS Password for LDAP connexion
LDAP_FILTER LDAP filter
LDAP_BASEDN LDAP base DN
LDAP_UIDTAG LDAP UID tag (e.g. uid/cn/username)
WITH_ZONE_MTA enables or disables builtin Zone-MTA (default: true)
POOL_NAME sets builtin Zone-MTA pool name (default: os.hostname())
WITH_CAS use if you want to use CAS
CAS_URL CAS base URL
CAS_NAMETAG The field used to save the name (default: username)
CAS_MAILTAG The field used to save the email (default: mail)
CAS_NEWUSERROLE The role of new users (default: nobody)
CAS_NEWUSERNAMESPACEID The namespace id of new users (default: 1)
LOG_LEVEL sets log level among `silly
DEFAULT_LANGUAGE sets default language (default: en-US)
WITH_POSTFIXBOUNCE enables PostfixBounce TCP listener (default: false)
POSTFIXBOUNCE_PORT sets PostfixBounce Listening TCP-Port (default: 5699)
POSTFIXBOUNCE_HOST sets PostfixBounce Listening Host (default: 127.0.0.1)
If you don't want to modify the original docker-compose.yml
, you can put your overrides to another file (e.g. docker-compose.override.yml
) -- like the one below.
version: '3'
services:
mailtrain:
environment:
- URL_BASE_TRUSTED
- URL_BASE_SANDBOX
- URL_BASE_PUBLIC
License
GPL-V3.0
Twice a month we will interview people behind open source businesses. We will talk about how they are building a business on top of open source projects.
We'll never share your email with anyone else.