listmonk is a self-hosted newsletter and mailing list manager.


For this guide you should be familiar with the basic concepts of


listmonk is released under the AGPL v3 license.


Create the target directory:

[isabell@stardust ~]$ mkdir -p ~/opt/listmonk/
[isabell@stardust ~]$

Jump into the new directory:

[isabell@stardust ~]$ cd ~/opt/listmonk/
[isabell@stardust ~]$


Please check the Github project page for the latest release and copy the archive download link named with listmonk_<version>_linux_amd64.

Download the archive file:

[isabell@stardust ~]$ wget
[isabell@stardust ~]$

Untar the archive file:

[isabell@stardust ~]$ tar -xzf listmonk_2.0.0_linux_amd64.tar.gz
[isabell@stardust ~]$

Delete the archive file:

[isabell@stardust ~]$ rm listmonk_2.0.0_linux_amd64.tar.gz
[isabell@stardust ~]$

Database Setup


Your PostgreSQL database environment has to be setup as described in the Lab-Guide before you follow the next steps.

Create a new database user (in this example listmonk):

[isabell@stardust ~]$ createuser listmonk -P
[isabell@stardust ~]$

Create a new database (in this example listmonk):

[isabell@stardust ~]$ createdb --encoding=UTF8 --owner=listmonk --template=template0 listmonk
[isabell@stardust ~]$


Please write down your database info with: user, password and database.


listmonk configuration

Jump into the listmonk directory:

[isabell@stardust ~]$ cd ~/opt/listmonk/
[isabell@stardust ~]$

Generate the config file:

[isabell@stardust ~]$ ./listmonk --new-config
[isabell@stardust ~]$

Edit the config file ~/opt/listmonk/config.toml and change the predefined values of the admin user and database settings:

# Interface and port where the app will run its webserver.  The default value
# of localhost will only listen to connections from the current machine. To
# listen on all interfaces use ''. To listen on the default web address
# port, use port 80 (this will require running with elevated permissions).
address = ""

# BasicAuth authentication for the admin dashboard. This will eventually
# be replaced with a better multi-user, role-based authentication system.
# IMPORTANT: Leave both values empty to disable authentication on admin
# only where an external authentication is already setup.
admin_username = "listmonk"
admin_password = "password"

# Database.
host = "localhost"
port = 5432
user = "listmonk"
password = "password"
database = "listmonk"
ssl_mode = "disable"
max_open = 25
max_idle = 25
max_lifetime = "300s"

Create the database structure:

[isabell@stardust ~]$ ./listmonk --install
[isabell@stardust ~]$

Daemon setup

Create ~/etc/services.d/listmonk.ini with the following content:

command=%(ENV_HOME)s/opt/listmonk/listmonk --config %(ENV_HOME)s/opt/listmonk/config.toml

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.

Webserver setup


listmonk is running on port 9000.

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 ~]$


Check the project page on Github for new releases. The update approach is similar to the standard installation.

Stop the daemon:

[isabell@stardust ~]$ supervisorctl stop listmonk
[isabell@stardust ~]$

Jump into the listmonk directory:

[isabell@stardust ~]$ cd ~/opt/listmonk/
[isabell@stardust ~]$

Download the new archive file:

[isabell@stardust ~]$ wget<version>/listmonk_<version>_linux_amd64.tar.gz
[isabell@stardust ~]$

Rename your existing file-version:

[isabell@stardust ~]$ mv listmonk listmonk-old
[isabell@stardust ~]$

Untar the archive file:

[isabell@stardust ~]$ tar -xzf listmonk_<version>_linux_amd64.tar.gz
[isabell@stardust ~]$

Delete the archive file:

[isabell@stardust ~]$ rm listmonk_<version>_linux_amd64.tar.gz
[isabell@stardust ~]$

And make the binary file executable:

[isabell@stardust ~]$ chmod +x listmonk
[isabell@stardust ~]$

Start the update process:

[isabell@stardust ~]$ ./listmonk --upgrade
[isabell@stardust ~]$

And start the daemon:

[isabell@stardust ~]$ supervisorctl start listmonk
[isabell@stardust ~]$

In case of no problems you can delete your old version:

[isabell@stardust ~]$ rm listmonk-old
[isabell@stardust ~]$

Tested with listmonk 2.0.0 on Uberspace 7.11.5 with PostgreSQL 13

Written by: FM <>