Listmonk

​

Overview

​

Architecture

• Listmonk — A stateful, single-replica workload serving the admin UI, the public subscription/tracking pages, and the HTTP API on port 9000. The container boots through listmonk’s own idempotent install chain: it waits for the database, installs the schema, applies any pending migrations, then starts the server. A default install is ready in about a minute with no manual setup step, and a restart re-runs the same chain safely — it detects an already-provisioned database, skips the install, and leaves existing data untouched.
• PostgreSQL (single-instance, default) — The postgres template as a subchart: the store for all lists, subscribers, campaigns, templates, and settings.
• PostgreSQL (HA, optional) — The postgres-highly-available template instead: 3× Patroni PostgreSQL with automatic failover, fronted by an HAProxy leader endpoint that listmonk connects through for writes and schema migrations.

​

What Gets Created

• Stateful Listmonk Workload — The listmonk server on port 9000, one replica, with configurable CPU and memory.
• Database Workloads — Single mode: one stateful PostgreSQL workload. HA mode: a stateful Patroni PostgreSQL workload, a stateful etcd workload, and a standard HAProxy leader-routing workload.
• Volume Sets — A persistent uploads volume set mounted at /listmonk/uploads for media uploaded through the admin UI, plus the database subchart’s data volumes (10 GiB by default; per replica in HA mode).
• Secret — A dictionary secret holding the admin bootstrap username and password. The database credentials secret is created by the backing store subchart.
• Identity & Policy — An identity bound to the listmonk workload, with a policy granting reveal on exactly two secrets: the admin bootstrap secret and the active backing store’s credentials secret.
• Cron Backup Workload (optional) — Created in the backing PostgreSQL store when database backups are enabled.

​

Prerequisites

• SMTP — required before any mail is delivered. Configured in listmonk’s own admin UI (see Post-Install Setup).
• Database backups (optional) — need a bucket and provider access set up beforehand (see Backing Up).

​

Choosing a Database Mode

​

Configuration

image: listmonk/listmonk:v6.2.0 # official Docker Hub image

resources: # single Go binary — light footprint
  cpu: 500m
  memory: 512Mi
  minCpu: 150m
  minMemory: 256Mi

# Persistent media uploads (filesystem media store), mounted at /listmonk/uploads
volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)

admin:
  username: admin                    # min 3 chars
  password: change-me-listmonk-admin # min 8 chars — change before installing

timezone: Etc/UTC # container TZ — governs campaign scheduling times

publicAccess:
  enabled: true # HTTPS admin UI + public subscription/tracking pages via the canonical *.cpln.app endpoint

internalAccess:
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: []  # only used when type is same-gvc or workload-list

postgres: # default: single-instance PostgreSQL
  enabled: true
  image: postgres:18 # listmonk requires Postgres 12+
  config:
    username: listmonk
    password: change-me-listmonk-db # change before installing
    database: listmonk
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)
  backup:
    enabled: false        # true = scheduled DB backups to object storage
    schedule: "0 2 * * *" # daily at 2am UTC
    provider: aws         # aws | gcp | minio
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: listmonk/backups

postgresHA: # durable HA: 3-replica Patroni store with an HAProxy leader endpoint (disable postgres first)
  enabled: false
  postgres:
    username: listmonk
    password: change-me-listmonk-db # change before installing
    database: listmonk
  replicas: 3
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)
  backup:
    enabled: false # true = scheduled backups to object storage
    mode: logical  # logical | wal-g
    provider: aws  # aws | gcp | minio
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: listmonk/backups

​

Application

• image — The official listmonk image from Docker Hub.
• resources — CPU and memory bounds for the listmonk workload. Listmonk is a single Go binary, so the defaults suit typical installs.
• volumeset.capacity — Initial size in GiB (minimum 10) of the uploads volume set mounted at /listmonk/uploads. It holds images and files uploaded through the admin Media page, including generated thumbnails, and survives restarts and redeploys.
• timezone — The container timezone, which governs the times used for scheduled campaigns.

​

Admin Bootstrap

admin:
  username: admin                    # min 3 chars
  password: change-me-listmonk-admin # min 8 chars — change before installing

​

Access

• publicAccess.enabled — Serve listmonk on the auto-assigned *.cpln.app HTTPS canonical endpoint (default). This is what makes the subscriber-facing pages — subscription forms, unsubscribe links, and tracking pixels — reachable from the internet. The admin UI and admin API on the same endpoint remain authentication-gated. Set to false for an internal-only instance: external requests are then refused at the edge, and in-GVC callers still reach it per internalAccess.
• internalAccess.type — Controls which workloads can reach listmonk over the internal network:

​

Backing Store

​

Connecting

​

Post-Install Setup

​

Backing Up

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": "arn:aws:s3:::my-backup-bucket" },
    { "Effect": "Allow", "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"], "Resource": "arn:aws:s3:::my-backup-bucket/*" }
  ]
}

​

Important Notes

• Single instance by design — there is no replicas knob. Listmonk runs its campaign workers in-process, so two instances against one database would send every campaign twice. The workload is pinned to one replica and rolls out without surge: the old replica stops before the new one starts, which means an upgrade or restart causes a brief gap in availability instead of overlapping senders. Durability comes from PostgreSQL and the uploads volume set.
• Change admin.password and the database password before installing. Both are applied on the first boot only; editing them afterwards does not change the existing account or database.
• No mail is delivered until SMTP is configured in Admin → Settings → SMTP. Before that, starting a campaign is not an error — it runs and finishes with zero messages sent.
• Keep publicAccess enabled for subscriber-facing pages to work. Subscription forms, unsubscribe links, and tracking pixels must be reachable from the internet; the admin UI and API stay authentication-gated either way.
• Use /health for external health checks, not /api/health — the latter requires an authenticated session.
• Volumes survive reinstalls under the same release name; uninstalling deletes them — the database volumes and the uploads volume set go with the release, taking all lists, subscribers, campaigns, and media with them. Use postgresHA and/or enable backups for durable production data.

​

External References