Skip to content
Wallabag icon
v1.3.14App: v2.6.14Pinned DigestS3 Backup Ready

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

Wallabag Helm Chart

Deploy Wallabag on Kubernetes with the official wallabag/wallabag image. Wallabag is a self-hosted read-it-later application: save articles from the web, strip distractions, and read them in the browser, mobile apps, or e-readers.

Features

  • Working first install: a setup init container installs the Wallabag schema on first start and runs Doctrine migrations on every upgrade
  • Initial super-admin from a Secret: username, email, and a generated or supplied password; no wallabag/wallabag default account is left behind
  • PostgreSQL backend: HelmForge PostgreSQL subchart or an external server
  • Optional Redis: subchart or external instance for the asynchronous import queue
  • Stable secrets: the Symfony secret and admin password survive helm upgrade
  • Configurable listener: wallabag.port changes the real nginx listener
  • Exposure: Ingress or Gateway API HTTPRoutes
  • S3 backups: scheduled pg_dump archives uploaded to S3-compatible storage
  • Hardened defaults: no privilege escalation, minimal capabilities, RuntimeDefault seccomp, no ServiceAccount token

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install wallabag helmforge/wallabag \
  --set wallabag.domainName=https://wallabag.example.com

OCI registry:

helm install wallabag oci://ghcr.io/helmforgedev/helm/wallabag \
  --set wallabag.domainName=https://wallabag.example.com

Quick Start

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

Open http://localhost:8080/ and log in as wallabag with the password above. Resource names follow <release>-wallabag, so the release wallabag creates wallabag-wallabag.

Architecture

The pod runs a setup init container and the wallabag container, both from the same image. The setup container waits for PostgreSQL, installs the schema when wallabag_internal_setting is missing, configures the initial super-admin once, and applies pending migrations on later starts. The main container runs nginx and PHP-FPM under the upstream s6 supervisor. See DESIGN.md for the full design and its boundaries.

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 and Redis

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

See docs/external-database.md for managed PostgreSQL and docs/configuration.md for Redis and listener details.

Exposure, probes, and storage

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

Backup settings are documented in docs/backup-restore.md. Every key is listed in values.yaml and validated by values.schema.json.

Examples

Security

  • The upstream image starts as root and drops to nobody for PHP-FPM, so runAsNonRoot and a read-only root filesystem are not supported. The chart disables privilege escalation, drops every capability the image does not need, applies the RuntimeDefault seccomp profile, and does not mount a ServiceAccount token.
  • Every credential is read from a Secret and accepts an existing Secret.
  • Registration is disabled by default. Enable it only when the instance is meant to be public.

Troubleshooting

Symptom Check
Pod stuck in Init:0/1 kubectl logs deploy/<release>-wallabag -c setup; PostgreSQL is not reachable or the credentials are wrong
HTTP 500 on every page The schema is missing; confirm setup.enabled=true and read the setup logs
Login rejected after install Read the password from <release>-wallabag-admin; it applies only to the first install
Container exits with Unable to configure the nginx listener The image changed its nginx configuration; pin a supported image.tag

More Information

Security Scan: wallabag

Framework Score
MITRE + NSA + SOC2 87.878784%

Security posture acceptable.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  user[Browser, apps, extensions] --> edge[Ingress or HTTPRoute]
  edge --> svc[Service http]
  svc --> pod
  subgraph pod[Wallabag pod]
    setup[init: setup] --> app[nginx + PHP-FPM]
  end
  setup --> pg[(PostgreSQL)]
  app --> pg
  app -.optional.-> redis[(Redis import queue)]
  app --> pvc[(PVC /var/www/wallabag/data)]
  cron[backup CronJob] --> pg
  cron --> s3[(S3 bucket)]
Official Contractvalues.schema.json

Wallabag Values Schema Reference

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

121 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 resource name prefix

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to every rendered resource

Image(3)

ParameterTypeDefaultDescription
image.repositorystringdocker.io/wallabag/wallabagWallabag container image
image.tagstring2.6.14Image tag
image.pullPolicystringIfNotPresentImage pull policy
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets for private registries

Wallabag(13)

ParameterTypeDefaultDescription
wallabag.portinteger80Port the bundled nginx listener binds inside the container
wallabag.domainNamestringhttps://wallabag.example.comPublic URL users reach Wallabag through (scheme and host, no trailing slash)
wallabag.serverNamestringWallabagInstance name shown in the Wallabag UI and API
wallabag.secretstring""Symfony secret (generated once and preserved across upgrades when empty)
wallabag.existingSecretstring""Existing Secret containing the Symfony secret
wallabag.existingSecretKeystringsymfony-secretKey in the existing Secret holding the Symfony secret
wallabag.registrationbooleanfalseAllow public user registration
wallabag.admin.usernamestringwallabagUsername of the initial super-admin created on first install
wallabag.admin.emailstring[email protected]Email of the initial super-admin created on first install
wallabag.admin.passwordstring""Initial super-admin password (generated once and preserved when empty)
wallabag.admin.existingSecretstring""Existing Secret containing the initial super-admin password
wallabag.admin.existingSecretPasswordKeystringadmin-passwordKey in the existing Secret holding the super-admin password
wallabag.extraEnvarray-Extra environment variables for the Wallabag container

Setup(3)

ParameterTypeDefaultDescription
setup.enabledbooleantrueRun the database setup init container (schema install on first start, migrations on upgrade)
setup.databaseWaitTimeoutSecondsinteger300Seconds to wait for PostgreSQL before the setup init container fails
setup.resourcesobject-Resources for the setup init container

Database(7)

ParameterTypeDefaultDescription
database.external.hoststring""External PostgreSQL host (required when postgresql.enabled=false)
database.external.portstringinteger5432External PostgreSQL port
database.external.namestringwallabagExternal PostgreSQL database name
database.external.usernamestringwallabagExternal PostgreSQL username
database.external.passwordstring""External PostgreSQL password (ignored when existingSecret is set)
database.external.existingSecretstring""Existing Secret containing the database password
database.external.existingSecretPasswordKeystringpasswordKey in the existing Secret containing the password

External Redis(5)

ParameterTypeDefaultDescription
externalRedis.hoststring""External Redis host for asynchronous imports (used when redis.enabled=false)
externalRedis.portstringinteger6379External Redis port
externalRedis.passwordstring""External Redis password (ignored when existingSecret is set)
externalRedis.existingSecretstring""Existing Secret containing the external Redis password
externalRedis.existingSecretPasswordKeystringredis-passwordKey in the existing Secret containing the Redis password

Persistence(5)

ParameterTypeDefaultDescription
persistence.enabledbooleantrueEnable persistence for /var/www/wallabag/data
persistence.sizestring2GiStorage size
persistence.storageClassstring""Storage class
persistence.accessModesarray-Access modes
persistence.existingClaimstring""Use an existing PVC

Service Account(3)

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

Automount Service Account Token(1)

ParameterTypeDefaultDescription
automountServiceAccountTokenbooleanfalseMount the ServiceAccount token into the pod (Wallabag does not call the Kubernetes API)

Service & Networking(3)

ParameterTypeDefaultDescription
service.typestringClusterIPService type
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger80HTTP service port
service.annotationsobject-Annotations for the Service

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledbooleanfalseEnable ingress for Wallabag
ingress.ingressClassNamestringtraefikIngress class name (for example: traefik, nginx)
ingress.annotationsobject-Annotations for the Ingress
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 Wallabag Service by default

Health Probes(16)

ParameterTypeDefaultDescription
probes.pathstring/api/infoHTTP path used by every probe (served by Wallabag through nginx and PHP-FPM)
probes.startup.enabledbooleantrueEnable the startup probe
probes.startup.initialDelaySecondsinteger15Initial delay before the first startup probe
probes.startup.periodSecondsinteger10Startup probe period
probes.startup.timeoutSecondsinteger5Startup probe timeout
probes.startup.failureThresholdinteger30Startup probe failure threshold
probes.liveness.enabledbooleantrueEnable the liveness probe
probes.liveness.initialDelaySecondsinteger0Initial delay before the first liveness probe
probes.liveness.periodSecondsinteger15Liveness probe period
probes.liveness.timeoutSecondsinteger5Liveness probe timeout
probes.liveness.failureThresholdinteger3Liveness probe failure threshold
probes.readiness.enabledbooleantrueEnable the readiness probe
probes.readiness.initialDelaySecondsinteger0Initial delay before the first readiness probe
probes.readiness.periodSecondsinteger10Readiness probe period
probes.readiness.timeoutSecondsinteger5Readiness probe timeout
probes.readiness.failureThresholdinteger3Readiness probe failure threshold

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-Resources for the Wallabag container

Pod Security(1)

ParameterTypeDefaultDescription
podSecurityContextobject-Pod security context. The upstream image starts as root and drops to nobody for PHP.

Container Security(1)

ParameterTypeDefaultDescription
securityContextobject-Container security context for the Wallabag and setup containers

Backup(28)

ParameterTypeDefaultDescription
backup.enabledbooleanfalseEnable scheduled PostgreSQL backups to S3-compatible storage
backup.schedulestring0 3 * * *Cron schedule for backups (default: daily at 03:00 UTC)
backup.suspendbooleanfalseSuspend the CronJob without deleting it
backup.concurrencyPolicystringForbidConcurrency policy: Forbid, Replace, Allow
Allowed:AllowForbidReplace
backup.successfulJobsHistoryLimitinteger3Number of successful job records to keep
backup.failedJobsHistoryLimitinteger3Number of failed job records to keep
backup.backoffLimitinteger1Maximum retries per backup job
backup.archivePrefixstringwallabagPrefix for backup archive filenames
backup.images.postgresqlstringdocker.io/library/postgres:18-alpineImage used for PostgreSQL backup (must have pg_dump)
backup.images.uploaderstringdocker.io/helmforge/mc:1.0.0Image used for S3 upload (MinIO client)
backup.resourcesobject-Resources for backup containers
backup.s3.endpointstring""S3-compatible endpoint URL
backup.s3.bucketstring""Target bucket name
backup.s3.prefixstringwallabagKey prefix within the bucket
backup.s3.createBucketIfNotExistsbooleantrueAuto-create the bucket if it does not exist
backup.s3.existingSecretstring""Use an existing secret for S3 credentials
backup.s3.existingSecretAccessKeyKeystringaccess-keyKey in the existing secret for the access key
backup.s3.existingSecretSecretKeyKeystringsecret-keyKey in the existing secret for the secret key
backup.s3.accessKeystring""Inline S3 access key (ignored when existingSecret is set)
backup.s3.secretKeystring""Inline S3 secret key (ignored when existingSecret is set)
backup.database.hoststring""Backup database host override
backup.database.portstringinteger""Backup database port override
backup.database.namestring""Backup database name override
backup.database.usernamestring""Backup database username override
backup.database.passwordstring""Backup database password override
backup.database.existingSecretstring""Existing Secret with the backup database password
backup.database.existingSecretPasswordKeystringpasswordKey in the backup database Secret
backup.database.postgresDumpArgsstring""Extra arguments appended to pg_dump

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Node selector for the Wallabag pod

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Tolerations for the Wallabag pod

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Affinity rules for the Wallabag pod

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Topology spread constraints for the Wallabag pod

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring""Priority class name for the Wallabag pod

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger30Grace period for PHP-FPM and nginx to drain

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Extra labels for the Wallabag pod

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Extra annotations for the Wallabag pod

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Extra volumes for the Wallabag pod

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Extra volume mounts for the Wallabag container

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Extra manifests to deploy alongside the chart

Postgresql(5)

ParameterTypeDefaultDescription
postgresql.enabledbooleantrueDeploy PostgreSQL as a subchart
postgresql.architecturestringstandalonePostgreSQL subchart architecture
postgresql.auth.databasestringwallabagDatabase created for Wallabag
postgresql.auth.usernamestringwallabagDatabase user created for Wallabag
postgresql.auth.passwordstring""PostgreSQL password (auto-generated if empty)

Redis(3)

ParameterTypeDefaultDescription
redis.enabledbooleanfalseDeploy Redis as a subchart (asynchronous import queue; requires import workers, see DESIGN.md)
redis.architecturestringstandaloneRedis subchart architecture
redis.auth.passwordstring""Redis password (auto-generated by the subchart if empty)