Deploying MediaWiki on Kubernetes with Helm: From Development to Production

Why run MediaWiki on Kubernetes?

MediaWiki powers Wikipedia and thousands of other wikis. As the platform grows, operators need a deployment model that can scale, recover quickly, and integrate with modern CI/CD pipelines. Kubernetes provides container orchestration, while Helm supplies a declarative package format that bundles MediaWiki, its database, and supporting services into a single, repeatable release.

Helm charts in the Wikimedia ecosystem

The Wikimedia Foundation maintains a ChartMuseum that hosts the official mediawiki chart and its dependencies (MariaDB, Parsoid, etc.). A 2020 “Scrum of scrums” note announced the migration of the old chart endpoint to this new repository, making the charts directly consumable with helm repo add.

From a developer’s sandbox to a production cluster

1. Local development with local‑charts

The workflow looks like this:

1. Customize via values.yaml. Typical overrides include:
   • Persistence size for MediaWiki and MariaDB (persistence.size)
   • Replica count and Horizontal Pod Autoscaler (autoscaling.enabled)
   • Secrets for DB credentials (mariadb.auth.password)

Iterate rapidly with local images. Wikimedia recommends building a local Docker image (using blubber) and loading it into Minikube’s Docker daemon:

eval $(minikube docker-env)
blubber .pipeline/blubber.yaml development | docker build -t mywiki:dev -f - .
helm upgrade mywiki wiki/mediawiki --set image.repository=mywiki,image.tag=dev

This avoids pushing images to a remote registry during early development.

Install the chart locally:

helm repo add wiki https://helm-charts.wikimedia.org/stable/
helm install mywiki wiki/mediawiki --namespace mediawiki

Spin up Minikube (or any Docker‑driver Kubernetes cluster):

minikube start --driver=docker

2. Testing the stack

The chart bundles a MariaDB sub‑chart, so a single helm install creates both MediaWiki and its database. The chart also includes an init‑container that waits for the DB to become reachable before MediaWiki starts – a pattern that works both locally and in the cloud.

Typical tests include:

• Checking that the MediaWiki service receives a LoadBalancer IP: kubectl get svc mywiki-mediawiki -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
• Running the MediaWiki installer against the DB: kubectl exec -it $(kubectl get pod -l app=mediawiki -o name) -- php install.php "My Wiki" admin --pass secret --dbserver mywiki-mariadb --dbuser wikiuser --dbpass secret
• Verifying that LocalSettings.php is generated and persisted on the PVC.

3. From sandbox to a production‑grade cluster

When the chart is ready for production you switch from Minikube to a real Kubernetes cluster (EKS, GKE, AKS, or the internal Wikimedia wikikube environment). The steps are the same but with a few extra considerations:

1. Pin a chart version – the ChartMuseum publishes semver tags, so you can lock to a known‑good release, e.g. mediawiki-21.0.5.
2. Enable persistent storage on a cloud‑provided ReadWriteMany volume if you plan to autoscale replicas. The chart’s persistence.accessModes defaults to ReadWriteOnce, which works for a single replica but must be changed for horizontal scaling.
3. Rolling updates – Helm’s default strategy.type=RollingUpdate ensures zero‑downtime. You can also enable podDisruptionBudget to protect against accidental outages.

Secret management – store DB passwords, MediaWiki secret keys, and OAuth tokens in Kubernetes Secret objects. The chart automatically mounts them into the container; you only need to reference the secret name in values.yaml.

kubectl create secret generic mediawiki-secret \
  --from-literal=wgSecretKey=$(openssl rand -hex 32)

Configure TLS and a public LoadBalancer. The chart supports service.type=LoadBalancer and can be wired to an Ingress controller (NGINX, Traefik) for HTTPS termination.

helm upgrade mywiki wikicharts/mediawiki \
  --set service.type=LoadBalancer \
  --set ingress.enabled=true \
  --set ingress.host=wiki.example.org

Use the official chart repository:

helm repo add wikicharts https://helm-charts.wikimedia.org/stable/

Production‑grade continuous delivery – the “Pretrain” model

Wikimedia is moving toward a daily‑deployment pipeline called Pretrain. The idea is to build a single OCI image that contains MediaWiki core, all enabled extensions, and the chosen skin, then push that image to a registry and deploy it to a dedicated pretrain namespace on the production Kubernetes cluster.^[8] Benefits include:

• All code that lands in the MediaWiki repository is exercised on a “production‑like” cluster within minutes, catching regressions early.
• Because the image is immutable, rollbacks are as simple as redeploying the previous tag.
• The same pipeline can be reused for internal wikis (wikitech, mediawiki.org) and for test wikis (test.wikipedia.org).

The Pretrain workflow mirrors a typical Helm‑CI pipeline:

1. CI builds the OCI image (named wmf/next) daily.
2. A helm upgrade runs against the pretrain release, passing the new image tag via --set image.tag=$(date +%Y%m%d).
3. Health checks (/healthz endpoint) ensure the new pods are ready before traffic is switched.

Operators who want a similar “continuous delivery” model can adopt the same pattern: a nightly build job that produces a version‑tagged image, a Helm chart that only changes the image tag, and a Kubernetes Deployment with maxSurge=25% and maxUnavailable=0 to guarantee smooth rollouts.

Best‑practice checklist

Area	Recommendation
Chart versioning	Pin to a specific chart version; upgrade only after testing in a pre‑prod namespace.
Persistence	Use a cloud‑managed ReadWriteMany PVC for MediaWiki uploads; enable backups of the volume.
Secrets	Store DB credentials and $wgSecretKey in Kubernetes Secret; rotate regularly.
Scaling	Enable the chart’s Horizontal Pod Autoscaler; ensure the DB can handle multiple read replicas or use a managed DB service.
Observability	Expose /healthz and Prometheus metrics (the chart ships a serviceMonitor); forward logs to the Wikimedia logstash pipeline or your own stack.
CI/CD	Integrate Helm lint, Helm test, and a Helmfile/ArgoCD deployment pipeline; use the same values.yaml for dev, staging, and prod, overriding only environment‑specific fields.

Putting it all together – a minimal example

# 1. Add the official repo
helm repo add wikicharts https://helm-charts.wikimedia.org/stable/
helm repo update

# 2. Create a namespace for the release
kubectl create namespace wiki-prod

# 3. Prepare secrets (run once)
kubectl -n wiki-prod create secret generic mediawiki-db \
  --from-literal=rootPassword=$(openssl rand -hex 16) \
  --from-literal=wikiPassword=$(openssl rand -hex 16)

# 4. Deploy the chart (pin version 21.0.5 as an example)
helm upgrade --install mywiki wikicharts/mediawiki \
  --namespace wiki-prod \
  --version 21.0.5 \
  --set mariadb.auth.rootPasswordSecret=mediawiki-db \
  --set mariadb.auth.passwordSecret=mediawiki-db \
  --set persistence.size=10Gi \
  --set service.type=LoadBalancer \
  --set ingress.enabled=true \
  --set ingress.host=wiki.example.org \
  --set autoscaling.enabled=true \
  --set autoscaling.minReplicas=2 \
  --set autoscaling.maxReplicas=5

# 5. Verify
kubectl -n wiki-prod get svc mywiki-mediawiki
kubectl -n wiki-prod get pod -l app.kubernetes.io/name=mediawiki

Once the LoadBalancer IP is reachable, navigate to http://wiki.example.org and finish the MediaWiki web installer. The generated LocalSettings.php is stored on the PVC, so subsequent pod restarts preserve configuration.

Conclusion

Deploying MediaWiki on Kubernetes with Helm gives you a repeatable, version‑controlled stack that can evolve from a single‑node developer experiment to a high‑availability production service. By leveraging the Wikimedia‑maintained chart repository, the local‑charts sandbox, and the Pretrain continuous‑delivery pattern, teams can iterate quickly, test changes in a production‑like environment, and roll out updates with zero downtime.

Start with Minikube, move to a cloud cluster, and finally adopt the daily‑build Pretrain workflow – MediaWiki on Kubernetes has never been more approachable.