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/wallabagdefault 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.portchanges the real nginx listener - Exposure: Ingress or Gateway API HTTPRoutes
- S3 backups: scheduled
pg_dumparchives uploaded to S3-compatible storage - Hardened defaults: no privilege escalation, minimal capabilities,
RuntimeDefaultseccomp, 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
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 and Redis
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.
See docs/external-database.md for managed PostgreSQL and docs/configuration.md for Redis and listener details.
Exposure, probes, and storage
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.
Backup settings are documented in
docs/backup-restore.md. Every key is listed in
values.yaml and validated by values.schema.json.
Examples
- examples/external-database.yaml: managed PostgreSQL with an existing Secret
- examples/production-with-redis-and-backup.yaml: Ingress with TLS, Redis, daily backups, and resource limits
Security
- The upstream image starts as root and drops to
nobodyfor PHP-FPM, sorunAsNonRootand a read-only root filesystem are not supported. The chart disables privilege escalation, drops every capability the image does not need, applies theRuntimeDefaultseccomp 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
- Wallabag documentation
- Chart source
- Chart design, configuration, external database, and backup and restore
Security Scan: wallabag
| Framework | Score |
|---|---|
| MITRE + NSA + SOC2 | 87.878784% |
Security posture acceptable.
System Architecture
DESIGN.md SyncedVerified 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)]Wallabag 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 resource name prefix |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Labels added to every rendered resource |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | docker.io/wallabag/wallabag | Wallabag container image |
| image.tag | string | 2.6.14 | Image tag |
| 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 |
Wallabag(13)
| Parameter | Type | Default | Description |
|---|---|---|---|
| wallabag.port | integer | 80 | Port the bundled nginx listener binds inside the container |
| wallabag.domainName | string | https://wallabag.example.com | Public URL users reach Wallabag through (scheme and host, no trailing slash) |
| wallabag.serverName | string | Wallabag | Instance name shown in the Wallabag UI and API |
| wallabag.secret | string | "" | Symfony secret (generated once and preserved across upgrades when empty) |
| wallabag.existingSecret | string | "" | Existing Secret containing the Symfony secret |
| wallabag.existingSecretKey | string | symfony-secret | Key in the existing Secret holding the Symfony secret |
| wallabag.registration | boolean | false | Allow public user registration |
| wallabag.admin.username | string | wallabag | Username of the initial super-admin created on first install |
| wallabag.admin.email | string | [email protected] | Email of the initial super-admin created on first install |
| wallabag.admin.password | string | "" | Initial super-admin password (generated once and preserved when empty) |
| wallabag.admin.existingSecret | string | "" | Existing Secret containing the initial super-admin password |
| wallabag.admin.existingSecretPasswordKey | string | admin-password | Key in the existing Secret holding the super-admin password |
| wallabag.extraEnv | array | - | Extra environment variables for the Wallabag container |
Setup(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| setup.enabled | boolean | true | Run the database setup init container (schema install on first start, migrations on upgrade) |
| setup.databaseWaitTimeoutSeconds | integer | 300 | Seconds to wait for PostgreSQL before the setup init container fails |
| setup.resources | object | - | Resources for the setup init container |
Database(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| database.external.host | string | "" | External PostgreSQL host (required when postgresql.enabled=false) |
| database.external.port | stringinteger | 5432 | External PostgreSQL port |
| database.external.name | string | wallabag | External PostgreSQL database name |
| database.external.username | string | wallabag | External PostgreSQL username |
| database.external.password | string | "" | External PostgreSQL password (ignored when existingSecret is set) |
| database.external.existingSecret | string | "" | Existing Secret containing the database password |
| database.external.existingSecretPasswordKey | string | password | Key in the existing Secret containing the password |
External Redis(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalRedis.host | string | "" | External Redis host for asynchronous imports (used when redis.enabled=false) |
| externalRedis.port | stringinteger | 6379 | External Redis port |
| externalRedis.password | string | "" | External Redis password (ignored when existingSecret is set) |
| externalRedis.existingSecret | string | "" | Existing Secret containing the external Redis password |
| externalRedis.existingSecretPasswordKey | string | redis-password | Key in the existing Secret containing the Redis password |
Persistence(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | true | Enable persistence for /var/www/wallabag/data |
| persistence.size | string | 2Gi | Storage size |
| persistence.storageClass | string | "" | Storage class |
| persistence.accessModes | array | - | Access modes |
| persistence.existingClaim | string | "" | Use an existing PVC |
Service Account(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | false | Create a ServiceAccount |
| serviceAccount.name | string | "" | ServiceAccount name |
| serviceAccount.annotations | object | - | Annotations for the ServiceAccount |
Automount Service Account Token(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| automountServiceAccountToken | boolean | false | Mount the ServiceAccount token into the pod (Wallabag does not call the Kubernetes API) |
Service & Networking(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | ClusterIP | Service type Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | 80 | HTTP service port |
| service.annotations | object | - | Annotations for the Service |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | false | Enable ingress for Wallabag |
| ingress.ingressClassName | string | traefik | Ingress class name (for example: traefik, nginx) |
| ingress.annotations | object | - | Annotations for the Ingress |
| 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 Wallabag Service by default |
Health Probes(16)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.path | string | /api/info | HTTP path used by every probe (served by Wallabag through nginx and PHP-FPM) |
| probes.startup.enabled | boolean | true | Enable the startup probe |
| probes.startup.initialDelaySeconds | integer | 15 | Initial delay before the first startup probe |
| probes.startup.periodSeconds | integer | 10 | Startup probe period |
| probes.startup.timeoutSeconds | integer | 5 | Startup probe timeout |
| probes.startup.failureThreshold | integer | 30 | Startup probe failure threshold |
| probes.liveness.enabled | boolean | true | Enable the liveness probe |
| probes.liveness.initialDelaySeconds | integer | 0 | Initial delay before the first liveness probe |
| probes.liveness.periodSeconds | integer | 15 | Liveness probe period |
| probes.liveness.timeoutSeconds | integer | 5 | Liveness probe timeout |
| probes.liveness.failureThreshold | integer | 3 | Liveness probe failure threshold |
| probes.readiness.enabled | boolean | true | Enable the readiness probe |
| probes.readiness.initialDelaySeconds | integer | 0 | Initial delay before the first readiness probe |
| probes.readiness.periodSeconds | integer | 10 | Readiness probe period |
| probes.readiness.timeoutSeconds | integer | 5 | Readiness probe timeout |
| probes.readiness.failureThreshold | integer | 3 | Readiness probe failure threshold |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | Resources for the Wallabag container |
Pod Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext | object | - | Pod security context. The upstream image starts as root and drops to nobody for PHP. |
Container Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext | object | - | Container security context for the Wallabag and setup containers |
Backup(28)
| Parameter | Type | Default | Description |
|---|---|---|---|
| backup.enabled | boolean | false | Enable scheduled PostgreSQL backups to S3-compatible storage |
| backup.schedule | string | 0 3 * * * | Cron schedule for backups (default: daily at 03:00 UTC) |
| backup.suspend | boolean | false | Suspend the CronJob without deleting it |
| backup.concurrencyPolicy | string | Forbid | Concurrency policy: Forbid, Replace, Allow Allowed: AllowForbidReplace |
| backup.successfulJobsHistoryLimit | integer | 3 | Number of successful job records to keep |
| backup.failedJobsHistoryLimit | integer | 3 | Number of failed job records to keep |
| backup.backoffLimit | integer | 1 | Maximum retries per backup job |
| backup.archivePrefix | string | wallabag | Prefix for backup archive filenames |
| backup.images.postgresql | string | docker.io/library/postgres:18-alpine | Image used for PostgreSQL backup (must have pg_dump) |
| backup.images.uploader | string | docker.io/helmforge/mc:1.0.0 | Image used for S3 upload (MinIO client) |
| backup.resources | object | - | Resources for backup containers |
| backup.s3.endpoint | string | "" | S3-compatible endpoint URL |
| backup.s3.bucket | string | "" | Target bucket name |
| backup.s3.prefix | string | wallabag | Key prefix within the bucket |
| backup.s3.createBucketIfNotExists | boolean | true | Auto-create the bucket if it does not exist |
| backup.s3.existingSecret | string | "" | Use an existing secret for S3 credentials |
| backup.s3.existingSecretAccessKeyKey | string | access-key | Key in the existing secret for the access key |
| backup.s3.existingSecretSecretKeyKey | string | secret-key | Key in the existing secret for the secret key |
| backup.s3.accessKey | string | "" | Inline S3 access key (ignored when existingSecret is set) |
| backup.s3.secretKey | string | "" | Inline S3 secret key (ignored when existingSecret is set) |
| backup.database.host | string | "" | Backup database host override |
| backup.database.port | stringinteger | "" | Backup database port override |
| backup.database.name | string | "" | Backup database name override |
| backup.database.username | string | "" | Backup database username override |
| backup.database.password | string | "" | Backup database password override |
| backup.database.existingSecret | string | "" | Existing Secret with the backup database password |
| backup.database.existingSecretPasswordKey | string | password | Key in the backup database Secret |
| backup.database.postgresDumpArgs | string | "" | Extra arguments appended to pg_dump |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Node selector for the Wallabag pod |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Tolerations for the Wallabag pod |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Affinity rules for the Wallabag pod |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Topology spread constraints for the Wallabag pod |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | "" | Priority class name for the Wallabag pod |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | 30 | Grace period for PHP-FPM and nginx to drain |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Extra labels for the Wallabag pod |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Extra annotations for the Wallabag pod |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Extra volumes for the Wallabag pod |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Extra volume mounts for the Wallabag container |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Extra manifests to deploy alongside the chart |
Postgresql(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| postgresql.enabled | boolean | true | Deploy PostgreSQL as a subchart |
| postgresql.architecture | string | standalone | PostgreSQL subchart architecture |
| postgresql.auth.database | string | wallabag | Database created for Wallabag |
| postgresql.auth.username | string | wallabag | Database user created for Wallabag |
| postgresql.auth.password | string | "" | PostgreSQL password (auto-generated if empty) |
Redis(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| redis.enabled | boolean | false | Deploy Redis as a subchart (asynchronous import queue; requires import workers, see DESIGN.md) |
| redis.architecture | string | standalone | Redis subchart architecture |
| redis.auth.password | string | "" | Redis password (auto-generated by the subchart if empty) |
No schema parameters match your search
Try searching for a different keyword or reset the filter.