aapjeisbaas/wordpress-helm repository overview

⁠WordPress Helm Chart

A Helm chart for deploying WordPress with MySQL, Varnish, and Memcached on Kubernetes.

This repository contains an OCI Helm chart, not a container image. Install it with Helm, not docker run. The WordPress runtime image is aapjeisbaas/wp-frankenphp⁠.

Current chart: 0.2.11 · Default runtime: v0.3.1 (PHP 8.4) · Source code⁠

⁠Overview

This chart deploys a complete WordPress environment with the following components:

• WordPress with FrankenPHP
• MySQL database
• Varnish cache
• Memcached for object caching
• Network policies for securing communications
• Optional scheduled S3-compatible backups and restore support

⁠Prerequisites

• A Kubernetes cluster and kubectl access
• Helm 3.14+ or Helm 4 (the upgrade examples use --reset-then-reuse-values)
• A storage class supporting the configured persistent volume access modes

⁠Installing the Chart

⁠From DockerHub OCI Registry

Install directly from Docker Hub; no helm repo add is needed. Choose a storage class available in your cluster (kubectl get storageclass). The chart defaults to standard with ReadWriteMany volumes. For a single WordPress replica on storage that only supports ReadWriteOnce, save this as my-values.yaml and replace your-storage-class:

wordpress:
  persistence:
    storageClass: your-storage-class
    accessMode: ReadWriteOnce
mysql:
  persistence:
    storageClass: your-storage-class
    accessMode: ReadWriteOnce

helm install my-wordpress oci://registry-1.docker.io/aapjeisbaas/wordpress-helm \
  --version 0.2.11 \
  --namespace my-wordpress --create-namespace \
  --values my-values.yaml \
  --wait --timeout 10m

Inspect all defaults before installing:

helm show values oci://registry-1.docker.io/aapjeisbaas/wordpress-helm --version 0.2.11

⁠Access WordPress

The chart creates internal ClusterIP services; it does not create an Ingress or configure TLS. For a local preview:

kubectl --namespace my-wordpress port-forward service/my-wordpress-varnish 8080:80

Open http://localhost:8080. For public access, configure your ingress controller or reverse proxy to route to my-wordpress-varnish on port 80 in the release namespace. my-wordpress-wordpress:80 bypasses Varnish.

⁠From Local Directory

To install the chart from a local directory with the release name my-wordpress:

git clone https://gitlab.com/aapjeisbaas/wordpress-helm.git
helm install my-wordpress wordpress-helm \
  --set wordpress.persistence.accessMode=ReadWriteOnce \
  --set mysql.persistence.accessMode=ReadWriteOnce

⁠Upgrade Notes

• Chart 0.2.11 defaults to wp-frankenphp:v0.3.1 with PHP 8.4 for broader compatibility. PHP 8.5 remains available via wordpress.image.tag=v0.3.1-php8.5.
• Chart 0.2.10 defaults to wp-frankenphp:v0.3.0 with PHP 8.5. Check plugin and theme compatibility before upgrading. To stay on PHP 8.4, set wordpress.image.tag=v0.3.0-php8.4.
• In-place upgrades are supported with helm upgrade.
• Database password is generated once (if empty) and preserved on upgrades.
• Services and network policies are release-scoped for multi-release support.
• Deployment selectors remain app-only for upgrade compatibility because Kubernetes does not allow changing them in-place.
• PVC access mode is immutable in Kubernetes. If an existing release uses ReadWriteOnce, keep using:

--set wordpress.persistence.accessMode=ReadWriteOnce \
--set mysql.persistence.accessMode=ReadWriteOnce

⁠Configuration

The following table lists the configurable parameters of the WordPress chart and their default values.

⁠Global Parameters

⁠WordPress Parameters

⁠MySQL Parameters

⁠Varnish and Memcached Parameters

⁠Database Secrets

⁠Backup Storage Parameters

⁠Backup Parameters

⁠Restore Parameters

⁠Backups And Restores

The chart includes optional S3-compatible backup and restore support. It is disabled by default.

Backups use standard tools:

• Database: mysqldump --single-transaction --quick --routines --triggers, compressed as database.sql.gz
• Files: tar.gz archive of the full WordPress document root, default wordpress.dataPath /var/www
• Storage: AWS CLI to S3-compatible storage

The files backup contains the complete WordPress tree under wordpress.dataPath, including WordPress core, plugins, themes, uploads, and config files stored on the WordPress PVC. The archive extracts directly into the configured data path, so it is usable outside these containers as a standalone WordPress filesystem backup.

Backup layout:

s3://<bucket>/<prefix>/latest.txt
s3://<bucket>/<prefix>/<backup-id>/database.sql.gz
s3://<bucket>/<prefix>/<backup-id>/wordpress-files.tar.gz

The backup ID is a UTC timestamp in YYYYMMDD-HHMMSS format.

⁠S3 Credentials

For production, prefer an existing Kubernetes Secret:

kubectl create secret generic wordpress-backup-s3 \
  --from-literal=AWS_ACCESS_KEY_ID='<access-key>' \
  --from-literal=AWS_SECRET_ACCESS_KEY='<secret-key>'

Then reference it:

backupStorage:
  s3:
    bucket: my-wordpress-backups
    prefix: production/example-site
    region: eu-west-1
    existingSecret: wordpress-backup-s3

For S3-compatible storage such as MinIO, also set backupStorage.s3.endpoint.

⁠Shared S3 Credentials Across Namespaces

Kubernetes Secrets are namespace-scoped. A backup CronJob can only read a Secret from its own namespace. If many WordPress releases share the same backup credentials, use Emberstack Reflector to copy one source Secret to every namespace.

The chart does not need special configuration for this. Every namespace should end up with a local Secret named wordpress-backup-s3, and the chart should reference it with:

backupStorage:
  s3:
    existingSecret: wordpress-backup-s3

Install Reflector in the cluster:

helm repo add emberstack https://emberstack.github.io/helm-charts
helm repo update

helm upgrade --install reflector emberstack/reflector \
  --namespace reflector \
  --create-namespace

Create one namespace for the source Secret:

kubectl create namespace backup-secrets

Create the source Secret in that namespace:

kubectl -n backup-secrets create secret generic wordpress-backup-s3 \
  --from-literal=AWS_ACCESS_KEY_ID='<access-key>' \
  --from-literal=AWS_SECRET_ACCESS_KEY='<secret-key>'

Annotate the source Secret so Reflector copies it to every namespace:

kubectl -n backup-secrets annotate secret wordpress-backup-s3 \
  reflector.v1.k8s.emberstack.com/reflection-allowed="true" \
  reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces=".*" \
  reflector.v1.k8s.emberstack.com/reflection-auto-enabled="true" \
  reflector.v1.k8s.emberstack.com/reflection-auto-namespaces=".*" \
  --overwrite

Use a narrower namespace pattern instead of .* if only some namespaces should receive the backup credentials, for example wordpress-.*|frankenphp-test.

Check that the Secret was copied:

kubectl get secret wordpress-backup-s3 -A

⁠PHP Configuration

The wp-frankenphp image ships default PHP settings in /usr/local/etc/php/conf.d/99-custom.ini. To override or add PHP ini settings without rebuilding the image, set wordpress.php.customIni. The chart mounts the content as /usr/local/etc/php/conf.d/zz-custom.ini, so it is loaded after the image defaults.

For example, to raise the PHP memory limit for large wp-admin/editor requests:

wordpress:
  php:
    customIni: |
      memory_limit=512M

You can include multiple settings:

wordpress:
  php:
    customIni: |
      memory_limit=512M
      upload_max_filesize=256M
      post_max_size=256M
      max_execution_time=300

Changing wordpress.php.customIni updates a pod template checksum, so Helm upgrades roll the WordPress pods automatically.

⁠Scheduled Backups

Enable backups with:

backup:
  enabled: true
  schedule: "0 2 * * *"
  retention:
    keepLast: 3
    keepDaily: 7
    keepWeekly: 4
    keepMonthly: 2
backupStorage:
  s3:
    bucket: my-wordpress-backups
    existingSecret: wordpress-backup-s3

Retention cleanup runs after a successful upload. It only deletes timestamped backup directories, never deletes latest.txt, always keeps the backup referenced by latest.txt, and stops before deleting the last remaining backup.

The recommended retention policy uses Proxmox Backup Server-style buckets:

• keepLast: keep the N most recent backups regardless of timing.
• keepDaily: keep the newest backup from each of the last N UTC calendar days with backups.
• keepWeekly: keep the newest backup from each of the last N UTC ISO calendar weeks with backups.
• keepMonthly: keep the newest backup from each of the last N UTC calendar months with backups.
• keepYearly: keep the newest backup from each of the last N UTC calendar years with backups.

Rules are evaluated in this order: keepLast, keepDaily, keepWeekly, keepMonthly, keepYearly. Kept backups are de-duplicated, so overlap is intentional. For example, if the newest three backups are also the newest backups for three daily buckets, they count toward both keepLast and keepDaily and are stored only once.

Retention policy examples, assuming one backup per day:

Approximate retained counts account for overlap between rules. Actual counts vary depending on backup frequency and timing.

Set all backup.retention.* values to empty, null, or 0 to disable rule-based cleanup. If all rule-based retention values are disabled, the older backup.retentionDays setting is used for age-based cleanup. Set backup.retentionDays to empty, null, or 0 as well to keep backups forever.

To run a backup immediately:

kubectl create job --from=cronjob/my-wordpress-backup my-wordpress-backup-manual

⁠Manual Restore

Restore is destructive: it overwrites WordPress files under wordpress.dataPath and imports the database dump.

You must set the confirmation string explicitly:

helm upgrade my-wordpress oci://registry-1.docker.io/aapjeisbaas/wordpress-helm \
  --version 0.2.11 \
  --namespace my-wordpress \
  --reset-then-reuse-values \
  --set restore.enabled=true \
  --set restore.confirmation=I_UNDERSTAND_RESTORE_OVERWRITES_DATA \
  --set restore.backupId=20260101-020000

Leave restore.backupId empty to restore the backup referenced by latest.txt.

Set restore.enabled=false again after the restore Job completes, otherwise the restore hook will be created again on later upgrades.

⁠Auto-Restore On Empty Installs

Auto-restore is intended for disaster recovery or creating a fresh install from the latest backup:

restore:
  autoRestoreOnEmpty: true
backupStorage:
  s3:
    bucket: my-wordpress-backups
    existingSecret: wordpress-backup-s3

The initContainer restores only when both the database and wordpress.dataPath are empty. If both contain data, it skips restore. If only one side contains data, it fails loudly to avoid overwriting a partial state silently.

Do not enable automatic restore in production until manual restore has been tested successfully. A backup that has not been restored at least once is not a backup.

⁠Persistence

This chart uses PVC to persist data for WordPress and MySQL deployments. You can configure the storage class and size in the values.yaml file.

If you are upgrading an existing release, keep the existing PVC access mode values. Kubernetes does not allow changing access mode on bound PVCs.

⁠Upgrading

⁠From Local Directory

helm upgrade my-wordpress /path/to/wordpress-helm \
  --reset-then-reuse-values

For existing RWO volumes:

helm upgrade my-wordpress /path/to/wordpress-helm \
  --reset-then-reuse-values \
  --set wordpress.persistence.accessMode=ReadWriteOnce \
  --set mysql.persistence.accessMode=ReadWriteOnce

⁠From DockerHub OCI Registry

Back up the site first. Upgrade using the existing release name and namespace:

helm upgrade my-wordpress oci://registry-1.docker.io/aapjeisbaas/wordpress-helm \
  --version 0.2.11 \
  --namespace my-wordpress \
  --reset-then-reuse-values \
  --wait --timeout 10m

--reset-then-reuse-values loads the new chart defaults and reapplies your saved custom values. Avoid --reuse-values alone: it can keep old defaults, including the old WordPress image. Explicit image overrides remain overrides; remove or update them if you want to follow the chart default. Keep existing storage classes and PVC access modes unchanged.

For automatic rollback on failure, add --rollback-on-failure with Helm 4 or --atomic with Helm 3. A Helm rollback does not undo database or filesystem changes.

⁠Uninstalling the Chart

helm uninstall my-wordpress --namespace my-wordpress

Uninstalling removes the chart-managed PVCs as well as the workloads. Depending on the storage class reclaim policy, the underlying volumes and site data may also be deleted. Make and verify a backup before uninstalling.