docker-compose-cookbooks/listmonk/README.md

listmonk

Overview

Self-hosted newsletter and mailing list manager powered by PostgreSQL. This stack deploys listmonk with persistent storage, automatic database initialization/upgrades, and support for reverse proxy integration.

Project Details

• Project Repository: https://github.com/knadh/listmonk
• Container Image: https://hub.docker.com/r/listmonk/listmonk
• Compose Example: https://github.com/knadh/listmonk/blob/master/docker-compose.yml
• Documentation: https://listmonk.app/docs/
• Reverse Proxy Port: 9000 (configurable with LISTMONK_PORT)

Getting Started

1. Start the container: docker compose up -d
2. Open http://localhost:9000 in your browser
3. Follow the initial setup wizard to configure the application

Environment Variable Notes

Most variables are optional because sane defaults are already included in the compose file.

Database

POSTGRES_IMAGE – PostgreSQL container image
POSTGRES_RESTART – Restart policy for PostgreSQL
POSTGRES_USER – PostgreSQL username
POSTGRES_PASSWORD – PostgreSQL password
POSTGRES_DB – PostgreSQL database name

listmonk

LISTMONK_IMAGE – listmonk container image
LISTMONK_RESTART – Restart policy for listmonk
LISTMONK_PORT – Web UI / proxy port
LISTMONK_HOSTNAME – Container hostname
LISTMONK_SSLMODE – PostgreSQL SSL mode
LISTMONK_MAX_OPEN – Maximum open DB connections
LISTMONK_MAX_IDLE – Maximum idle DB connections
LISTMONK_MAX_LIFETIME – DB connection lifetime

Initial Admin User

These are only used during first startup.

LISTMONK_ADMIN_USER – Initial admin username
LISTMONK_ADMIN_PASSWORD – Initial admin password

General

VOL_PATH – Base path for persistent storage
TZ – Container timezone

Volume Notes

/data/listmonk/db PostgreSQL database storage

/data/listmonk/uploads
    listmonk uploads and media storage

Back up both directories regularly.

Network Notes

Requires an external Docker network named:

proxy

Create it manually if it does not already exist:

docker network create proxy

Internal application traffic uses the private:

listmonk

bridge network.

Docker Run

docker run -d \
  --name listmonk \
  -p 9000:9000 \
  -v /data/listmonk/db:/var/lib/postgresql \
  -v /data/listmonk/uploads:/listmonk/uploads:rw \
  listmonk/listmonk:latest

See compose.yaml for the full set of environment variables.

Additional Notes / Gotchas

• The stack automatically runs:

  • database installation
  • schema upgrades
  • application startup

  on container launch.

• The install and upgrade commands are idempotent and safe to rerun.

• Change all default passwords before exposing publicly.

• Designed for use behind a reverse proxy such as Traefik, Caddy, Nginx Proxy Manager, or SWAG.

Dockhand Stack, Deploy from Git

Cookbooks Repository

stackname: listmonk
Compose file path: listmonk/compose.yaml
Additional env file (optional): listmonk/sample.env

Then load:

listmonk/sample.env

into the Environmental Variables section in Dockhand.

Create the Stack.