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 |
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.
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.
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-brandingwhich 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.
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,cleanupremote-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.
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 lintandhelm template, against bothops/staging-values.yamlandops/production-values.yaml- kubeconform -- validates the
rendered manifests against the real Kubernetes API schema (catches
typos/structural mistakes
helm lint/helm templatewon't, e.g. a wrong field name orapiVersion) - helm-unittest -- unit
tests in
wordpress/tests/, e.g. asserting thatprivateSite.enabled: falseactually removes the mu-plugin ConfigMap and its volume mount, and that therequired()guards oningress.hostname/externalSecret.onePasswordItemfire correctly - A Trivy config scan of the rendered
manifests -- report-only (doesn't fail the build), since the official
wordpress/mysqlimages 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.
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.
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-productionAfter 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.
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:
- In
ops/staging-values.yamlorops/production-values.yaml, changeprivateSite.enabledtofalse:privateSite: enabled: false
- Re-run the Deploy workflow for that environment (or
./bin/helm_deploy enact-wp-staging enact-wp-staginglocally withHELM_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.
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/usersand/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-admininstall) 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).
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 defaultnotch8-admin, the accountbin/provisionuses). 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.
- Deploy with
twoFactor.enabled: trueandtwoFactor.enforce: false(the current state of bothops/*-values.yamlfiles). The plugin ships in the image already (see above) -- it just needs activating. - Activate it over REST. Activating an already-present plugin isn't a file
mod, so
pluginLockdown.enableddoesn'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'
- Each account holder sets up an authenticator app under Users > Profile > Two-Factor Options and saves their backup codes. Administrators go first.
- Set
twoFactor.enforce: truein 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.
- 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.enabledblocks 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: falseand redeploy. That lifts the gate without anyone needing cluster access. Set it back afterwards.
wordpress/-- the Helm chart. WordPress is the parent chart;wordpress/charts/mysql/is a nested subchart for its database. Onehelm installdeploys 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 viawordpress/values.yaml.content/-- the site seed (pages, posts, media, navigation, styles, settings) declared incontent/site.json; see "Site content as code".bin/provision-- appliescontent/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 aroundhelm upgrade --installused by both local and CI deploys.NAMESPACEmust 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-- runshelm-checkson every PR againstmain..github/workflows/deploy.yaml-- runshelm-checks, then deploys. Auto-deploysstagingon push tomain;workflow_dispatchalso 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".
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-stagingvault ->wordpress-mysql-staging-enactonepassword-enact-production->enact-productionvault ->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).
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.
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-mysqland-wordpressto 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-wpdeploys via its own GitHub Actions workflow, not ArgoCD, so nothing auto-syncs over a manual restore -- but avoid merging/pushing tomainmid-recovery, since a concurrent deploy would race it.- If only the database is affected (media/fonts are fine), restore just the
mysqlPVC, 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.
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).