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 --idempotentand--upgrade, and create the superadmin from a Secret - Hardened pod: non-root uid 65534, read-only root filesystem, no
privilege escalation, every capability dropped,
RuntimeDefaultseccomp - PostgreSQL backend: HelmForge PostgreSQL subchart or an external server
- Configurable listener:
listmonk.portchanges the real HTTP listener - Persistent uploads mounted at
/listmonk/uploads - Exposure: Ingress or Gateway API HTTPRoutes
- S3 backups: scheduled
pg_dumparchives 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
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.
Database
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.
External databases must let the Listmonk user create objects and the
pgcrypto extension, or provide it beforehand.
Exposure, probes, storage, and backups
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.
Every key is documented in values.yaml and validated by
values.schema.json.
Examples
- examples/simple.yaml: bundled PostgreSQL with persistent uploads
- examples/ingress.yaml: TLS Ingress and explicit resources
- examples/external-db.yaml: managed external PostgreSQL
- examples/backup.yaml: S3-compatible PostgreSQL backups
Security
- The pod runs as uid 65534 with a read-only root filesystem, no privilege
escalation, no capabilities,
RuntimeDefaultseccomp, and no ServiceAccount token./tmpand/listmonk/uploadsare 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
lookupon upgrade. Renderers without cluster access (client-side GitOps rendering) generate a new value on every render; setlistmonk.admin.passwordorlistmonk.admin.existingSecretin 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 SyncedVerified 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)]Listmonk Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global settings shared by the chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | "" | Override the chart name used in resource names |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | "" | Override the full release name used in resource names |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Labels added to every resource created by this chart |
Replica Count(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| replicaCount | integer | 1 | Number of Listmonk application replicas. Keep 1: several active instances |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | docker.io/listmonk/listmonk | Listmonk container image repository |
| image.tag | string | v6.2.0 | Listmonk image tag (pinned; floating tags are rejected) |
| image.pullPolicy | string | IfNotPresent | Image pull policy Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Image pull secrets for private registries |
Listmonk(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| listmonk.port | integer | 9000 | HTTP listener inside the container (LISTMONK_app__address) |
| listmonk.extraEnv | array | - | Additional environment variables for the Listmonk and db-init containers |
| listmonk.admin.username | string | admin | Superadmin username created by the first --install (at least 3 characters) |
| listmonk.admin.password | string | "" | Superadmin password (at least 8 characters); generated once when empty |
| listmonk.admin.existingSecret | string | "" | Existing Secret with the superadmin password |
| listmonk.admin.existingSecretPasswordKey | string | admin-password | Key in listmonk.admin.existingSecret |
Setup(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| setup.waitImage | string | docker.io/library/postgres:18.6-alpine | PostgreSQL client image used to wait for the database |
| setup.databaseWaitTimeoutSeconds | integer | 300 | Seconds the wait-for-postgresql init container waits for the database |
| setup.resources | object | - | Resources for the init containers |
Database(9)
| Parameter | Type | Default | Description |
|---|---|---|---|
| database.mode | string | auto | Database mode: auto | external | postgresql Allowed: autoexternalpostgresql |
| database.external.host | string | "" | External PostgreSQL hostname |
| database.external.port | stringinteger | 5432 | External PostgreSQL port |
| database.external.name | string | listmonk | External PostgreSQL database name |
| database.external.username | string | listmonk | External PostgreSQL username |
| database.external.password | string | "" | External PostgreSQL password. Ignored when existingSecret is set. |
| database.external.sslMode | string | disable | PostgreSQL SSL mode Allowed: disableallowpreferrequireverify-caverify-full |
| database.external.existingSecret | string | "" | Existing secret containing the external PostgreSQL password |
| database.external.existingSecretPasswordKey | string | database-password | Secret key for the external PostgreSQL password |
Postgresql(9)
| Parameter | Type | Default | Description |
|---|---|---|---|
| postgresql.enabled | boolean | true | Chart configuration parameter |
| postgresql.architecture | string | standalone | Chart configuration parameter |
| postgresql.auth.database | string | listmonk | PostgreSQL database name created on first run |
| postgresql.auth.username | string | listmonk | PostgreSQL username created on first run |
| postgresql.auth.password | string | "" | PostgreSQL application user password. Auto-generated if empty. |
| postgresql.auth.postgresPassword | string | "" | PostgreSQL superuser password. Auto-generated if empty. |
| postgresql.initdb.scripts.10-listmonk-bootstrap.sql | string | GRANT 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.enabled | boolean | true | Enable persistence for PostgreSQL data |
| postgresql.standalone.persistence.size | string | 8Gi | PVC size for PostgreSQL |
Storage(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| storage.enabled | boolean | true | Enable persistent local storage for uploaded media |
| storage.storageClass | string | "" | Storage class for the uploads PVC |
| storage.accessMode | string | ReadWriteOnce | Access mode for the uploads PVC Allowed: ReadWriteOnceReadOnlyManyReadWriteManyReadWriteOncePod |
| storage.size | string | 5Gi | Size of the uploads PVC |
| storage.existingClaim | string | "" | Existing PVC claim for uploads storage |
| storage.annotations | object | - | Annotations for the uploads PVC |
Backup(21)
| Parameter | Type | Default | Description |
|---|---|---|---|
| backup.enabled | boolean | false | Enable built-in backup CronJob for PostgreSQL (pg_dump to S3) |
| backup.schedule | string | 0 3 * * * | Backup schedule in Cron format |
| backup.suspend | boolean | false | Suspend backup execution |
| backup.concurrencyPolicy | string | Forbid | CronJob concurrency policy Allowed: AllowForbidReplace |
| backup.successfulJobsHistoryLimit | integer | 3 | Successful job history retained by the CronJob |
| backup.failedJobsHistoryLimit | integer | 3 | Failed job history retained by the CronJob |
| backup.backoffLimit | integer | 1 | Job backoff limit |
| backup.archivePrefix | string | listmonk | Prefix used in generated backup archive names |
| backup.images.postgresql | string | docker.io/library/postgres:18.6-alpine | PostgreSQL client image used for pg_dump (must not be older than the server) |
| backup.images.uploader | string | docker.io/helmforge/mc:1.0.0 | MinIO client image used for S3 upload |
| backup.resources | object | - | Resources applied to the backup dump and upload containers |
| backup.database.pgDumpArgs | string | "" | Extra arguments passed to pg_dump |
| backup.s3.endpoint | string | "" | S3-compatible endpoint URL |
| backup.s3.bucket | string | "" | Target bucket name |
| backup.s3.prefix | string | listmonk | Optional key prefix inside the bucket |
| backup.s3.createBucketIfNotExists | boolean | true | Create the bucket automatically when it does not exist yet |
| backup.s3.existingSecret | string | "" | Existing secret containing access-key and secret-key |
| backup.s3.existingSecretAccessKeyKey | string | access-key | Secret key name for the access key inside backup.s3.existingSecret |
| backup.s3.existingSecretSecretKeyKey | string | secret-key | Secret key name for the secret key inside backup.s3.existingSecret |
| backup.s3.accessKey | string | "" | Inline access key used when backup.s3.existingSecret is not set |
| backup.s3.secretKey | string | "" | Inline secret key used when backup.s3.existingSecret is not set |
Service & Networking(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | ClusterIP | Service type for the Listmonk HTTP service Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | 80 | Service port exposed by the Listmonk service |
| service.annotations | object | - | Annotations for the Listmonk service |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | false | Enable ingress for Listmonk |
| ingress.ingressClassName | string | "" | Ingress class name |
| ingress.annotations | object | - | Ingress annotations |
| ingress.hosts | array | - | Ingress hosts |
| ingress.tls | array | - | Ingress TLS configuration |
Gateway API(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gatewayAPI.enabled | boolean | false | Render Gateway API HTTPRoute resources |
| gatewayAPI.httpRoutes | array | - | HTTPRoute definitions routed to the Listmonk Service by default |
Startup Probe(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| startupProbe.enabled | boolean | true | Enable startup probe |
| startupProbe.path | string | /health | HTTP path used by the startup probe |
| startupProbe.initialDelaySeconds | integer | 5 | Startup probe initial delay |
| startupProbe.periodSeconds | integer | 5 | Startup probe period |
| startupProbe.timeoutSeconds | integer | 3 | Startup probe timeout |
| startupProbe.failureThreshold | integer | 30 | Startup probe failure threshold |
Liveness Probe(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| livenessProbe.enabled | boolean | true | Enable liveness probe |
| livenessProbe.path | string | /health | HTTP path used by the liveness probe |
| livenessProbe.initialDelaySeconds | integer | 0 | Liveness probe initial delay |
| livenessProbe.periodSeconds | integer | 30 | Liveness probe period |
| livenessProbe.timeoutSeconds | integer | 5 | Liveness probe timeout |
| livenessProbe.failureThreshold | integer | 3 | Liveness probe failure threshold |
Readiness Probe(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| readinessProbe.enabled | boolean | true | Enable readiness probe |
| readinessProbe.path | string | /health | HTTP path used by the readiness probe |
| readinessProbe.initialDelaySeconds | integer | 0 | Readiness probe initial delay |
| readinessProbe.periodSeconds | integer | 10 | Readiness probe period |
| readinessProbe.timeoutSeconds | integer | 3 | Readiness probe timeout |
| readinessProbe.failureThreshold | integer | 3 | Readiness probe failure threshold |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | CPU and memory requests/limits for the Listmonk container |
Pod Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext | object | - | Pod security context |
Container Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext | object | - | Container security context for the Listmonk and init containers |
Automount Service Account Token(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| automountServiceAccountToken | boolean | false | Mount the ServiceAccount token (Listmonk does not call the Kubernetes API) |
Service Account(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | false | Create a dedicated ServiceAccount |
| serviceAccount.name | string | "" | ServiceAccount name override |
| serviceAccount.annotations | object | - | Annotations for the ServiceAccount |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Node selector for pod scheduling |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Tolerations for pod scheduling |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Affinity rules for pod scheduling |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | "" | Priority class name |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | 30 | Grace period for shutdown, in seconds |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Additional labels for the Listmonk pod |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Additional annotations for the Listmonk pod |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Additional volume mounts for the Listmonk container |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Additional volumes for the Listmonk pod |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Extra Kubernetes manifests to deploy alongside the chart |
External Secrets(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalSecrets.enabled | boolean | false | Enable External Secrets Operator integration |
| externalSecrets.secretStoreRef.name | string | "" | SecretStore name |
| externalSecrets.secretStoreRef.kind | string | SecretStore | SecretStore kind (SecretStore or ClusterSecretStore) Allowed: SecretStoreClusterSecretStore |
| externalSecrets.refreshInterval | string | 1h | Default refresh interval for external secrets |
| externalSecrets.creationPolicy | string | Owner | Creation policy for target secrets (Owner, Merge, None) Allowed: OwnerMergeNoneOrphan |
| externalSecrets.deletionPolicy | string | Retain | Deletion policy for target secrets (Retain, Delete, Merge) Allowed: RetainDeleteMerge |
| externalSecrets.items | array | - | List of ExternalSecret resources to create |
No schema parameters match your search
Try searching for a different keyword or reset the filter.