listmonk requires Postgres ⩾ 12.
See the "Tutorials" section at the bottom for detailed guides.
- Download the latest release and extract the listmonk binary.
./listmonk --new-configto generate config.toml. Then, edit the file.
./listmonk --installto install the tables in the Postgres DB.
The latest image is available on DockerHub at
Listmonk's docs and scripts use
docker compose, which is compatible with the latest version of docker. If you installed docker and docker-compose from your Linux distribution, you probably have an older version and will need to use the
docker-compose command instead, or you'll need to update docker manually. More info.
Use the sample docker-compose.yml to run listmonk and Postgres DB with
docker compose as follows:
Easy Docker install¶
mkdir listmonk-demo && cd listmonk-demo sh -c "$(curl -fsSL https://raw.githubusercontent.com/knadh/listmonk/master/install-demo.sh)"
Manual Docker install¶
wget -O docker-compose.yml https://raw.githubusercontent.com/knadh/listmonk/master/docker-compose.yml docker compose up -d demo-db demo-app
The demo does not persist Postgres after the containers are removed. DO NOT use this demo setup in production.
Easy Docker install¶
This setup is recommended if you want to quickly setup
listmonk in production.
mkdir listmonk && cd listmonk sh -c "$(curl -fsSL https://raw.githubusercontent.com/knadh/listmonk/master/install-prod.sh)"
The above shell script performs the following actions:
docker-compose.ymland generates a
- Runs a Postgres container and installs the database schema.
- Runs the
It's recommended to examine the contents of the shell script, before running in your environment.
Manual Docker install¶
The following workflow is recommended to setup
listmonk manually using
docker compose. You are encouraged to customise the contents of
docker-compose.yml to your needs. The overall setup looks like:
docker compose up dbto run the Postgres DB.
docker compose run --rm app ./listmonk --installto setup the DB (or
--upgradeto upgrade an existing DB).
config.toml.sampleto your directory and make the following changes:
0.0.0.0:9000(Port forwarding on Docker will work only if the app is advertising on all interfaces.)
listmonk_db(Container Name of the DB container)
docker compose up appand visit
Mounting a custom config.toml¶
To mount a local
config.toml file, add the following section to
app: <<: *app-defaults depends_on: - db volumes: - ./path/on/your/host/config.toml:/listmonk/config.toml
Some common changes done inside
config.toml for Docker based setups:
Here's a sample
config.toml you can use:
[app] address = "0.0.0.0:9000" admin_username = "listmonk" admin_password = "listmonk" # Database. [db] host = "listmonk_db" port = 5432 user = "listmonk" password = "listmonk" database = "listmonk" ssl_mode = "disable" max_open = 25 max_idle = 25 max_lifetime = "300s"
Mount the local
config.toml inside the container at
- See configuring with environment variables for variables like
- Ensure that both
dbcontainers are in running. If the containers are not running, restart them
docker compose restart app db.
- Refer to this tutorial for setting up a production instance with Docker + Nginx + LetsEncrypt SSL.
docker-compose.yml file works with Docker Engine 24.0.5+ and Docker Compose version v2.20.2+.
Changing the port¶
To change the port for listmonk:
- Ensure no other container of listmonk app is running. You can check with
docker ps | grep listmonk.
- Change L11 to
3876:9000. This will expose the port 3876 on your local network to the container's network interface on port 9000.
- For NGINX setup, if you're running NGINX on your local machine, you can proxy_pass to the
<MACHINE_IP>:3876. You can also run NGINX as a docker container within the listmonk's container (for that you need to add a service
nginxin the docker-compose.yml). If you do that, then proxy_pass will be set to
http://app:9000. Docker's network will resolve the DNS for
appand directly speak to port 9000 (which the app is exposing within its own network).
Compiling from source¶
To compile the latest unreleased version (
- Make sure
yarnare installed on your system.
git clone email@example.com:knadh/listmonk.git
cd listmonk && make dist. This will generate the
Release candidate (RC)¶
master branch with bleeding edge changes is periodically built and published as
listmonk/listmonk:rc on DockerHub. To run the latest pre-release version, replace all instances of
listmonk/listmonk:rc in the docker-compose.yml file and follow the Docker installation steps above. While it is generally safe to run release candidate versions, they may have issues that only get resolved in a general release.
3rd party hosting¶
- Informal step-by-step on how to get started with Listmonk using Railway
- Complete Listmonk setup guide. Step-by-step tutorial for installation and all basic functions. Amazon EC2 & SES
- Step-by-step guide on how to install and set up Listmonk on a server (rameerez, AWS Lightsail & docker)
- Binary install on Ubuntu 22.04 as a service
- Binary install on Ubuntu 18.04 as a service (Apache & Plesk)
- Binary and docker on linux (techviewleo)
- Binary install on your PC. Discussions of limitations: .
- Install Listmonk with Docker on Rocky Linux 8 (nginx, Let's Encrypt SSL)
- Docker with nginx reverse proxy, certbot SSL, and Gmail SMTP
- Install Listmonk on Self-hosting with Pre-Configured AMI Package at AWS by Single Click
- Tutorial for deploying on Fly.io -- Currently not working