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:

  1. The application image is still based on the upstream Wallabag release.
  2. 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:

  • REGISTRY points to the registry address visible to the cluster.
  • LOCAL_REGISTRY supports pushing through a local registry port-forward or local endpoint.
  • VERSION is pinned to the Wallabag version used by the chart.
  • PLATFORM is linux/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-certificate TLS 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.