Docs: Production deployment guide (nginx + AOT binary + CGI/FastCGI)

[PurHur]

Problem

README documents dev workflows (phpc serve, phpc serve --aot) but not a single production narrative from phpc build → live site behind nginx.

Pieces exist across closed issues:

• Docs: deploy-web-aot.md quickstart (phpc deploy + PHPC_DEPLOY_ROOT + nginx CGI) #635 ✅ docs/deploy-web-aot.md quickstart (phpc deploy, PHPC_DEPLOY_ROOT, nginx CGI snippet)
• AOT: phpc deploy bundles binary, public/, assets/, and phpc.json into dist/ #609 ✅ deploy CLI
• Web: AOT CGI wrapper for phpc-built binaries (production nginx spawn) #665 ✅ AOT CGI wrapper
• Web: FastCGI request loop adapter (nginx / php-fpm compatible) #173 FastCGI adapter (open)

Contributors still grep #50, #180, #443 for the full story.

Goal

Umbrella production deployment guide (extend docs/deploy-web-aot.md or add docs/deploy-production.md) covering:

1. Build + deploy — phpc build --project, phpc deploy, dist layout (#609, #635)
2. Static assets — nginx alias for assets/ / public/ (#696)
3. CGI — per-request env (QUERY_STRING, REQUEST_METHOD, PATH_INFO, …) — Web: Runtime-populated superglobals for JIT and AOT (per-request $_GET/$_POST) #49, Web: AOT CGI wrapper for phpc-built binaries (production nginx spawn) #665
4. FastCGI — nginx fastcgi_pass pool — Web: FastCGI request loop adapter (nginx / php-fpm compatible) #173 (when implemented)
5. TLS termination — reverse proxy in front of CGI (illustrative only)
6. Security — body limits Security: Request body size limits and header sanitization in CGI driver #77, PHP_COMPILER_DEBUG, path traversal, contact validation Security: MiniWebApp contact POST validation and body limits (dev + deploy) #697
7. Local smoke before deploy — make examples-web-smoke, phpc cgi on dist, optional --aot (Testing: ServeAotTest MiniWebApp routes via phpc serve --aot (blocked #764 execute) #478, Testing: CgiDriverTest MiniWebApp PATH_INFO via AOT cgi-wrapper (blocked #764) #682)

Implementation hints

Section	Source issues	Files
Quickstart (done)	#635	docs/deploy-web-aot.md
nginx CGI	#665, #50	bin/cgi-aot.php, docs/deploy-web-aot.md
Static files	#696	examples/003-MiniWebApp/assets/
FastCGI	#173	new lib/Web/FastCgi*.php TBD
MiniWebApp AOT	#568, #445	blocked until native link
Checklist	#472, #657	phpc doctor --gates

Suggested doc outline

1. Prerequisites (LLVM, Docker image php-compiler:22.04-dev)
2. Build/deploy commands (002 green, 003 blocked note)
3. Dist tree diagram (bin/app, cgi-wrapper, assets/, templates/)
4. nginx server block (CGI + static locations)
5. FastCGI appendix (stub until Web: FastCGI request loop adapter (nginx / php-fpm compatible) #173)
6. Operations (env vars, logs, upgrading binary)
7. Verification commands (local only)

Acceptance criteria

• Production sections committed; README “Deploying” links to the canonical doc
• Copy-paste nginx blocks marked illustrative (not CI-tested)
• All verification steps use local/Docker commands only (Disable github actions for now #394 GHA off)
• Cross-links Docs: deploy-web-aot.md quickstart (phpc deploy + PHPC_DEPLOY_ROOT + nginx CGI) #635 (quickstart) vs this umbrella (depth)

Verification (review)

./phpc deploy examples/002-StaticWeb -o /tmp/static-dist
phpc cgi /tmp/static-dist/bin/app
make examples-web-smoke

Optional: script/check-doc-links.sh if link checker exists.

Dependencies

• Docs: deploy-web-aot.md quickstart (phpc deploy + PHPC_DEPLOY_ROOT + nginx CGI) #635 ✅ quickstart (do not duplicate — extend)
• AOT: phpc deploy bundles binary, public/, assets/, and phpc.json into dist/ #609 ✅ deploy CLI
• Web: AOT CGI wrapper for phpc-built binaries (production nginx spawn) #665 ✅ AOT CGI
• Web: FastCGI request loop adapter (nginx / php-fpm compatible) #173 FastCGI (section can be stub until landed)
• AOT: Native user-class object model for phpc build --project #568 MiniWebApp native binary (document blocked state)
• Docs: nginx static assets (alias) for AOT deploy dist #696 static assets nginx section (can land in parallel)

Non-goals

• Publishing containers to a registry (Infrastructure: Publish Docker dev image and document container CI workflow #202)
• GitHub Actions deploy workflows (CI: Add GitHub Actions workflow for PHPUnit (VM, compliance, real, AOT) #47 / Disable github actions for now #394 closed)

Links

• docs/deploy-web-aot.md
• examples/README.md
• 🗺️ ROADMAP: Compile a small PHP web application (living document) #78 ROADMAP Phase 3–4

[PurHur]

Quickstart slice tracked in #635 (docs/deploy-web-aot.md). This issue remains the full production guide (nginx, FastCGI #173, security #77). Depends on #609 ✅ deploy CLI.