Installation¶
listmonk requires Postgres ⩾ 12.
See the "Tutorials" section at the bottom for detailed guides.
Binary¶
- Download the latest release and extract the listmonk binary.
amd64
is the main one. It works for Intel and x86 CPUs. ./listmonk --new-config
to generate config.toml. Then, edit the file../listmonk --install
to install the tables in the Postgres DB.- Run
./listmonk
and visithttp://localhost:9000
.
Docker¶
The latest image is available on DockerHub at listmonk/listmonk:latest
Note
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:
Demo¶
Easy Docker install¶
mkdir listmonk-demo && cd listmonk-demo
bash -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
Warning
The demo does not persist Postgres after the containers are removed. DO NOT use this demo setup in production.
Production¶
Easy Docker install¶
This setup is recommended if you want to quickly setup listmonk
in production.
mkdir listmonk && cd listmonk
bash -c "$(curl -fsSL https://raw.githubusercontent.com/knadh/listmonk/master/install-prod.sh)"
The above shell script performs the following actions:
- Downloads
docker-compose.yml
and generates aconfig.toml
. - Runs a Postgres container and installs the database schema.
- Runs the
listmonk
container.
Note
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 db
to run the Postgres DB.docker compose run --rm app ./listmonk --install
to setup the DB (or--upgrade
to upgrade an existing DB).- Copy
config.toml.sample
to your directory and make the following changes:app.address
=>0.0.0.0:9000
(Port forwarding on Docker will work only if the app is advertising on all interfaces.)db.host
=>listmonk_db
(Container Name of the DB container)
- Run
docker compose up app
and visithttp://localhost:9000
.
Mounting a custom config.toml¶
To mount a local config.toml
file, add the following section to docker-compose.yml
:
app:
<<: *app-defaults
depends_on:
- db
volumes:
- ./path/on/your/host/config.toml:/listmonk/config.toml
Note
Some common changes done inside config.toml
for Docker based setups:
- Change
app.address
to0.0.0.0:9000
. - Change
db.host
tolistmonk_db
.
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 listmonk/config.toml
.
Tip
- See configuring with environment variables for variables like
app.admin_password
anddb.password
- Ensure that both
app
anddb
containers are in running. If the containers are not running, restart themdocker compose restart app db
. - Refer to this tutorial for setting up a production instance with Docker + Nginx + LetsEncrypt SSL.
Info
The example 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
custom-port:9000
Eg: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 servicenginx
in the docker-compose.yml). If you do that, then proxy_pass will be set tohttp://app:9000
. Docker's network will resolve the DNS forapp
and directly speak to port 9000 (which the app is exposing within its own network).
Compiling from source¶
To compile the latest unreleased version (master
branch):
- Make sure
go
,nodejs
, andyarn
are installed on your system. git clone git@github.com:knadh/listmonk.git
cd listmonk && make dist
. This will generate thelistmonk binary
.
Release candidate (RC)¶
The 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:latest
with 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.
Helm chart for kubernetes¶
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¶
Tutorials¶
- Informal step-by-step on how to get started with Listmonk using Railway
- Step-by-step tutorial for installation and all basic functions. Amazon EC2, SES, docker & binary
- Step-by-step guide on how to install and set up Listmonk on AWS Lightsail with docker (rameerez)
- Quick setup on any cloud server using docker and caddy
- 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: [1][2].
- 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