How To Install Listmonk

This article gives a walkthrough of how to install Listmonk and corresponding dependencies. This article focuses on the Docker implementation of Listmonk and does not outline the process from installing the service from the precompiled binaries.

NOTE: This process has been used by many others but I have personally tested this on Ubuntu and Ubuntu server and have had success, this process will be modified if you are using a non-debian based linux distribution or are using Windows and/or MacOS.

NOTE: This article is heavily based off of an article written by Ramces Red on Make Tech Easier. This version had been adapted from his with updated/corrected code and language improvements. Link to the origional article at the time of posting [MakeTechEasier]


About Listmonk

I will not talk much about Listmonk or its features here, this article merely focuses on how to install it, to learn more about listmonk you can find information on their website. [Listmonk]



Installation Process

Installing Docker and Docker Compose

Retreive the repository key for the Docker and Docker Compose packages


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

Create the new repository file for Docker and Docker Compose packages


sudo nano /etc/apt/sources.list.d/docker.list

Inside the repository file copy (or type) the following configuration


deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu jammy stable

Updae and upgrade your system using the following command


sudo apt update && sudo apt upgrade

Install the Docker Engine along with Docker Compose and its component dependencies


sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin docker-buildx-plugin nginx git curl

Configure permissions such that your current user has rights to access the Docker binaries


sudo usermod -a -G docker [CURRENT USER]


Setting Up & Deploying Listmonk

Create a new directory for your Docker files inside the home directory of your current user


mkdir ~/listmonk && cd ~/listmonk

Create a configuration file for your Listmonk Instance


nano ./config.toml

Copy the following code into your configuration file


[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 = ""

Save the configuration file, then create the listmonk instance's docker-compose.yml


nano ./docker-compose.yml

Paste the following code into the .yml file. This represents the default docker-compose.yml file for Listmonk. Modify time zone and other parameters as needed.


---
x-app-defaults:
    restart: unless-stopped
    image: listmonk/listmonk:latest
    ports:
    - 9000:9000
    networks:
    - listmonk
    environment:
    - TZ=America/Detroit
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 Container

Run the following Docker command to generate your instance's database file


sudo docker compose up db

Open a new SSH connection (if connecting remotely) or another terminal window (if working natively) and start the build process for Listmonk by running the "listmonk" bianary inside its docker container


sudo docker compose run --rm app ./listmonk --install

Type "Y" then press ENTER when the build script asks you to wipe any existing data on the running database. This will ensure that your listmonk container is clean when it starts.

Return the first terminal window (or SSH session) for your instace's databse then press CTRL + C to end the session.

Lastly, restart all te docker containers for Listmonk with its proper settings


sudo docker compose up -d app db


After taking these steps your should be able to access Listmonk's webui from the machine you installed it on at the ip address 127.0.0.1:9000 if you did not modify the address or port when configuring.

On occasion you may have to restart these services one or multiple times for the application to become accessible. To restart the services use the following command.


sudo docker restart listmonk_db listmonk_app


---

To take this installation a step further for production installs I have also created a guide on configuring NGINX as a reverse proxy for Listmonk. See the next article section below

NEXT ARTICLE: [Nginx as Reverse Proxy for Listmonk]

---

Back To Article Page
Back To Home Page