listmonk

listmonk is a selfhosted newsletter and mailing list manager.


Note

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

License

listmonk is released under the AGPL v3 license.

Installation

Create the target directory:

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

Jump into the new directory:

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

Note

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 https://github.com/knadh/listmonk/releases/download/v2.0.0/listmonk_2.0.0_linux_amd64.tar.gz
[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

Warning

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

Configuration

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:

[app]
# 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 '0.0.0.0'. To listen on the default web address
# port, use port 80 (this will require running with elevated permissions).
address = "0.0.0.0:9000"

# 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.
[db]
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:

[program:listmonk]
command=%(ENV_HOME)s/opt/listmonk/listmonk --config %(ENV_HOME)s/opt/listmonk/config.toml
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.

Webserver setup

Note

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

Updates

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 https://github.com/knadh/listmonk/releases/download/<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 <git.fm@mmw9.de>