Running Wallabag on a Private Kubernetes Cluster
How a self-hosted read-it-later service becomes a reproducible Kubernetes workload with Docker, Helm, Traefik, and GitOps.
What is Wallabag?
Wallabag is a self-hosted read-it-later application. It solves the same basic problem as Pocket or Instapaper: you find an article, save it, and come back to it later in a clean reading interface.
The important difference is ownership. With Wallabag, the saved articles, tags, annotations, and reading history live in infrastructure you control. That makes it a good fit for a private Kubernetes cluster: it is useful enough to keep running permanently, small enough to operate without heavy machinery, and stateful enough to exercise the full application lifecycle.
In this setup, Wallabag runs as a regular Kubernetes application behind Traefik, exposed publicly at:
https://wallabag.balhau.dev
The application is described by a Helm chart under apps/wallabag/helm/wallabag, registered as an ArgoCD application under infra/apps/wallabag.yaml, and backed by persistent storage through the cluster's nfs storage class.
Why Containerize It?
Kubernetes does not run source trees. It runs containers. The first step is therefore to make Wallabag available as an image that the cluster can pull consistently.
The previous approach in this repository tried to build Wallabag from lower-level pieces: an ARM32 Alpine base image, system packages, application setup, custom entrypoint logic, and local filesystem overlays. That style gives maximum control, but it also creates a maintenance burden:
- the image was tied to an old ARM32 platform,
- the Dockerfile duplicated work already done upstream,
- runtime setup depended on files that were not present in the repository,
- and every upstream Wallabag change became our build problem.
The current Dockerfile is deliberately smaller:
ARG WALLABAG_VERSION=2.6.10
FROM wallabag/wallabag:${WALLABAG_VERSION}
LABEL authors="Balhau <[email protected]>"
This is not a lack of engineering. It is the engineering decision.
Wallabag already publishes a maintained container image. The private cluster does not need to rebuild Wallabag from source just to run it. What it does need is a local artifact that follows the same registry conventions as the other applications in the cluster.
The local image is built and pushed as:
192.168.1.241:5000/balhau/wallabag:2.6.10
That gives us two useful properties:
- The application image is still based on the upstream Wallabag release.
- The cluster pulls from the private registry used by the rest of the platform.
The Makefile
The apps/wallabag/Makefile wraps the container workflow in the same shape used by the rest of the repository:
REGISTRY ?= 192.168.1.241:5000
LOCAL_REGISTRY ?= localhost:5000
NS ?= balhau
APP ?= wallabag
VERSION ?= 2.6.10
PLATFORM ?= linux/arm64
IMAGE = $(REGISTRY)/$(NS)/$(APP):$(VERSION)
LOCAL_IMAGE = $(LOCAL_REGISTRY)/$(NS)/$(APP):$(VERSION)
The important details are:
REGISTRYpoints to the registry address visible to the cluster.LOCAL_REGISTRYsupports pushing through a local registry port-forward or local endpoint.VERSIONis pinned to the Wallabag version used by the chart.PLATFORMislinux/arm64, matching the current Raspberry Pi worker target.
The build target uses Docker Buildx:
build:
docker buildx build --platform $(PLATFORM) --build-arg WALLABAG_VERSION=$(VERSION) -t $(IMAGE) --load .
And the push-oriented target builds directly for the local registry endpoint:
build-push:
docker buildx build --platform $(PLATFORM) --build-arg WALLABAG_VERSION=$(VERSION) -t $(LOCAL_IMAGE) --push .
There are also chart-focused targets:
template:
helm template wallabag helm/wallabag --namespace wallabag
lint:
helm lint helm/wallabag
That matters because Wallabag is no longer just a Docker image. It is a Kubernetes application, and the Makefile should help validate both sides of that contract.
The Helm Chart
The Helm chart under apps/wallabag/helm/wallabag describes the Kubernetes resources required to run Wallabag.
At a high level, the chart generates:
- a
ServiceAccount, - a
PersistentVolumeClaim, - a
Service, - a
Deployment, - and an
Ingress.
This is a compact but complete shape for a small stateful web application.
Image Configuration
The image configured in values.yaml points to the private registry:
image:
repository: 192.168.1.241:5000/balhau/wallabag
tag: 2.6.10
pullPolicy: IfNotPresent
This connects the containerization step to the runtime step. The Dockerfile defines how the image is produced; Helm defines where that image runs.
Persistent Storage
Wallabag stores data that must survive pod restarts. In this setup, the chart creates a PVC using the nfs storage class:
persistence:
enabled: true
storageClass: nfs
accessModes:
- ReadWriteOnce
size: 1Gi
The deployment mounts that volume at:
/var/www/wallabag/data
For this deployment, Wallabag is configured to use SQLite:
env:
SYMFONY__ENV__DATABASE_DRIVER: pdo_sqlite
SYMFONY__ENV__DATABASE_PATH: /var/www/wallabag/data/db/wallabag.sqlite
That keeps the operational footprint small. There is no separate database dependency for Wallabag, but the database file still lives on persistent storage instead of inside the container filesystem.
Deployment
The Deployment runs a single Wallabag replica:
replicaCount: 1
For a SQLite-backed application, that is the correct default. Multiple replicas would need shared database semantics that SQLite does not provide safely for this use case.
The rendered pod uses the private image:
192.168.1.241:5000/balhau/wallabag:2.6.10
It exposes container port 80 and defines TCP readiness and liveness probes. The probes are intentionally simple: they answer the first operational question Kubernetes needs to know, which is whether the web server is accepting connections.
Service
The Service gives the Wallabag pod a stable in-cluster endpoint:
service:
type: ClusterIP
port: 80
Pods come and go. Services are the stable layer that other Kubernetes resources target. The Ingress does not route directly to a pod; it routes to this service.
Ingress
The chart exposes Wallabag through Traefik:
ingress:
enabled: true
className: infra-ingress-traefik
hosts:
- host: wallabag.balhau.dev
paths:
- path: /
pathType: Prefix
tls:
- secretName: wallabag-certificate
hosts:
- wallabag.balhau.dev
The generated Kubernetes Ingress tells Traefik:
- listen for requests to
wallabag.balhau.dev, - route path
/to the Wallabag service, - and use the
wallabag-certificateTLS secret.
The ingress also carries the cert-manager issuer annotation:
cert-manager.io/cluster-issuer: letsencrypt-prod
That keeps certificate management declarative. The chart describes the desired public hostname and TLS secret; cert-manager is responsible for making the certificate exist.
GitOps Registration
The chart is registered with ArgoCD through infra/apps/wallabag.yaml.
The ArgoCD Application points to the Helm chart path:
path: apps/wallabag/helm/wallabag
repoURL: http://forgejo-http.git.svc.cluster.local:3000/kuber/kuber.git
targetRevision: main
It deploys into the wallabag namespace:
destination:
namespace: wallabag
server: https://kubernetes.default.svc
And it enables namespace creation:
syncOptions:
- CreateNamespace=true
The app is also pinned to the same node convention used by the other public applications:
nodeSelector:
kubernetes.io/hostname: rasp6
This is the point where Wallabag becomes part of the cluster operating model. A change to the chart or values goes to git, ArgoCD sees it, and the cluster converges toward the declared state.
Validation
The integration was validated in three layers.
First, the Makefile commands were checked without running full builds:
make -n build
make -n build-push
That confirmed the image name, platform, build arguments, and registry targets.
Second, the Helm chart was linted and rendered:
make lint
make template
Third, the rendered Kubernetes resources were submitted to the Kubernetes client-side dry-run path:
helm template wallabag apps/wallabag/helm/wallabag --namespace wallabag \
| kubectl apply --dry-run=client -f -
The generated resources passed validation:
serviceaccount/wallabag created (dry run)
persistentvolumeclaim/wallabag created (dry run)
service/wallabag created (dry run)
deployment.apps/wallabag created (dry run)
ingress.networking.k8s.io/wallabag created (dry run)
Finally, the ArgoCD application set was rendered with:
kubectl kustomize infra/apps
That verifies that the Wallabag application is included in the broader GitOps app registry.
Why Run Wallabag in a Private Cluster?
Wallabag is a good example of the kind of application that benefits from private Kubernetes without requiring enterprise-scale infrastructure.
Data Ownership
Saved articles often reveal interests, research topics, work context, and personal routines. Keeping that data in a private cluster means the reading list is not another behavioral dataset owned by a third-party SaaS provider.
Reproducibility
The deployment is not a wiki page full of manual steps. It is a Dockerfile, a Makefile, a Helm chart, and an ArgoCD application. Rebuilding or moving the service is mostly a matter of replaying the repository state.
Operational Consistency
Wallabag uses the same platform primitives as the other applications in the cluster:
- local container registry,
- Helm chart packaging,
- Traefik ingress,
- cert-manager TLS,
- NFS-backed persistence,
- and ArgoCD reconciliation.
There is no special snowflake server for the read-it-later service. It runs like the rest of the platform runs.
Small Stateful Workload, Real Platform Exercise
Wallabag is small, but it is not trivial. It needs persistence, configuration, routing, certificates, image management, and application lifecycle handling. That makes it a useful workload for proving that the private cluster is capable of running real personal infrastructure.
Reduced External Dependency
The application itself can be reached publicly through wallabag.balhau.dev, but the control plane remains private. The source of truth is the local GitOps repository. The image comes from the local registry. The storage is internal. The cluster owns the runtime.
The Result
The final integration is intentionally boring:
- Wallabag is built as a local image based on the upstream release.
- Helm describes the runtime resources.
- Kubernetes provides scheduling, service discovery, persistence, and ingress.
- Traefik exposes the application.
- cert-manager handles TLS.
- ArgoCD keeps the deployed state aligned with git.
That is the point. A private Kubernetes cluster is most valuable when useful applications can be added in a repeatable pattern. Wallabag now follows that pattern: one image, one chart, one ArgoCD application, and one public hostname backed by infrastructure we control.
This article is based on the Wallabag integration in the kuber repository, especially apps/wallabag/Dockerfile, apps/wallabag/Makefile, apps/wallabag/helm/wallabag, and infra/apps/wallabag.yaml.