Listmonk

Overview

Listmonk is a high-performance, self-hosted newsletter and mailing list manager distributed as a single Go binary — an alternative to Mailchimp, Sendy, and Mautic. This template deploys the listmonk server (admin dashboard, campaign engine, public subscription and tracking pages, and the transactional-mail API) on port 9000, backed by a bundled PostgreSQL store. The database schema is installed and the Super Admin account is created automatically on first boot, so a default install needs no setup wizard. The bundled database is single-instance by default; set postgresHA.enabled: true (and postgres.enabled: false) for a three-replica Patroni cluster with automatic failover. Listmonk itself always runs as exactly one replica — see Scaling and Availability.

This template does not create a GVC. You must deploy it into an existing GVC.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-listmonk`	Listmonk server — admin UI, public pages, HTTP API on port `9000` (stateful, 1 replica)	—
Volume set	`RELEASE_NAME-listmonk-uploads`	Media uploaded through the admin UI, mounted at `/listmonk/uploads` (`ext4`, 10 GiB by default)	—
Identity & Policy	`RELEASE_NAME-listmonk-identity`, `RELEASE_NAME-listmonk-policy`	Grants the listmonk workload `reveal` on exactly two secrets: your admin secret and the database credentials secret	—
Workload	`RELEASE_NAME-postgres`	Single-instance PostgreSQL 18 (stateful, 1 replica, port `5432`)	default — `postgres.enabled: true`
Volume set	`RELEASE_NAME-pg-vs`	PostgreSQL data (`ext4`, 10 GiB by default)	`postgres.enabled: true`
Identity & Policy	`RELEASE_NAME-pg-identity`, `RELEASE_NAME-pg-policy`	Grants the database workload `reveal` on the database credentials secret	`postgres.enabled: true`
Workload	`RELEASE_NAME-postgres-backup`	Scheduled `pg_dump` to object storage (cron)	`postgres.backup.enabled: true`
Workloads	`RELEASE_NAME-postgres-ha`, `RELEASE_NAME-etcd`, `RELEASE_NAME-postgres-ha-proxy`	Patroni PostgreSQL (3 replicas), etcd (3 replicas), and the HAProxy leader endpoint listmonk connects through	`postgresHA.enabled: true`
Volume sets	`RELEASE_NAME-postgres-ha-vs`, `RELEASE_NAME-etcd-vs`	PostgreSQL and etcd data, one volume per replica	`postgresHA.enabled: true`
Identities & Policies	`RELEASE_NAME-postgres-ha-identity`, `RELEASE_NAME-postgres-ha-policy`, `RELEASE_NAME-etcd-identity`, `RELEASE_NAME-etcd-policy`	Secret access for the HA store	`postgresHA.enabled: true`
Secrets	`RELEASE_NAME-patroni-startup`, `RELEASE_NAME-postgres-proxy-startup`, `RELEASE_NAME-etcd-startup`, `RELEASE_NAME-wal-g-backup-script`	Startup scripts for the HA store	`postgresHA.enabled: true`
Workload	`RELEASE_NAME-postgres-ha-backup`	Scheduled backup of the HA store (cron)	`postgresHA.backup.enabled: true`
Secret	`RELEASE_NAME-postgres-config`	Backup bucket and region for the HA store	`postgresHA.backup.enabled: true`

The Super Admin and database credentials are not created by this template. You create those dictionary secrets before installing and reference them by name — see Prerequisites.

Prerequisites

Two dictionary secrets must exist before you install. They hold credentials, so they are prerequisite secrets rather than template values — a value would sit in plaintext in the Helm release for the life of the install. Secrets are org-level, so no GVC flag is involved.

Create the database credentials secret

A dictionary secret with the keys username, password and database. The bundled PostgreSQL initializes with it and listmonk connects with it:

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

Set its name in the key of the store you use: postgres.config.credentialsSecretName (single-instance, the default) or postgresHA.config.credentialsSecretName (HA). Secret names are org-wide, so give each listmonk release its own secret. PostgreSQL reads the secret only when its data is first initialized — see Rotating the Database Password for changing it later.

Create the admin credentials secret

A dictionary secret holding exactly two keys, username (at least 3 characters) and password (at least 8 characters) — both are upstream requirements:

cpln secret create-dictionary --name ADMIN_SECRET_NAME \
  --entry username=admin \
  --entry password='YOUR-STRONG-PASSWORD'

Set admin.secretName to the name you used.

Read the credentials back later

Pass -o yaml. A bare cpln secret reveal prints only a summary table, not the values:

cpln secret reveal ADMIN_SECRET_NAME -o yaml

Create both secrets before installing, or the deployment wedges silently. A name that points at a secret which does not exist installs “successfully” and then never starts. The container never runs, so cpln logs returns zero lines — there is nothing to log. The one place the reason appears is status.versions[].message:

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

The secret ADMIN_SECRET_NAME no longer exists. Workload updates are paused until
the secret is added or the reference to the secret removed.

Use get-deployments — plain cpln workload get has no versions key; a missing database secret shows the same way on RELEASE_NAME-postgres (or RELEASE_NAME-postgres-ha in HA mode). Creating the missing secret repairs the deployment on its own, or run cpln workload force-redeployment RELEASE_NAME-listmonk --gvc GVC_NAME to pick it up immediately.

Nothing else is required for a default install. Database backups are optional and need a bucket and provider access first — see Backing Up. SMTP is configured in listmonk’s own admin UI after installing — see First Run.

Installation

Install into an existing GVC, naming the admin and database credentials secrets you created:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/listmonk \
  --version 1.6.0 --gvc GVC_NAME \
  --set admin.secretName=ADMIN_SECRET_NAME \
  --set postgres.config.credentialsSecretName=DB_CREDENTIALS_SECRET_NAME

Or follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Application

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

resources: # single Go binary — light footprint
  maxCpu: 500m
  maxMemory: 512Mi
  minCpu: 150m # keeps cpu:minCpu under the platform 4:1 cap (500/150 = 3.3:1)
  minMemory: 256Mi

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

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

Admin Bootstrap

admin:
  secretName: my-listmonk-admin # name of your pre-created dictionary secret

The secret named here must exist before you install — see Prerequisites. Its username and password are read only during the first boot’s schema install, when listmonk creates the Super Admin. After that the account lives in the database: editing the secret does not update it, and an upgrade does not change your existing password. Manage users in Admin → Users.

Root URL

# Public base URL for all subscriber-facing links and email (subscribe, unsubscribe,
# archive, open/click tracking). Empty = auto-derive the canonical *.cpln.app endpoint
# when publicAccess is on. Set this to your custom domain once attached.
rootUrl: ""

Listmonk builds every subscriber-facing link — subscription forms, unsubscribe links, the public archive, open and click tracking, and the links inside sent email — from its Root URL setting, so it must match the address subscribers actually use. The setting lives in listmonk’s database and a fresh install seeds it to http://localhost:9000, which would break every one of those links. The container therefore sets it at boot, before serving:

rootUrl set — written on every boot, so the value in your values file always wins. Set it to your custom domain once you attach one.
rootUrl empty and publicAccess.enabled: true — the canonical *.cpln.app endpoint is written, but only while the setting still holds the untouched http://localhost:9000 default. A value you later change in Settings → General is kept.
rootUrl empty and publicAccess.enabled: false — nothing is written; set the Root URL yourself in Settings → General.

Access

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 workload-list
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

Public access is on by default and is load-bearing: subscription forms, unsubscribe links, and tracking pixels are served to subscribers on the open internet. The admin UI and API on the same endpoint stay behind listmonk’s own login, guarded by the credential you created. Set publicAccess.enabled: false only for an internal-only instance; see Connecting for how to reach a private install.

Single-Instance PostgreSQL

The default backing store. Exactly one of postgres or postgresHA must be enabled — the chart refuses to render otherwise.

postgres:
  enabled: true
  image: postgres:18 # listmonk requires Postgres 12+
  config:
    # REQUIRED PREREQUISITE SECRET (single-instance mode) — CREATE IT BEFORE YOU
    # INSTALL. If it does not exist the deployment WEDGES silently and looks like
    # a platform fault. A `dictionary` secret holding exactly three keys:
    # username, password, database. PostgreSQL reads it once, when its data is
    # first initialized, and listmonk connects with the same keys. See
    # Prerequisites for the command.
    credentialsSecretName: my-listmonk-db-credentials
  resources:
    minCpu: 200m
    maxCpu: 500m
    minMemory: 256Mi
    maxMemory: 512Mi
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)
  # Scheduled DB backups to object storage (off by default) — pass-through to the
  # postgres template's native backup. See README "Storage setup".
  backup:
    enabled: false
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0 # 18.1.0 = PG18, 17.1.0 = PG17
    schedule: "0 2 * * *" # daily at 2am UTC
    resources:
      cpu: 100m
      memory: 128Mi
    provider: aws # aws, gcp, or minio
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: listmonk/backups
    gcp:
      bucket: my-backup-bucket
      cloudAccountName: my-backup-cloudaccount
      prefix: listmonk/backups
    minio: # any S3-compatible endpoint (e.g. an internal MinIO template)
      endpoint: http://my-minio-workload:9000
      bucket: my-backup-bucket
      # REQUIRED prerequisite dictionary secret holding `accessKey` and `secretKey`,
      # only when backup is enabled with provider: minio. See README "Storage setup".
      credentialsSecretName: my-listmonk-minio-credentials
      prefix: listmonk/backups

The credentials secret seeds PostgreSQL on its first boot; editing it afterwards does not change the database password — see Rotating the Database Password. Provider setup for backups is under Backing Up.

Highly Available PostgreSQL

Set postgresHA.enabled: true for near-zero-downtime database upgrades and automatic failover: a three-replica Patroni cluster coordinated by etcd, fronted by an HAProxy leader endpoint that listmonk connects through for writes and schema migrations (the chart refuses to render if that proxy is disabled). The credentials come from the prerequisite secret named by postgresHA.config.credentialsSecretName.

postgres:
  enabled: false # exactly one backing store may be enabled

postgresHA:
  enabled: true # set postgresHA.enabled: true for near-zero-downtime upgrades and failover
  image: controlplanecorporation/patroni-postgres:0.8 # pgvector 0.8.7 (CVE-2026-103484); 0.1-0.7 are refused
  config:
    # REQUIRED PREREQUISITE SECRET (HA mode) — the same kind of `dictionary`
    # secret as postgres.config.credentialsSecretName above (keys: username,
    # password, database). Create it BEFORE you install.
    credentialsSecretName: my-listmonk-db-credentials
  replicas: 3
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)
  # Scheduled backups (off by default) — pass-through to the postgres-highly-available
  # template's native backup; see README "Storage setup".
  backup:
    enabled: false
    mode: logical # logical or wal-g
    resources:
      cpu: 100m
      memory: 128Mi
    logical:
      image: ghcr.io/controlplane-com/backup-images/postgres-backup:17.1.0
      schedule: "0 2 * * *" # daily at 2am UTC
    walg:
      intervalSeconds: 21600 # every 6 hours
    provider: aws # aws, gcp, or minio
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: listmonk/backups
    gcp:
      bucket: my-backup-bucket
      cloudAccountName: my-backup-cloudaccount
      prefix: listmonk/backups
    minio:
      endpoint: http://my-minio-workload:9000
      bucket: my-backup-bucket
      # REQUIRED PREREQUISITE SECRET when provider is `minio` — a `dictionary`
      # secret holding exactly `accessKey` and `secretKey`. See Backup setup
      # in the README.
      credentialsSecretName: my-listmonk-minio-credentials
      prefix: listmonk/backups

The HA store’s own tuning (Patroni resources, etcd compaction, PgBouncer) is documented on the PostgreSQL Highly Available page.

Connecting

What	Address	Notes
Public endpoint	`status.canonicalEndpoint` from `cpln workload get RELEASE_NAME-listmonk --gvc GVC_NAME -o yaml`	HTTPS, assigned automatically while `publicAccess.enabled: true`
Admin UI	`https://CANONICAL_ENDPOINT/admin`	Sign in with the `username` / `password` from your admin secret
Public subscription form	`https://CANONICAL_ENDPOINT/subscription/form`	What you link subscribers to
Health check	`https://CANONICAL_ENDPOINT/health`	Unauthenticated; `/api/health` requires a session, so do not use it for external monitors
HTTP API	`https://CANONICAL_ENDPOINT/api/...`	Authenticated; lists, subscribers, campaigns, transactional mail
Internal (same GVC)	`http://RELEASE_NAME-listmonk.GVC_NAME.cpln.local:9000`	Subject to `internalAccess.type`
Admin credentials	`cpln secret reveal ADMIN_SECRET_NAME -o yaml`	The secret you created in Prerequisites
Database (single mode)	`RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432`	Credentials from your `postgres.config.credentialsSecretName` secret: `cpln secret reveal DB_CREDENTIALS_SECRET_NAME -o yaml`
Database (HA mode)	`RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local:5432`	HAProxy leader endpoint; credentials from your `postgresHA.config.credentialsSecretName` secret

Read the public address once the workload is ready, then open /admin in your browser:

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

If you installed with publicAccess.enabled: false, reach the admin UI through a tunnel instead and open http://localhost:9000/admin:

cpln port-forward RELEASE_NAME-listmonk 9000:9000 --gvc GVC_NAME

First Run

There is no setup wizard — the schema is installed and the Super Admin exists when the workload reports ready. Sign in at /admin with the credentials from your admin secret, then finish the two settings listmonk keeps in its database rather than in Helm values:

Configure SMTP

In Settings → SMTP, add your mail provider (Amazon SES, SendGrid, Mailgun, Postmark, or any SMTP relay) and save. Until a working SMTP server is configured, no mail is delivered — a campaign still runs to completion, with every message failing to send.

Check the Root URL

In Settings → General, confirm the Root URL is the address your subscribers will use. On a public install the container has already set it to the canonical *.cpln.app endpoint (or to rootUrl if you set one); on a private install, or if the boot log shows a WARN could not set app.root_url line, set it here by hand. See Root URL for how the template manages it.

Choose a media store (optional)

Filesystem storage on the bundled uploads volume set works out of the box. To store media in S3-compatible object storage instead, switch the provider in Settings → Media.

Operations

Backing Up

Database backups are off by default. When enabled, a scheduled backup job runs inside the backing PostgreSQL store and uploads to your bucket under the configured prefix — covering lists, subscribers, campaigns, templates, and settings, but not the media on the uploads volume set. Enable with postgres.backup.enabled: true or postgresHA.backup.enabled: true to match your database mode, and complete the storage setup for your provider before installing. In HA mode, postgresHA.backup.mode selects logical (scheduled pg_dump) or wal-g (continuous WAL archiving).

AWS S3
Google Cloud Storage
S3-compatible (MinIO)

Create a bucket

Create an S3 bucket. Set backup.aws.bucket and backup.aws.region to match.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your AWS account. Set backup.aws.cloudAccountName to its name.

Create a bucket-scoped IAM policy

Create an IAM policy granting the required S3 actions on the bucket, and set backup.aws.policyName to its name:

{
  "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/*" }
  ]
}

Create a bucket

Create a GCS bucket. Set backup.gcp.bucket to its name.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your GCP project and grant its service account Storage Object Admin (roles/storage.objectAdmin) on the bucket. Set backup.gcp.cloudAccountName to its name.

Create a bucket

Create your bucket on the server. Set backup.minio.bucket to its name and backup.minio.endpoint to the S3 API address including port. No Cloud Account is required.

Create the MinIO credentials secret

In both database modes the keys are a prerequisite dictionary secret holding exactly accessKey and secretKey:

cpln secret create-dictionary --name MINIO_CREDENTIALS_SECRET_NAME \
  --entry accessKey='YOUR-MINIO-ACCESS-KEY' \
  --entry secretKey='YOUR-MINIO-SECRET-KEY'

Set backup.minio.credentialsSecretName to its name.

Media uploads are not part of the database backup. The uploads volume set takes a final snapshot when it is deleted (retained for 7 days), and you can snapshot it yourself at any time:

cpln volumeset snapshot create RELEASE_NAME-listmonk-uploads --gvc GVC_NAME --snapshot-name NAME

Restoring a Backup

A restore replays the SQL dump into the backing database from a client inside the GVC that can reach both the bucket and the database — the per-provider commands are on the PostgreSQL page for single mode and the PostgreSQL Highly Available page for HA mode. For this template, substitute the host RELEASE_NAME-postgres.GVC_NAME.cpln.local (single) or RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local (HA), and the username, password and database values from your database credentials secret.

This restore path has not been verified against a live install of this template; it is the backing store’s own documented procedure. Restore while listmonk is not serving campaigns, and expect to restart the listmonk workload afterwards so it re-reads its settings. Restoring the uploads volume set from a snapshot is likewise unverified here — see Volume Set snapshots.

Upgrading from 1.0.x

Version 1.1.0 moved the Super Admin login out of Helm values and into the prerequisite dictionary secret. An upgrade that still carries either removed key is refused at render, before anything is applied, with a message naming its replacement — there is no compatibility fallback.

Removed key	Replacement
`admin.username`	key `username` in the secret named by `admin.secretName`
`admin.password`	key `password` in the secret named by `admin.secretName`

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.

An existing install’s Super Admin password does not change on upgrade. The account was written to the database on the first install and the secret is never read again, so its contents only matter to a fresh install. Change the password in Admin → Users. If the install is still carrying the published 1.0.x default (change-me-listmonk-admin), treat that password as compromised and change it now.

Create the admin credentials secret

Follow Prerequisites. Putting your current credentials in it keeps your values file honest, but it does not re-seed the account.

Drop the removed keys from your values

Remove admin.username and admin.password, and set admin.secretName instead.

Upgrade

The single replica stops before the new one starts, so expect a brief gap. Lists, subscribers, campaigns, and uploaded media are on the database and the uploads volume set and are untouched.

Upgrading from 1.1.0

postgres.config.username, .password and .database were removed. Put the values your single-instance database was initialized with into the database credentials secret under Prerequisites (keys username, password, database), set postgres.config.credentialsSecretName to its name, and remove the three keys. With postgres.backup.provider: minio, postgres.backup.minio.accessKey / .secretKey were likewise removed — put them in a dictionary secret holding accessKey and secretKey as shown in Backing Up and set postgres.backup.minio.credentialsSecretName to its name.

Upgrading from 1.2.0

Version 1.3.0 adopted the postgres-highly-available 2.5.0 template for the HA path. It affects only installs with postgresHA.enabled: true; single-instance installs need no action. Put the values of postgresHA.postgres.username / .password / .database unchanged into the database credentials secret under Prerequisites, set postgresHA.config.credentialsSecretName to its name, and delete the postgres block under postgresHA. The HA database was initialized with those values; a different password only changes the secret, and listmonk then fails to log in to its own database. If you use MinIO backups on the HA path, create a dictionary secret holding accessKey and secretKey as shown in Backing Up and set postgresHA.backup.minio.credentialsSecretName to its name.

Upgrading from 1.3.1

Version 1.4.0 renamed the listmonk resource limits so it is unambiguous which number is the ceiling. An upgrade that still carries the old names is refused at render:

Removed key	Replacement
`resources.cpu`	`resources.maxCpu`
`resources.memory`	`resources.maxMemory`

Version 1.5.0 then added rootUrl and the boot-time Root URL handling described under Root URL; no values change is required for it. Then follow Upgrading from 1.5.0.

Upgrading from 1.5.0

Version 1.6.0 removed postgres.credentials: the database credentials are now a prerequisite secret, the same one the database templates require on their own. Carrying the old key forward fails the render. 1.5.0 created the database secret itself, so this upgrade deletes it. Before upgrading, create a secret under a new name holding the values your database was initialized with — not new ones, or listmonk loses its database connection:

cpln secret create-dictionary --name RELEASE_NAME-listmonk-db \
  --entry username=listmonk --entry password='YOUR_CURRENT_PASSWORD' --entry database=listmonk

Then upgrade with postgres.config.credentialsSecretName (single-instance mode) or postgresHA.config.credentialsSecretName (HA mode) set to that name, and postgres.credentials removed. Your current values are in postgres.credentials of the 1.5.0 release, and also in the old secret (cpln secret reveal SECRET_NAME -o yaml, where SECRET_NAME is the credentialsSecretName your release used, my-listmonk-db-credentials by default) until the upgrade deletes it. The upgrade restarts the bundled PostgreSQL too (it now reads the new secret), so listmonk can briefly lose its database; it reconnects by itself. While access to the new secret propagates, the new version of a workload can wait in get-deployments reporting that it is not allowed to reveal the secret; the previous version keeps serving meanwhile, and it clears by itself.

Upgrading from 1.6.0 or earlier

1.6.1 moves the HA database (postgresHA) to controlplanecorporation/patroni-postgres:0.8, which carries pgvector 0.8.7 (CVE-2026-103484). The fix takes effect when the upgrade restarts the Patroni members; existing data needs nothing. Nothing limits that rollout, so expect a brief interruption of writes while the leader changes. listmonk itself restarts as on any upgrade, which is the longer interruption, because its single replica stops before the new one serves; a few writes on already-open database connections can also fail right after the leader change. Upgrade in a quiet window. If you pinned postgresHA.image in your values, set it to the 0.8 tag: tags 0.1 to 0.7 are refused at render. listmonk does not use the vector extension; if you created it yourself in a database, \dx keeps reporting the old version until you run ALTER EXTENSION vector UPDATE; there, which only updates that record. Single-instance mode (postgres) is unchanged.

Rotating the Database Password

A running workload keeps the credential values it started with, and PostgreSQL reads the secret only when its data is first initialized, so editing the secret alone does not change the database password. Change one key and keep the others with export, edit, apply:

cpln secret reveal SECRET_NAME -o yaml > secret.yaml
# edit only the key you are rotating in secret.yaml
cpln apply -f secret.yaml
cpln secret reveal SECRET_NAME -o yaml

Single-instance mode: run ALTER ROLE for the secret’s username in the database first, then update the secret, then right away force a redeployment of RELEASE_NAME-listmonk. Do not redeploy the database; restarting it only adds downtime.

cpln workload force-redeployment RELEASE_NAME-listmonk --gvc GVC_NAME

HA mode needs its own order. The replication role repl shares the password, and a member that restarts with the old password can be promoted to leader, which splits the cluster. Move the leader to member -0 first, so it restarts last, after every other member already has the new password. pgx runs a command in one member (LOCATION is your GVC’s location, DB_USERNAME the secret’s username):

pgx() { cpln workload exec RELEASE_NAME-postgres-ha --gvc GVC_NAME --location LOCATION \
  --container patroni-postgres --replica "RELEASE_NAME-postgres-ha-$1" -- "${@:2}"; }
# 1. Find the leader ("role": "leader"); the other two must be "streaming" on the same "timeline"
pgx 0 curl -s localhost:8008/cluster
# 2. If the leader is not RELEASE_NAME-postgres-ha-0, move it there (N = current leader), then repeat step 1
pgx 0 curl -s -XPOST -d '{"leader":"RELEASE_NAME-postgres-ha-N","candidate":"RELEASE_NAME-postgres-ha-0"}' localhost:8008/switchover
# 3. Back to back: change BOTH roles on -0, put the same password in the secret (export, edit, apply above), restart the members
pgx 0 psql -h 127.0.0.1 -d postgres -c "ALTER ROLE DB_USERNAME PASSWORD 'NEW_PASSWORD'; ALTER ROLE repl PASSWORD 'NEW_PASSWORD';"
cpln workload force-redeployment RELEASE_NAME-postgres-ha --gvc GVC_NAME
# 4. Once the members are back, confirm one leader and two "streaming" replicas on one timeline (repeat step 1)
# 5. Optional: remove the install-time password Patroni keeps in its cluster config
pgx 0 curl -s -XPATCH -d '{"postgresql":{"authentication":null}}' localhost:8008/config

Then force-redeploy RELEASE_NAME-listmonk, which keeps the old password until it restarts. The app cannot open new database connections from the ALTER ROLE until its own redeploy finishes, so rotate in a quiet window. If a member stays starting, or running without streaming, re-copy it from the leader. This copies the whole database, so it costs network traffic in proportion to its size:

pgx N curl -s -XPOST -d '{"force": true}' localhost:8008/reinitialize

Scaling and Availability

Listmonk is a single instance by design — there is no replicas knob. Listmonk runs its campaign workers in-process, and upstream allows only one instance per database: two 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 — so an upgrade or restart causes a brief gap in availability rather than overlapping senders. Do not hand-scale the workload or point a second copy at the same database.
Database availability is the one knob you have. The default single-instance store restarts on upgrade and reschedules on node failure; postgresHA.enabled: true gives a three-replica cluster with automatic failover — see Highly Available PostgreSQL.
The first cpln helm upgrade after an install may restart the bundled database even when nothing changed; listmonk waits for it and comes back on its own.

Troubleshooting

Workload never starts and cpln logs returns zero lines

Cause: the secret named by admin.secretName, or the database credentials secret, did not exist at install time. The container never ran, so there is no output to log. A missing database secret shows the same way on RELEASE_NAME-postgres (or RELEASE_NAME-postgres-ha).Fix: read the one place the reason appears:

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

The secret ADMIN_SECRET_NAME no longer exists. Workload updates are paused until
the secret is added or the reference to the secret removed.

Create the secret as shown in Prerequisites. The deployment recovers on its own, or run cpln workload force-redeployment RELEASE_NAME-listmonk --gvc GVC_NAME to pick it up immediately.

Container exits immediately with a message naming the admin secret

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

Cause: the username is under 3 characters or the password under 8. Upstream’s install step would otherwise fail on every attempt inside the database-wait loop, which looks like a database problem — so the container checks the lengths first and names the real cause.Fix: update the secret with compliant values, then force a redeployment:

cpln workload force-redeployment RELEASE_NAME-listmonk --gvc GVC_NAME

Boot log repeats waiting for database

listmonk: waiting for database...

Cause: PostgreSQL is not accepting connections yet. A few of these lines on a fresh install are normal while the database initializes (the HA store also needs its leader endpoint to settle). If they continue indefinitely, listmonk cannot authenticate — typically because the database credentials secret was changed after the database volume was first initialized, so listmonk presents a password the database never received.Fix: check the database workload with cpln workload get-deployments RELEASE_NAME-postgres --gvc GVC_NAME -o yaml (or RELEASE_NAME-postgres-ha in HA mode). If the secret was changed after the first boot, restore the original values or follow Rotating the Database Password; the password is applied to the database on its first boot only.

Subscription, unsubscribe or tracking links point at localhost:9000

Cause: listmonk’s Root URL is still the fresh-install default. On a public install the container sets it at boot; if that step could not run, the boot log carries a WARN could not set app.root_url line. On a private install (publicAccess.enabled: false with no rootUrl) nothing sets it.Fix: set rootUrl to the address subscribers use (or correct it in Settings → General) — see Root URL. Check the boot log with:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-listmonk"} |= "root_url"' --limit 50 --since 10m

Campaign finishes with zero messages sent

Cause: no SMTP server is configured. Listmonk stores SMTP settings in its database, not in boot configuration, so a fresh install cannot deliver mail; each message fails individually and the campaign still completes.Fix: add your provider in Settings → SMTP (see First Run) and start the campaign again.

Upgrade is refused at render naming a removed key

Cause: your values file still carries a key removed in a later version — admin.username / admin.password (1.1.0), postgres.config.username / .password / .database (1.2.0), resources.cpu / resources.memory (1.4.0), or postgres.credentials (1.6.0). Each guard names its replacement, and nothing is applied, so the running release is untouched.Fix: follow the matching subsection above — 1.0.x, 1.1.0, 1.3.1, or 1.5.0 — then upgrade again.

Important Notes

Create the admin and database credentials secrets before installing. A reference to a secret that does not exist wedges the workload with zero log lines; see Prerequisites for the one command that shows the reason.
The Super Admin is created on first boot only. Editing the secret later does not change the account, and upgrades never change your existing password — manage users in Admin → Users.
Editing the database credentials secret does not change the database password. Run ALTER ROLE first and then force-redeploy listmonk; in HA mode move the leader first — see Rotating the Database Password.
Give each listmonk release in an org its own database credentials secret. Secret names are org-wide, so two releases pointed at one secret share a password.
Do not scale listmonk past one replica or point a second instance at the same database — duplicate campaign sends result. See Scaling and Availability.
No mail is delivered until SMTP is configured in Settings → SMTP. Starting a campaign before that is not an error — it finishes with nothing sent.
Keep publicAccess enabled for subscriber-facing pages to work, and keep the Root URL equal to the address subscribers use — see Root URL.
Use /health for external health checks, not /api/health, which requires an authenticated session.
Data lives on the volume sets and survives redeploys and upgrades; cpln helm uninstall deletes them — all lists, subscribers, campaigns, and media go with the release. Enable backups for production data.

External References

Listmonk Documentation

Official listmonk documentation

Configuration Reference

Settings, SMTP options, and filesystem or S3 media storage

Concepts

How lists, subscribers, campaigns, and templates fit together

API Reference

Manage lists, subscribers, and campaigns over HTTP

Listmonk Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Application

Admin Bootstrap

Root URL

Access

Single-Instance PostgreSQL

Highly Available PostgreSQL

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Upgrading from 1.0.x

Upgrading from 1.1.0

Upgrading from 1.2.0

Upgrading from 1.3.1

Upgrading from 1.5.0

Upgrading from 1.6.0 or earlier

Rotating the Database Password

Scaling and Availability

Troubleshooting

Important Notes

External References

Listmonk Documentation

Configuration Reference

Concepts

API Reference

Listmonk Template