Skip to content
Listmonk icon
v1.2.5App: v6.2.0Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Listmonk Helm Chart

Deploy Listmonk, a self-hosted newsletter and mailing list manager, on Kubernetes with the official docker.io/listmonk/listmonk:v6.2.0 image, a PostgreSQL backend, persistent uploads, and optional S3-compatible database backups.

Features

  • Ready on first start: init containers run listmonk --install --idempotent and --upgrade, and create the superadmin from a Secret
  • Hardened pod: non-root uid 65534, read-only root filesystem, no privilege escalation, every capability dropped, RuntimeDefault seccomp
  • PostgreSQL backend: HelmForge PostgreSQL subchart or an external server
  • Configurable listener: listmonk.port changes the real HTTP listener
  • Persistent uploads mounted at /listmonk/uploads
  • Exposure: Ingress or Gateway API HTTPRoutes
  • S3 backups: scheduled pg_dump archives uploaded to S3-compatible storage
  • External Secrets Operator integration for credentials

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install listmonk helmforge/listmonk

OCI registry:

helm install listmonk oci://ghcr.io/helmforgedev/helm/listmonk

Quick Start

helm install listmonk helmforge/listmonk
kubectl rollout status deploy/listmonk --timeout=300s
kubectl get secret listmonk-admin -o jsonpath='{.data.admin-password}' | base64 -d; echo
kubectl port-forward svc/listmonk 9000:80

Open http://localhost:9000/admin and log in as admin with the password above, then configure SMTP under Settings > SMTP. A release whose name contains listmonk uses it as the resource prefix; other releases use <release>-listmonk.

Architecture

The pod runs wait-for-postgresql (pg_isready with a timeout), db-init (idempotent install, superadmin creation on a fresh database, and upgrade), and the listmonk container. See DESIGN.md, docs/architecture.md, and docs/operations.md.

Configuration

Application

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Database

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

External databases must let the Listmonk user create objects and the pgcrypto extension, or provide it beforehand.

Exposure, probes, storage, and backups

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Every key is documented in values.yaml and validated by values.schema.json.

Examples

Security

  • The pod runs as uid 65534 with a read-only root filesystem, no privilege escalation, no capabilities, RuntimeDefault seccomp, and no ServiceAccount token. /tmp and /listmonk/uploads are the only writable paths.
  • The superadmin is created from a Secret on a fresh database, so the instance never exposes the first-run admin setup page.
  • Credentials accept existing Secrets or ExternalSecret resources.
  • The generated superadmin password is read back with lookup on upgrade. Renderers without cluster access (client-side GitOps rendering) generate a new value on every render; set listmonk.admin.password or listmonk.admin.existingSecret in those setups.
  • Add NetworkPolicies for your cluster; the chart does not render them.

Troubleshooting

Symptom Check
Pod stuck in Init:0/2 kubectl logs deploy/<name> -c wait-for-postgresql; the database is unreachable
Pod stuck in Init:1/2 kubectl logs deploy/<name> -c db-init; credentials or privileges are wrong
Login rejected after reinstall The password applies only to a fresh database; read <name>-admin from the first install
Backup job fails with a version mismatch Set backup.images.postgresql to a client at least as new as the server

More Information

Security Scan: listmonk

Framework Score
MITRE + NSA + SOC2 90.90909%

Security posture acceptable.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  user[Admins and subscribers] --> edge[Ingress or HTTPRoute]
  edge --> svc[Service http]
  svc --> app[listmonk container]
  subgraph pod[Listmonk pod]
    wait[wait-for-postgresql] --> init[db-init]
    init --> app
  end
  wait --> db[(PostgreSQL)]
  init --> db
  app --> db
  app --> pvc[(uploads PVC)]
  backup[backup CronJob] --> db
  backup --> s3[(S3 bucket)]
Official Contractvalues.schema.json

Listmonk Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

115 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring""Override the chart name used in resource names

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring""Override the full release name used in resource names

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to every resource created by this chart

Replica Count(1)

ParameterTypeDefaultDescription
replicaCountinteger1Number of Listmonk application replicas. Keep 1: several active instances

Image(3)

ParameterTypeDefaultDescription
image.repositorystringdocker.io/listmonk/listmonkListmonk container image repository
image.tagstringv6.2.0Listmonk image tag (pinned; floating tags are rejected)
image.pullPolicystringIfNotPresentImage pull policy
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets for private registries

Listmonk(6)

ParameterTypeDefaultDescription
listmonk.portinteger9000HTTP listener inside the container (LISTMONK_app__address)
listmonk.extraEnvarray-Additional environment variables for the Listmonk and db-init containers
listmonk.admin.usernamestringadminSuperadmin username created by the first --install (at least 3 characters)
listmonk.admin.passwordstring""Superadmin password (at least 8 characters); generated once when empty
listmonk.admin.existingSecretstring""Existing Secret with the superadmin password
listmonk.admin.existingSecretPasswordKeystringadmin-passwordKey in listmonk.admin.existingSecret

Setup(3)

ParameterTypeDefaultDescription
setup.waitImagestringdocker.io/library/postgres:18.6-alpinePostgreSQL client image used to wait for the database
setup.databaseWaitTimeoutSecondsinteger300Seconds the wait-for-postgresql init container waits for the database
setup.resourcesobject-Resources for the init containers

Database(9)

ParameterTypeDefaultDescription
database.modestringautoDatabase mode: auto | external | postgresql
Allowed:autoexternalpostgresql
database.external.hoststring""External PostgreSQL hostname
database.external.portstringinteger5432External PostgreSQL port
database.external.namestringlistmonkExternal PostgreSQL database name
database.external.usernamestringlistmonkExternal PostgreSQL username
database.external.passwordstring""External PostgreSQL password. Ignored when existingSecret is set.
database.external.sslModestringdisablePostgreSQL SSL mode
Allowed:disableallowpreferrequireverify-caverify-full
database.external.existingSecretstring""Existing secret containing the external PostgreSQL password
database.external.existingSecretPasswordKeystringdatabase-passwordSecret key for the external PostgreSQL password

Postgresql(9)

ParameterTypeDefaultDescription
postgresql.enabledbooleantrueChart configuration parameter
postgresql.architecturestringstandaloneChart configuration parameter
postgresql.auth.databasestringlistmonkPostgreSQL database name created on first run
postgresql.auth.usernamestringlistmonkPostgreSQL username created on first run
postgresql.auth.passwordstring""PostgreSQL application user password. Auto-generated if empty.
postgresql.auth.postgresPasswordstring""PostgreSQL superuser password. Auto-generated if empty.
postgresql.initdb.scripts.10-listmonk-bootstrap.sqlstringGRANT CREATE ON DATABASE listmonk TO listmonk; \connect listmonk CREATE EXTENSION IF NOT EXISTS pgcrypto; Bootstrap Listmonk database privileges and extensions on first PostgreSQL initialization.
postgresql.standalone.persistence.enabledbooleantrueEnable persistence for PostgreSQL data
postgresql.standalone.persistence.sizestring8GiPVC size for PostgreSQL

Storage(6)

ParameterTypeDefaultDescription
storage.enabledbooleantrueEnable persistent local storage for uploaded media
storage.storageClassstring""Storage class for the uploads PVC
storage.accessModestringReadWriteOnceAccess mode for the uploads PVC
Allowed:ReadWriteOnceReadOnlyManyReadWriteManyReadWriteOncePod
storage.sizestring5GiSize of the uploads PVC
storage.existingClaimstring""Existing PVC claim for uploads storage
storage.annotationsobject-Annotations for the uploads PVC

Backup(21)

ParameterTypeDefaultDescription
backup.enabledbooleanfalseEnable built-in backup CronJob for PostgreSQL (pg_dump to S3)
backup.schedulestring0 3 * * *Backup schedule in Cron format
backup.suspendbooleanfalseSuspend backup execution
backup.concurrencyPolicystringForbidCronJob concurrency policy
Allowed:AllowForbidReplace
backup.successfulJobsHistoryLimitinteger3Successful job history retained by the CronJob
backup.failedJobsHistoryLimitinteger3Failed job history retained by the CronJob
backup.backoffLimitinteger1Job backoff limit
backup.archivePrefixstringlistmonkPrefix used in generated backup archive names
backup.images.postgresqlstringdocker.io/library/postgres:18.6-alpinePostgreSQL client image used for pg_dump (must not be older than the server)
backup.images.uploaderstringdocker.io/helmforge/mc:1.0.0MinIO client image used for S3 upload
backup.resourcesobject-Resources applied to the backup dump and upload containers
backup.database.pgDumpArgsstring""Extra arguments passed to pg_dump
backup.s3.endpointstring""S3-compatible endpoint URL
backup.s3.bucketstring""Target bucket name
backup.s3.prefixstringlistmonkOptional key prefix inside the bucket
backup.s3.createBucketIfNotExistsbooleantrueCreate the bucket automatically when it does not exist yet
backup.s3.existingSecretstring""Existing secret containing access-key and secret-key
backup.s3.existingSecretAccessKeyKeystringaccess-keySecret key name for the access key inside backup.s3.existingSecret
backup.s3.existingSecretSecretKeyKeystringsecret-keySecret key name for the secret key inside backup.s3.existingSecret
backup.s3.accessKeystring""Inline access key used when backup.s3.existingSecret is not set
backup.s3.secretKeystring""Inline secret key used when backup.s3.existingSecret is not set

Service & Networking(3)

ParameterTypeDefaultDescription
service.typestringClusterIPService type for the Listmonk HTTP service
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger80Service port exposed by the Listmonk service
service.annotationsobject-Annotations for the Listmonk service

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledbooleanfalseEnable ingress for Listmonk
ingress.ingressClassNamestring""Ingress class name
ingress.annotationsobject-Ingress annotations
ingress.hostsarray-Ingress hosts
ingress.tlsarray-Ingress TLS configuration

Gateway API(2)

ParameterTypeDefaultDescription
gatewayAPI.enabledbooleanfalseRender Gateway API HTTPRoute resources
gatewayAPI.httpRoutesarray-HTTPRoute definitions routed to the Listmonk Service by default

Startup Probe(6)

ParameterTypeDefaultDescription
startupProbe.enabledbooleantrueEnable startup probe
startupProbe.pathstring/healthHTTP path used by the startup probe
startupProbe.initialDelaySecondsinteger5Startup probe initial delay
startupProbe.periodSecondsinteger5Startup probe period
startupProbe.timeoutSecondsinteger3Startup probe timeout
startupProbe.failureThresholdinteger30Startup probe failure threshold

Liveness Probe(6)

ParameterTypeDefaultDescription
livenessProbe.enabledbooleantrueEnable liveness probe
livenessProbe.pathstring/healthHTTP path used by the liveness probe
livenessProbe.initialDelaySecondsinteger0Liveness probe initial delay
livenessProbe.periodSecondsinteger30Liveness probe period
livenessProbe.timeoutSecondsinteger5Liveness probe timeout
livenessProbe.failureThresholdinteger3Liveness probe failure threshold

Readiness Probe(6)

ParameterTypeDefaultDescription
readinessProbe.enabledbooleantrueEnable readiness probe
readinessProbe.pathstring/healthHTTP path used by the readiness probe
readinessProbe.initialDelaySecondsinteger0Readiness probe initial delay
readinessProbe.periodSecondsinteger10Readiness probe period
readinessProbe.timeoutSecondsinteger3Readiness probe timeout
readinessProbe.failureThresholdinteger3Readiness probe failure threshold

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-CPU and memory requests/limits for the Listmonk container

Pod Security(1)

ParameterTypeDefaultDescription
podSecurityContextobject-Pod security context

Container Security(1)

ParameterTypeDefaultDescription
securityContextobject-Container security context for the Listmonk and init containers

Automount Service Account Token(1)

ParameterTypeDefaultDescription
automountServiceAccountTokenbooleanfalseMount the ServiceAccount token (Listmonk does not call the Kubernetes API)

Service Account(3)

ParameterTypeDefaultDescription
serviceAccount.createbooleanfalseCreate a dedicated ServiceAccount
serviceAccount.namestring""ServiceAccount name override
serviceAccount.annotationsobject-Annotations for the ServiceAccount

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Node selector for pod scheduling

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Tolerations for pod scheduling

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Affinity rules for pod scheduling

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring""Priority class name

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger30Grace period for shutdown, in seconds

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Additional labels for the Listmonk pod

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Additional annotations for the Listmonk pod

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Additional volume mounts for the Listmonk container

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Additional volumes for the Listmonk pod

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Extra Kubernetes manifests to deploy alongside the chart

External Secrets(7)

ParameterTypeDefaultDescription
externalSecrets.enabledbooleanfalseEnable External Secrets Operator integration
externalSecrets.secretStoreRef.namestring""SecretStore name
externalSecrets.secretStoreRef.kindstringSecretStoreSecretStore kind (SecretStore or ClusterSecretStore)
Allowed:SecretStoreClusterSecretStore
externalSecrets.refreshIntervalstring1hDefault refresh interval for external secrets
externalSecrets.creationPolicystringOwnerCreation policy for target secrets (Owner, Merge, None)
Allowed:OwnerMergeNoneOrphan
externalSecrets.deletionPolicystringRetainDeletion policy for target secrets (Retain, Delete, Merge)
Allowed:RetainDeleteMerge
externalSecrets.itemsarray-List of ExternalSecret resources to create