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).
• Secrets — The database credentials secret created by the backing store subchart. The Super Admin credentials are not created by this template: you create that dictionary secret yourself before installing and reference it by name (see Prerequisites).
• Identity & Policy — An identity bound to the listmonk workload, with a policy granting reveal on exactly two secrets: your admin credentials 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

cpln secret create-dictionary --name my-listmonk-admin \
  --entry username=admin \
  --entry password="$(openssl rand -hex 24)"

cpln secret reveal my-listmonk-admin -o yaml

listmonk: the my-listmonk-admin secret must hold a username of at least 3 characters and a password
of at least 8 (upstream install requirement)

cpln workload get-deployments RELEASE_NAME-listmonk --gvc GVC_NAME -o yaml

The secret my-listmonk-admin no longer exists. Workload updates are paused until
the secret is added or the reference to the secret removed.

• 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)

# REQUIRED PREREQUISITE SECRET — CREATE IT BEFORE YOU INSTALL. A `dictionary`
# secret holding exactly two keys, `username` (min 3 chars) and `password`
# (min 8 chars); the login form it guards sits on the public endpoint. The
# Super Admin is created on FIRST install only — editing the secret later does
# NOT update the account.
admin:
  secretName: my-listmonk-admin # name of your pre-created dictionary secret

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+
  credentials: # the chart writes these into the secret named below — nothing for you to create
    username: listmonk
    password: change-me-listmonk-db # change before installing
    database: listmonk
  config:
    credentialsSecretName: my-listmonk-db-credentials # secret names are org-wide — give each release its own
  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:
  secretName: my-listmonk-admin # your pre-created dictionary secret (see Prerequisites)

• admin.secretName — Name of the dictionary secret you created in Prerequisites, holding the username and password of the Super Admin. The credentials never pass through values, and the template creates no secret of its own — it references yours and grants the workload reveal on exactly that one secret.
• The account is created during the first boot’s schema install, from the secret’s contents. Because the values are no longer visible when the chart renders, the container enforces upstream’s minimum lengths at startup instead — see the length warning in Prerequisites.

​

Access

• publicAccess.enabled — Serve listmonk on the auto-assigned *.cpln.app HTTPS canonical endpoint. It is deliberately on by default and load-bearing: the subscriber-facing pages — subscription forms, unsubscribe links, and tracking pixels — are served to your subscribers on the open internet, so a private instance cannot do the job. The admin UI and admin API on the same endpoint remain authentication-gated, behind a credential you created rather than a published default. 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

​

Upgrading From 1.0.x

listmonk: admin.password was REMOVED in 1.1.0. Put it in a `dictionary` secret (key: `password`)
together with `username`, and set admin.secretName to that secret's name. Create the secret BEFORE
installing; see Prerequisites in the README.

​

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.
• Create the admin secret before installing — a missing prerequisite secret leaves the workload waiting on something that does not exist, with zero log lines. See Prerequisites for how to diagnose it.
• Mind the minimum credential lengths — a username under 3 characters or a password under 8 makes upstream’s install step fail; the container catches this at startup and names the secret instead of looping on a misleading database message.
• Change the database password before installing (postgres.credentials.password / postgres.credentials.password) — it is bundled plumbing, used exactly as given, and it remains a value by design. Both the admin account and the database are seeded on first boot only.
• 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