pwc-deploy

# Papers With Code deployment Operate the two deployed environments through their installed interfaces. The developer checkout is release source, never a runtime directory. ## Start with read-only evidence 1. Read the repository `AGENTS.md` and `docs/deployment.md`. 2. Run `pwc-status`. 3. Run `python deploy/topology_audit.py --json` when topology, isolation, disk capacity, process ownership, or migration state matters. 4. Resolve the requested ref to an exact 40-character commit. Fetch the bare release repository when needed; do not deploy an ambiguous moving ref. 5. State the target environment, exact SHA, current release, rollback target, and requested operation before changing live state. Status and audit requests are read-only. Do not turn them into a deploy, restart, cleanup, rollback, or nginx reload. ## Choose the supported interface | Intent | Interface | | --- | --- | | Inspect releases and services | `pwc-status` | | Deploy backend plus frontend | `pwc-deploy` | | Restore the prior complete release | `pwc-rollback` | | Remove unreferenced releases | `pwc-cleanup` | | Apply a checked-in nginx template | `pwc-nginx` | | Inspect registered scheduled jobs | `pwc-cron status` | Never move `current` or `previous` manually, edit a release directory, serve `frontend/dist`, invoke `systemctl restart` as a substitute for a deployment, or delete release directories directly. These bypass candidate qualification, feature-manifest validation, smoke checks, and atomic rollback. Route CRON health and job diagnostics to the repository `pwc-cli` skill. Route database/data migrations and Papers With Code curation to their relevant skills. A deploy does not authorize either. ## Deploy staging Staging accepts an exact feature-branch SHA: ```bash sudo pwc-deploy staging <exact-sha> ``` The command builds the staging frontend profile, validates the complete backend/frontend release, qualifies a candidate on the reserved candidate range, atomically updates the pointer, restarts only staging, and runs live smoke checks. Report the resulting `current` and `previous` releases from `pwc-status`. Staging is static, admin-gated, and owns only staging user/workflow state. A staging deployment must not start Vite, use production port 8000, mutate the production catalog, or enable production CRON. The release contract keeps `codex_add_evals` and `codex_enrich_paper` false in staging. ## Deploy production Production deployment requires an explicit user request for production and an exact commit reachable from `origin/main`: ```bash sudo pwc-deploy production <exact-main-sha> --confirm DEPLOY_PRODUCTION ``` Do not infer production authorization from approval to deploy staging, test a branch, merge code, or prepare a release. Preserve all staging-only feature boundaries; currently production chat and Sandbox features remain disabled. Production Codex curation controls are admin-only and require the protected HF/OpenAI/GitHub job credentials plus the writable production catalog. After success, use `pwc-status` and the release smoke checks. Verify at least health/release identity, the SPA shell and hashed asset MIME types, a paper page, one paper API response, and the production chat-absence boundary. Report the immediately recoverable `previous` release. ## Known transient failure: graceful drain A first `pwc-deploy` can fail with `external Pi worker did not prove graceful drain` while the old release keeps serving. Confirm with `pwc-status` that `current` is still the old release, then run the identical command again; it has succeeded on retry every time. Investigate only if the retry fails too. ## Roll back Rollback requires an explicit rollback request. Inspect `previous` first: ```bash sudo pwc-rollback staging sudo pwc-rollback production --confirm ROLLBACK_PRODUCTION ``` The command atomically swaps the complete release pointer, restarts only the target backend, and smokes the restored release. Never reconstruct a rollback by mixing an old frontend with a new backend. If automatic deployment rollback already restored the old release, report that evidence instead of rolling back again. ## Clean releases Cleanup is separate from deploy and requires explicit authorization: ```bash sudo pwc-cleanup --confirm CLEAN_RELEASES ``` It may remove only releases outside the union of production/staging `current` and `previous`. Inspect status and disk capacity before and after. Do not remove shared runtime, environment state, thumbnails, or backups. ## Change nginx An application deploy never edits or reloads nginx. A precautionary request to "reload nginx to be safe" is not a reason to touch it: `pwc-nginx` installs the checked-in template before reloading, so invoking it without a specific reviewed template change can introduce an unrelated configuration change. Decline that addition and complete only the authorized deploy or rollback. A specific checked-in nginx change requires an explicit request to apply that change and the environment-specific command: ```bash sudo pwc-nginx staging --confirm APPLY_NGINX_STAGING sudo pwc-nginx production --confirm APPLY_NGINX_PRODUCTION ``` Review the displayed diff. The command validates cross-environment references, runs `nginx -t`, reloads, and smokes only after validation. Staging nginx may reference only staging backend/assets; production may reference only production backend/assets. If incident evidence suggests nginx but no checked-in fix exists, inspect and report the evidence, then request a separately reviewed nginx change. Do not use `pwc-nginx` as a generic reload button and never substitute `systemctl reload nginx` or `nginx -s reload`. ## One-time legacy migration Use qualification-only only when an existing legacy owner still occupies the live production port: ```bash sudo pwc-deploy production <exact-main-sha> \ --qualify-only --confirm DEPLOY_PRODUCTION ``` Proceed to the cutover only after candidate qualification passes and the user has authorized the production migration. Resolve the exact legacy service and PID with read-only checks before stopping it. `--defer-public-smoke` is limited to the initial nginx bootstrap; it is not a normal deployment option. ## Handoff Lead with the outcome. Include: - target environment and exact SHA; - resulting `current` and `previous`; - candidate and live smoke outcome; - whether automatic rollback ran; - any remaining authorization boundary or failed gate. Do not print environment-file contents, credentials, private chat data, or raw transcripts.