Listmonk is a straightforward, all-in-one self-hosted solution for managing newsletters and mailing lists on Linux. Unlike traditional mailing list tools, Listmonk is designed to be lightweight and high-performance, ensuring speed and efficiency. In this guide, we’ll walk you through the process of installing Listmonk using Docker on Ubuntu and show you how to get started with sending newsletters.
Content
- Advantages of Using Listmonk
- Installation of Listmonk
- Creating Nginx Reverse Proxy
- Installing SSL Certificate
- Accessing and Configuring Listmonk
Advantages of Using Listmonk
One of the biggest selling points of Listmonk is that it can work with almost any external mail delivery server on the Internet. This means that you can send your newsletters with a hosted mail provider such as Gmail or your own self-hosted mail setup.
Listmonk offers the ability to create dynamic email templates, allowing you to craft customized emails that adapt based on the context in which the user receives them.
Additionally, Listmonk includes a powerful analytics module, enabling you to track the performance of your newsletters. This feature monitors both the number of clicks on each message and the overall views of your mailing list over a given time period.
Installing Listmonk
Prerequisites: Docker and Docker Compose
Assumption: This guide assumes you’re deploying Listmonk on a VPS that is always on. It also assumes you already have a domain name with both A and PTR records configured to point to your VPS.
To begin, fetch the repository key for Docker and Docker Compose:
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
Next, create the repository file for Docker and Docker Compose packages:
sudo nano /etc/apt/sources.list.d/docker.list
Add the following line to your repository file:
deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu jammy stable
Update and upgrade your system:
sudo apt update && sudo apt upgrade
Now, install Docker Engine, Docker Compose, and the necessary dependencies:
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin docker-buildx-plugin nginx git curl
Ensure your user has the proper permissions to access Docker:
sudo usermod -aG docker <your_username>
Setting Up and Deploying Listmonk
Create a new directory for your Docker files:
mkdir ~/listmonk && cd ~/listmonk
Next, create a configuration file for Listmonk:
nano ./config.toml
Insert the following configuration:
[app]
address = "0.0.0.0:9000"
admin_username = "listmonk"
admin_password = "listmonk"[db]
host = “listmonk_db” port = 5432 user = “listmonk” password = “INSERT_RANDOM_PASSWORD_HERE” database = “listmonk” ssl_mode = “disable” max_open = 25 max_idle = 25 max_lifetime = “300s” params = “”
You can generate a random password with the following command:
cat /dev/urandom | tr -dc 'A-Za-z0-9' | fold -w 32 | head -n 1
After saving your configuration file, create the docker-compose.yml file:
nano ./docker-compose.yml
Insert the following code into the file:
version: "3.7"
x-app-defaults:
restart: unless-stopped
image: listmonk/listmonk:latest
ports:
- 9000:9000
networks:
- listmonk
environment:
- TZ=Asia/Manila
x-db-defaults:
image: postgres:13
ports:
- 9432:5432
networks:
- listmonk
environment:
- POSTGRES_PASSWORD=INSERT_RANDOM_PASSWORD_HERE
- POSTGRES_USER=listmonk
- POSTGRES_DB=listmonk
restart: unless-stopped
healthcheck:
test:
- CMD-SHELL
- pg_isready -U listmonk
interval: 10s
timeout: 5s
retries: 6
services:
db:
image: postgres:13
ports:
- 9432:5432
networks:
- listmonk
environment:
- POSTGRES_PASSWORD=INSERT_RANDOM_PASSWORD_HERE
- POSTGRES_USER=listmonk
- POSTGRES_DB=listmonk
restart: unless-stopped
healthcheck:
test:
- CMD-SHELL
- pg_isready -U listmonk
interval: 10s
timeout: 5s
retries: 6
container_name: listmonk_db
volumes:
- type: volume
source: listmonk-data
target: /var/lib/postgresql/data
app:
restart: unless-stopped
image: listmonk/listmonk:latest
ports:
- 9000:9000
networks:
- listmonk
environment:
- TZ=Asia/Manila
container_name: listmonk_app
depends_on:
- db
volumes:
- ./config.toml:/listmonk/config.toml
networks:
listmonk: null
volumes:
listmonk-data: null
Deploying Listmonk Docker Containers
First, generate the database for your instance:
docker compose up db
Afterward, start the Listmonk build process by running the listmonk binary inside its Docker container:
docker compose run --rm app ./listmonk --install
When prompted, type “Y” and press Enter to wipe any existing data from the database. This will ensure that the Listmonk container starts clean.
Go back to SSH session for your instance’s database then press Ctrl + C to end the session gracefully.
Finally, restart all Docker containers for Listmonk with the proper settings:
docker compose up -d app db
Setting Up Nginx as a Reverse Proxy
Even though Listmonk is running in Docker, it is not publicly accessible until you configure a reverse proxy to link to it. Follow these steps to set up Nginx as a reverse proxy for Listmonk.
- Create a new site configuration file for your Listmonk instance:
sudo nano /etc/nginx/sites-available/listmonk
- Paste the following configuration into the new file:
server {
server_name listmonk.myvpsserver.top;
location / {
proxy_pass http://127.0.0.1:9000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $host;
}
}
- Create a symbolic link to enable the new site configuration:
sudo ln -s /etc/nginx/sites-available/listmonk /etc/nginx/sites-enabled/
- Reload Nginx to apply the new settings:
sudo systemctl reload nginx
Installing an SSL Certificate
After setting up the reverse proxy, your Listmonk instance will be publicly accessible, but not secure without an SSL certificate. Here’s how to install an SSL certificate for secure connections.
- Ensure the core snap daemon is running:
sudo snap install core
- Install the Certbot snap package from the Electronic Frontier Foundation (EFF), which will allow you to request an SSL certificate:
sudo snap install certbot --classic
- Test if Certbot is working by registering it with EFF:
sudo certbot register --agree-tos -m you@your-email.invalid
- Obtain an SSL certificate for your Listmonk domain:
sudo certbot --nginx -d listmonk.myvpsserver.top
Accessing and Configuring Listmonk
Once the reverse proxy and SSL certificate are set up, you can access your Listmonk instance. Open a web browser and navigate to the URL of your Listmonk installation. This will bring up the login page, where you can log in and start configuring your Listmonk instance.
Click the “Login” button, then type “listmonk” on both the User Name and Password fields.
Doing that will load the main dashboard for your Listmonk instance. Click the “Settings” option on the page’s left sidebar.
Replace the value of the “Root URL” textbox with the complete address of your Listmonk instance.
Click the “Save” button in the top-right corner of the page to save your new settings.
Note: Remember to change the default username and password for security purposes.
Linking Your Gmail Account to Listmonk
Log in to your Gmail account, then click on your user icon in the top-right corner of the page.
Click “Manage your Google Account.”
Click the “Security” category on the page’s left sidebar. Select the “2-Step Verification” option inside the Security subpage.
Scroll down to the bottom of the page, then click the “App Passwords” button.
This will bring up a prompt to ask you for the name of the application that you want to link. Type “listmonk”, then click “Create.”
The page will then pop up a small window with 16 random characters grouped in fours. Copy this to a text file then click “Done.”
Go back to your Listmonk dashboard page then click the “Settings” option on the page’s left sidebar.
Select the “SMTP” tab on the page’s upper bar. Click the “Gmail” link below the “Auth Protocol” dropdown box.
Type the complete email address of your Gmail account in the “Username” field.
Click the “Password” field, then type the 16-letter string you copied from the Gmail website without spaces.
Click “Save” to apply your new SMTP settings.
Lastly, go to the General tab then replace the value of the “Default ‘from’ address” textbox with the address of your Gmail account.
Creating a New Listmonk Newsletter
Go to your Listmonk Dashboard page, click the “Lists” category then click the “All lists” option.
Select the “New” button on the page’s upper right corner.
Fill in the details of your new mailing list, then click “Save.”
That’s it. You have completed installing Listmonk.
Hosting your own newsletter is just one part of creating your own digital platform. Learn how you can extend this by hosting a blog in Linux using Ghost and run your own web Kanban board with Kanboard.
