PHP Production Deployment Checklist V1

This document tracks the remaining work between the current implementation state and a responsible production deployment.

It is intended to be updated as work completes.

Progress

• Status: in progress

• Runtime/product slices: mostly complete

• Repo-owned production docs/config: completed

• External deployment validation: not started

• Last reviewed: 2026-09-24

Current Findings

The application is no longer blocked on major runtime correctness slices.

Already present in the repo:

• PHP-owned reads and writes

• git-backed canonical write flow

• synchronous read-model refresh on writes

• stale derived-state marker and next-read recovery

• single-instance write/rebuild locking

• Apache .htaccess runtime model for static-first HTML serving

• static artifact generation into public/

• browser identity/bootstrap flow

• HTML template extraction into separate template files

• multi-site config (FORUM_SITE_ID, SiteProfileRegistry) — documented in docs/runbooks/production_deploy.md

• content-hash asset fingerprinting and CSS splitting — documented in docs/specs/asset_fingerprinting_and_css_split_v1.md

• the Application.php decomposition into per-domain namespaces (codebase_cleanup_audit_plan_v1.md) — an internal refactor with no deployment-contract impact; nothing in this checklist needed updating for it

What remains is primarily deployment and operations work rather than core feature construction.

Production Readiness Checklist

1. Deployment Contract

• Document the exact production directory layout

• Document which directories must be writable by the web user

• Document required PHP extensions and server assumptions

• Document the environment variables used in production

• Decide and document where the writable canonical repository lives in production

Status:

• completed in docs/runbooks/production_deploy.md

2. Apache Production Setup

• Add a concrete Apache vhost example for production

• Document DocumentRoot expectations

• Document how .htaccess interacts with AllowOverride

• Document required Apache modules such as mod_rewrite

• Manually verify the full route set on a real Apache host

Status:

• repo-owned documentation completed

• real-host validation still missing

3. Writable State and Permissions

• Document writable state/ expectations

• Document writable repository expectations

• Document ownership/permission expectations for public/ artifact writes if used

• Verify behavior when writable paths are missing or misconfigured in production-like conditions

Status:

• documentation completed

• real host validation still useful

4. Operator Runbook

• Add a production runbook for first-time setup

• Add a runbook for manual read-model rebuild

• Add a runbook for stale-marker recovery

• Add a runbook for lock contention troubleshooting

• Add a runbook for write failure troubleshooting

Status:

• completed in docs/runbooks/production_deploy.md and docs/runbooks/operator_recovery.md

5. Static Artifact Operations

• Document when to build artifacts

• Document when artifacts are invalidated automatically

• Document how to rebuild artifacts manually

• Document the expected public/*.html route layout

• Decide whether production relies on sibling public/*.html artifacts, separate static roots, or both

Status:

• documentation completed

6. Backups and Recovery

• Document what is canonical and must be backed up

• Document what is derived and can be rebuilt

• Document backup expectations for the writable repository

• Document recovery expectations after host failure or bad deploy

Status:

• completed in docs/runbooks/operator_recovery.md

7. Production Smoke Checklist

• Validate anonymous board/thread/profile reads through Apache

• Validate static artifact serving for anonymous queryless routes

• Validate PHP fallback behavior when artifacts are absent

• Validate write flows on the production domain

• Validate browser identity/bootstrap under production cookies/HTTPS

• Validate read-model status visibility in production

Status:

• local automated coverage exists

• real production-like smoke pass is still outstanding

Repo-Owned Deliverables Still Worth Adding

These items belong in the repo and can be completed before deploy:

• docs/runbooks/production_deploy.md

• docs/runbooks/operator_recovery.md

• docs/examples/apache_vhost.conf

• docs/examples/env.production.example

• README links to the deploy/runbook docs

Status:

• completed

External Work That Cannot Be Finished Only In-Repo

These items require the actual host or deployment target:

• create/configure the real Apache vhost

• configure filesystem ownership and permissions

• provision the writable canonical repository location

• test HTTPS/domain/cookie behavior on the real site

• run the final production smoke checklist

Recommendation

The next highest-value repo work is:

1. add the production deploy document

2. add the operator recovery/runbook document

3. add a concrete Apache vhost example

4. add an env/config example

After that, move to a real Apache host and execute the production smoke checklist there.

Progress Log

• 2026-04-10: created this consolidated production deployment checklist document

• 2026-04-10: added production deploy runbook, operator recovery runbook, Apache vhost example, env example, and README links

• 2026-09-24: re-reviewed (doc had gone 5+ months without a review pass). Confirmed all repo-owned deliverables still exist and are current. Multi-site config and asset fingerprinting/CSS splitting landed since the last review and are already covered by production_deploy.md and the new asset_fingerprinting_and_css_split_v1.md spec, so no checklist items needed reopening. The Application.php decomposition was an internal refactor with no deployment-contract surface. No real Apache host validation or production smoke pass has happened yet — the "External Work" and "Production Smoke Checklist" sections are unchanged.