Skip to content
notch8Public

About

Wordpress site for Enact project - see also https://github.com/research-technologies/enact_knapsack

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

WordPress for Enact

A plain vanilla WordPress site (official wordpress + mysql Docker images) running on the enact Kubernetes cluster, for internal use.

Two independent environments, each its own namespace with its own MySQL instance:

Environment Namespace URL
staging enact-wp-staging https://enact-wp-staging.enacthyku.com
production enact-wp-production https://enact-wp-production.enacthyku.com

Access

Both URLs are on public DNS (proxied through Cloudflare, so bot_fight_mode and the WAF still apply), but the site itself is private: every front-end page requires a real WordPress login. This is done by a one-file mu-plugin (wordpress/templates/configmap-private-site.yaml, controlled by the privateSite.enabled value, true by default) that hooks WordPress's own auth_redirect() -- the same function wp-admin uses -- into every page load. Nothing renders for anonymous visitors, so bots/scrapers get nothing to crawl, and there's no dependency on Cloudflare Access or any other external service.

The very first time you open a given environment, you'll land on WordPress's normal 5-minute install wizard (it's unaffected by the login gate) -- pick a site title and an admin username/password there. Save that admin login in 1Password; nothing about it is templated or stored by this repo.

Local development

Mirror of the k8s deployment via docker compose -- WordPress builds the same pinned Dockerfile CI publishes to GHCR, not a floating official image:

docker compose up -d --build    # WordPress on http://localhost:8080, MySQL alongside
./bin/wp core install --url=http://localhost:8080 --title="Enact" \
    --admin_user=admin --admin_password=<pick-one> --admin_email=<you>@notch8.com --skip-email
./bin/wp rewrite structure '/%postname%/'
./bin/wp user create enact-team nick+enact-team@notch8.com --role=author --display_name="Enact Team"
./bin/wp user application-password create admin local --porcelain   # feed to bin/provision
./bin/provision --base-url http://localhost:8080 --user admin --app-password '<from above>' \
    --overwrite template-parts,templates,global-styles,settings,site-branding,cleanup

./bin/wp <anything> runs wp-cli against the local instance. The compose file sets WP_ENVIRONMENT_TYPE=local so application passwords work over plain http; that setting is intentionally absent from the k8s deployment, which is https.

The compose file also mounts the two-factor policy mu-plugin (see "Two-factor authentication" below) with enforcement off and admin as the only login allowed to use application passwords. To try enforcement locally, install the plugin (./bin/wp plugin install two-factor --activate) and restart with ENACT_2FA_ENFORCE=1 docker compose up -d --build.

Site content as code

The content/ directory is the seed for a new environment: block-markup HTML for every page and post, curated media (with alt text), self-hosted web fonts, the navigation tree, header/footer and news-listing template overrides, global styles, and site settings, all declared in content/site.json. bin/provision applies it over the WordPress REST API and is create-only: an item that already exists (matched by slug) is skipped and reported, never modified, so it's safe to re-run against an environment editors already own.

Overwriting an existing item needs an explicit --overwrite SECTION[,SECTION...] (sections: media, pages, posts, navigation, template-parts, templates, global-styles, site-branding, settings, cleanup). bin/provision --only SECTION[,SECTION...] separately limits which sections run at all (same section list, plus fonts) -- e.g. the brand rollout is:

bin/provision --base-url ... --user ... --app-password '...' \
    --only media,fonts,template-parts,global-styles,site-branding \
    --overwrite template-parts,global-styles,site-branding

which never touches pages, posts or navigation. Add --dry-run to either form to list what would be created, overwritten, skipped or deleted without writing anything. See docs/branding.md for the brand implementation (palette, logo renders, IBM Plex Sans with the FF Real swap plan) and bin/hero-variant for the two approved home-hero looks -- it follows the same rule, refusing to write the home page without its own --overwrite.

content/ is the record of how the site was born, not an ongoing source of truth: once real editors own the site in wp-admin, treat it that way. Neither script creates, modifies or deletes WordPress users; accounts (including the post author in content/site.json) are managed in wp-admin.

Bootstrapping a new environment

For a fresh k8s environment (production was set up this way; a wiped staging would be too), no kubectl is needed -- everything runs over https:

bin/remote-bootstrap --base-url https://enact-wp-production.enacthyku.com \
    --title Enact --admin-user notch8-admin --admin-email nick@notch8.com
# prints the generated admin password and a REST application password
bin/provision --base-url https://enact-wp-production.enacthyku.com \
    --user notch8-admin --app-password '<printed above>' \
    --overwrite template-parts,templates,global-styles,settings,site-branding,cleanup

remote-bootstrap runs the install wizard, sets pretty permalinks, and mints an application password. Before running bin/provision, create the post author account (post_author in content/site.json) in wp-admin -- the script looks it up and refuses to create one. The --overwrite list above is needed even on a brand-new install: WordPress ships its own default templates, template parts, global styles and settings, so those sections already "exist" and are create-only skipped otherwise; pages, posts, navigation and media are genuinely new on a fresh site and don't need it. Save everything printed in 1Password immediately; nothing is stored.

Pipeline

Every PR against main runs the Lint workflow, which is really a suite of Helm chart checks shared with Deploy via .github/actions/helm-checks so both stay in sync:

  • helm lint and helm template, against both ops/staging-values.yaml and ops/production-values.yaml
  • kubeconform -- validates the rendered manifests against the real Kubernetes API schema (catches typos/structural mistakes helm lint/helm template won't, e.g. a wrong field name or apiVersion)
  • helm-unittest -- unit tests in wordpress/tests/, e.g. asserting that privateSite.enabled: false actually removes the mu-plugin ConfigMap and its volume mount, and that the required() guards on ingress.hostname / externalSecret.onePasswordItem fire correctly
  • A Trivy config scan of the rendered manifests -- report-only (doesn't fail the build), since the official wordpress/mysql images run parts of their entrypoint as root before dropping privilege, which a hard-fail policy would otherwise block on

Merging to main runs those same checks again, then auto-deploys staging -- deploy.yaml's push: branches: [main] trigger, gated by the same checks job. Production is never auto-deployed; promoting to it is always a deliberate action.

Deploying

Ongoing deployment

Staging deploys itself on every merge to main, once checks pass. For a manual deploy of either environment (including production), trigger the Deploy workflow from the Actions tab and choose staging or production -- same as before, unaffected by the auto-deploy trigger.

One-time setup, before the first deploy of a new environment: the

enact-wp-staging / enact-wp-production namespaces must exist before notch8-ops's github-deploy-sa Terraform can create the github-deploy ServiceAccount inside them (that module deliberately doesn't create namespaces itself -- see terraform/modules/github-deploy-sa/README.md in notch8-ops). Create them by hand once:

kubectl --context enact create namespace enact-wp-staging
kubectl --context enact create namespace enact-wp-production

After that, notch8-ops's ./bin/tf-cosector enact apply (which provisions the github-deploy SA/RBAC/token) and ./scripts/push-github-deploy-kubeconfig.sh --cluster enact (which pushes the resulting KUBECONFIG_FILE secret here) only need to run once per namespace.

Making a site public

Your boss (or anyone with deploy access) can lift the login requirement for an environment independently of anything above -- it's just a Helm value:

  1. In ops/staging-values.yaml or ops/production-values.yaml, change privateSite.enabled to false:
    privateSite:
      enabled: false
  2. Re-run the Deploy workflow for that environment (or ./bin/helm_deploy enact-wp-staging enact-wp-staging locally with HELM_EXTRA_ARGS="--values ops/staging-values.yaml").

That's it -- no plugin to uninstall, no file to delete. Setting privateSite.enabled back to true and redeploying restores the login wall.

Site hardening

A one-file mu-plugin, wordpress/files/mu-plugins/site-hardening.php (controlled by the siteHardening.enabled value, true by default, mounted the same way as two-factor-policy.php), stops anonymous visitors from discovering account logins even once the login wall above is off:

  • /wp-json/wp/v2/users and /wp-json/wp/v2/users/<id> return 401 to anonymous requests (logged-in requests still work -- the block editor's author picker needs them).
  • ?author=<id> and /author/<slug>/ return 404 instead of redirecting to the username's archive URL.
  • The users sitemap (/wp-sitemap-users-1.xml) is disabled.
  • A wrong password and an unknown username show the same wp-login error.
  • Any account whose display name still matches its login (e.g. a fresh notch8-admin install) gets a generic display name, since bylines and oEmbed expose it otherwise.

./bin/test-site-hardening runs these checks (plus the case-insensitive REST route match and the author-link fix) against a local docker compose WordPress -- docker compose up -d first, then run it against the wordpress container directly (not ./bin/wp, which runs through the cli service and doesn't have the mu-plugins mounted).

Two-factor authentication

Browser logins use two-factor authentication through the Two Factor plugin, which is maintained by WordPress.org contributors. A must-use plugin, wordpress/files/mu-plugins/two-factor-policy.php, sets this site's policy around it. The chart mounts it into wp-content/mu-plugins/ (controlled by the twoFactor values), and docker compose mounts the same file locally.

What the policy does:

  • Methods are an authenticator app (TOTP) and backup codes. Email codes are switched off because the pods have no outbound mail, so a code would never arrive.
  • Application passwords work only for the logins listed in twoFactor.applicationPasswordUsers (by default notch8-admin, the account bin/provision uses). Requests that authenticate with one skip two-factor; that is the API path. Application passwords issued to anyone else stop working.
  • With twoFactor.enforce: true, a browser session that has not passed two-factor gets view-only access. Someone without an authenticator app is sent to their profile to set one up, and someone with one is sent to the code prompt. The plugin cannot be deactivated from wp-admin. If it goes missing or inactive anyway, every browser session drops to view-only until it is restored, so a missing plugin never leaves password-only access to editing.

Dockerfile bakes a pinned, checksum-verified copy of the plugin into the image (TWO_FACTOR_VERSION), the same way WordPress core itself ships, and it's authoritative: only wp-content/uploads is on the persistent volume (see "Versions"), so every pod start gets exactly this version regardless of anything previously installed there. pluginLockdown.enabled (on by default) also blocks installing a different one from wp-admin or REST.

Turning it on for an environment

  1. Deploy with twoFactor.enabled: true and twoFactor.enforce: false (the current state of both ops/*-values.yaml files). The plugin ships in the image already (see above) -- it just needs activating.
  2. Activate it over REST. Activating an already-present plugin isn't a file mod, so pluginLockdown.enabled doesn't block it (installing one would):
    curl -sS -u 'notch8-admin:<application password>' \
      -H 'Content-Type: application/json' \
      -d '{"status": "active"}' \
      'https://<hostname>/?rest_route=/wp/v2/plugins/two-factor/two-factor'
  3. Each account holder sets up an authenticator app under Users > Profile > Two-Factor Options and saves their backup codes. Administrators go first.
  4. Set twoFactor.enforce: true in that environment's values file and run the Deploy workflow.

Anyone who has not enrolled by step 4 is sent to set it up at their next login and has view-only access until they do.

Recovery

  • Lost phone: sign in with a backup code, then set the app up again on the profile page. Without backup codes, another administrator can turn two-factor off for that account (Users > edit the user > Two-Factor Options), and the person re-enrolls at their next login.
  • Plugin inactive (everyone is view-only): activate it with the step 2 command.
  • Plugin missing entirely: redeploy. pluginLockdown.enabled blocks installing one back from wp-admin or REST on purpose -- it's meant to come from the image, not either of those.
  • Last resort: set twoFactor.enforce: false and redeploy. That lifts the gate without anyone needing cluster access. Set it back afterwards.

Layout

  • wordpress/ -- the Helm chart. WordPress is the parent chart; wordpress/charts/mysql/ is a nested subchart for its database. One helm install deploys both.
  • ops/staging-values.yaml, ops/production-values.yaml -- the only per-environment differences (hostname, which 1Password item backs the DB credentials). Everything else is shared via wordpress/values.yaml.
  • content/ -- the site seed (pages, posts, media, navigation, styles, settings) declared in content/site.json; see "Site content as code".
  • bin/provision -- applies content/ to any environment over the REST API.
  • bin/remote-bootstrap -- one-time install wizard + permalinks + application password for a fresh remote environment.
  • bin/wp -- wp-cli against the local docker compose instance.
  • docker-compose.yml -- local development mirror of the deployment; also what builds and pushes the image in CI (see "Versions").
  • Dockerfile, bin/image-tag -- the pinned WordPress image's build and its content-addressed tag; see "Versions".
  • bin/helm_deploy RELEASE_NAME NAMESPACE -- thin wrapper around helm upgrade --install used by both local and CI deploys. NAMESPACE must already exist (see one-time setup below).
  • .github/actions/helm-checks/ -- composite action with the actual chart checks (lint, template, kubeconform, helm-unittest, Trivy); see Pipeline above.
  • .github/workflows/lint.yaml -- runs helm-checks on every PR against main.
  • .github/workflows/deploy.yaml -- runs helm-checks, then deploys. Auto-deploys staging on push to main; workflow_dispatch also covers manual deploys to either environment.
  • wordpress/tests/ -- the helm-unittest test suites.
  • wordpress/files/mu-plugins/ -- must-use plugin sources the chart mounts via ConfigMap (and docker compose mounts locally); see "Two-factor authentication".

Secrets

Database credentials never touch GitHub. Each environment's ExternalSecret (wordpress/templates/externalsecret.yaml) pulls from a 1Password item via its own per-vault ClusterSecretStore on the enact cluster (1Password SDK provider, scoped read-only to that one vault):

  • onepassword-enact-staging -> enact-staging vault -> wordpress-mysql-staging-enact
  • onepassword-enact-production -> enact-production vault -> wordpress-mysql-production-enact

Each item needs root-password, wordpress-password, and the eight WordPress auth keys/salts (auth-key, secure-auth-key, logged-in-key, nonce-key, auth-salt, secure-auth-salt, logged-in-salt, nonce-salt) -- since /var/www/html no longer persists, wp-config.php is regenerated on every pod start, and these have to come from the secret rather than docker-entrypoint.sh's own random defaults, or every restart logs everyone out. The resulting Kubernetes Secret is mounted directly into both the WordPress and MySQL pods -- no duplication into GitHub Actions secrets.

The only thing GitHub Actions holds is KUBECONFIG_FILE per environment, a namespace-scoped github-deploy service account token (see notch8-ops's terraform/modules/github-deploy-sa).

Before the first rollout of this PVC change

Once the subPath mount lands, /var/www/html stops being the persisted volume (only wp-content/uploads is), so the running pod's wp-config.php -- and whatever auth keys/salts it currently has -- becomes unreachable after cutover. Copy the 8 keys/salts into each environment's 1Password item before rolling this out, from the pod that's about to be replaced:

kubectl exec -n <namespace> deploy/<release>-wordpress -- \
  grep -E "define\( *'(AUTH_KEY|SECURE_AUTH_KEY|LOGGED_IN_KEY|NONCE_KEY|AUTH_SALT|SECURE_AUTH_SALT|LOGGED_IN_SALT|NONCE_SALT)'" \
  /var/www/html/wp-config.php

Also confirm nothing was installed through wp-admin that only lives on the old full-volume mount -- any plugin or mu-plugin added outside of this chart's image/ConfigMaps won't survive the cutover to an uploads-only PVC.

Backups

The enact cluster's daily-full-cluster Velero schedule fs-backs-up (kopia) every PVC in both namespaces nightly, 7-day retention. A raw copy of MySQL's data files isn't guaranteed consistent on its own, so the mysql deployment carries a pre.hook.backup.velero.io/command annotation (wordpress/charts/mysql/templates/deployment.yaml) that runs mysqldump --single-transaction --all-databases into .backup/dump.sql.gz on the same (backed-up) data volume before each snapshot -- the leading dot keeps mysqld's own datadir scan from treating it as a database on restart.

Testing a restore without touching production (verified 2026-11-09, pods booted with pages, media, and fonts intact): restore into a scratch namespace instead of the real one, so it can run alongside the live site untouched.

velero restore create --from-backup <name> \
  --include-namespaces enact-wp-production \
  --namespace-mappings enact-wp-production:<scratch-ns> \
  --exclude-resources ingresses.networking.k8s.io,certificates.cert-manager.io,certificaterequests.cert-manager.io

Excluding Ingress/Certificate stops the restore from fighting over the real hostname/cert. siteurl in the DB still points at the real domain, so the site 301/302s anything that doesn't arrive as that Host header or over HTTPS -- check content directly instead (kubectl exec into the pods, or curl -H "Host: <real-hostname>" through a port-forward).

Restoring production for real is a different, higher-stakes operation, not just the same command without --namespace-mappings:

  • Don't exclude Ingress/Certificate this time -- you want the real site back, not a copy next to it.
  • Velero skips any resource that already exists rather than overwriting it, so first scale enact-wp-production-mysql and -wordpress to 0 and delete the PVC(s) you're recovering (or pass --existing-resource-policy update) -- restoring files underneath a running mysqld risks corrupting it further.
  • This means real downtime, unlike the scratch-namespace test.
  • enact-wp deploys via its own GitHub Actions workflow, not ArgoCD, so nothing auto-syncs over a manual restore -- but avoid merging/pushing to main mid-recovery, since a concurrent deploy would race it.
  • If only the database is affected (media/fonts are fine), restore just the mysql PVC, or skip Velero entirely and pipe the dump back in: gunzip -c .backup/dump.sql.gz | MYSQL_PWD=$MYSQL_ROOT_PASSWORD mysql -uroot.

Retention: 7 days (daily-full-cluster's ttl) is the decided retention for both namespaces, same as every other namespace on that schedule -- UoW's editors are a small group likely to notice a content problem within days. Revisit if that stops being true.

Versions

WordPress runs from a pinned image, not a floating tag: Dockerfile builds ghcr.io/notch8/enact-wp FROM wordpress:7.1.4-php8.3-apache, pinned by digest -- the same build docker-compose.yml uses locally and CI publishes to GHCR. The image tag itself is content-addressed -- bin/image-tag hashes Dockerfile, so a commit that doesn't touch it reuses the image already published for that content, and deploy.yaml's build-image job skips rebuilding it. Bump WP_VERSION (and the FROM line's digest) to pick up a new WordPress or PHP release -- the en_GB language pack URL is derived from WP_VERSION, not a separate literal, so there's nothing else to edit there.

The image also bakes in a pinned, checksum-verified copy of the Two Factor plugin (TWO_FACTOR_VERSION/TWO_FACTOR_SHA256) and the en_GB core language pack (WP_LANG_EN_GB_SHA256), staged where docker-entrypoint.sh seeds a fresh /var/www/html. Neither checksum is published anywhere Renovate (or a human bumping either version by hand) could just read -- .github/workflows/fix-dockerfile-checksums.yaml recomputes and commits both on any PR that touches Dockerfile.

Only wp-content/uploads persists (persistence in wordpress/values.yaml) -- core, plugins, and mu-plugins all come from the image on every pod start, which is what makes the baked-in Two Factor plugin and pluginLockdown.enabled (see "Two-factor authentication") actually take effect, rather than being shadowed by whatever was previously installed on the old whole-volume mount.

mysql is pinned the same way (mysql.image.tag in wordpress/values.yaml), matching what's actually running rather than the ticket-era assumption that lts meant 8.4; it's moved on to the 9.x line since. Renovate (renovate.json) opens a PR when a newer digest exists for either image or for GitHub Actions; the matching checksums Renovate can't look up anywhere get recomputed and committed automatically by .github/workflows/fix-dockerfile-checksums.yaml (bin/fix-dockerfile-checksums).

About

Wordpress site for Enact project - see also https://github.com/research-technologies/enact_knapsack

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages