Skip to content

Installation

listmonk is a simple binary application that requires a Postgres database instance to run. The binary can be downloaded and run manually, or it can be run as a container with Docker compose.

Binary

  1. Download the latest release and extract the listmonk binary. amd64 is the main one. It works for Intel and x86 CPUs.
  2. ./listmonk --new-config to generate config.toml. Edit the file.
  3. ./listmonk --install to install the tables in the Postgres DB (⩾ 12).
  4. Run ./listmonk and visit http://localhost:9000 to create the Super Admin user and login.

Tip

To set the Super Admin username and password during installation, set the environment variables: LISTMONK_ADMIN_USER=myuser LISTMONK_ADMIN_PASSWORD=xxxxx ./listmonk --install

Docker

The latest image is available on DockerHub at listmonk/listmonk:latest

The recommended method is to download the docker-compose.yml file, customize it for your environment and then to simply run docker compose up -d.

# Download the compose file to the current directory.
curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml

# Run the services in the background.
docker compose up -d

Then, visit http://localhost:9000 to create the Super Admin user and login.

Tip

To set the Super Admin username and password during setup, set the environment variables (only the first time): LISTMONK_ADMIN_USER=myuser LISTMONK_ADMIN_PASSWORD=xxxxx docker compose up -d

Mounting a custom config.toml

The docker-compose file includes all necessary listmonk configuration as environment variables, LISTMONK_*. If you would like to remove those and mount a config.toml instead:

1. Save the config.toml file on the host

[app]
address = "0.0.0.0:9000"

# Database.
[db]
host = "listmonk_db" # Postgres container name in the compose file.
port = 5432
user = "listmonk"
password = "listmonk"
database = "listmonk"
ssl_mode = "disable"
max_open = 25
max_idle = 25
max_lifetime = "300s"

2. Mount the config file in docker-compose.yml

  app:
    ...
    volumes:
    - /path/on/your/host/config.toml:/listmonk/config.toml

3. Change the --config '' flags in the command: section to point to the path

command: [sh, -c, "./listmonk --install --idempotent --yes --config /listmonk/config.toml && ./listmonk --upgrade --yes --config /listmonk/config.toml && ./listmonk --config /listmonk/config.toml"]

Nightly

Warning

Nightly releases are untested and may have bugs. Use at your own risk. Always take a backup of your Postgres database before using a nightly release.

A nightly build is automatically published with the latest changes merged to the repository. If you want to access the latest changes without waiting for versioned releases, you can obtain the nightly builds and follow the same instructions above.

  • Docker: listmonk/listmonk:nightly (use this as the image name in the docker-compose file)
  • Binary: Download nightly release

Compiling from source

To compile the latest unreleased version (master branch):

  1. Make sure go, nodejs, and yarn are installed on your system.
  2. git clone git@github.com:knadh/listmonk.git
  3. cd listmonk && make dist. This will generate the listmonk binary.

Helm chart for Kubernetes

Version: 0.1.0 Type: application AppVersion: 3.0.0

A helm chart for easily installing listmonk on a kubernetes cluster is made available by community here.

In order to use the helm chart, you can configure values.yaml according to your needs, and then run the following command:

$ helm upgrade \
    --create-namespace \
    --install listmonk listmonk \
    --namespace listmonk \
    --repo https://th0th.github.io/helm-charts \
    --values values.yaml \
    --version 0.1.0

3rd party hosting

Deploy to Elestio
Deploy on PikaPod
One-click deploy on Northflank
One-click deploy on Railway
Deploy at RepoCloud
Deploy on Sealos
Deploy on Zeabur
Install on Cloudron

Tutorials