# Phone Buzz private staff pilot — DevOps handover

Prepared 2026-10-15; updated 2026-10-22 (Asia/Karachi). Scope: deploy the new staff web/API platform on a separate Linux VPS for a restricted synthetic-data pilot. Keep the existing PHP website and its customer/wholesaler accounts on their current host. This document is ready to share with the responsible operator; it has not been sent to anyone.

## Hosting-specific recipe

For `phonebuzz.onlinetestingserver.com`, use [CPANEL-DEPLOYMENT.md](CPANEL-DEPLOYMENT.md) and `compose.cpanel.yml` behind the existing Apache service. Its new source candidate is `cpanel-20261022-01`. The original standalone candidate below remains a separate immutable package. Do not start its Caddy proxy on this host: ports 80/443 are occupied. The cPanel account currently lacks Docker daemon permissions; an authorized operator must deploy.

## Before installation

Owner/operator must record the server identity, SSH administration method, two unused staging DNS names, certificate-notice email, allowed office/VPN IP ranges, responsible operator and initial staff administrator. Exchange SSH access and credentials privately. Do not put passwords, keys, database dumps, application logs with customer content or `.local` folders in chat/tickets.

Use Python 3.12+ for the API/tools, PostgreSQL 17, Linux Docker Engine and Compose v2.24+. Size the VPS separately for the application and, if requested, local-model inference; the laptop smoke result is not a server capacity measurement. CPU-only model provisioning is optional and documented in [SERVER-AI.md](SERVER-AI.md). No server or paid service has been selected or purchased by the development work.

## Release identification

The 2026-10-22 refresh updates dependency-review and handover documentation only; application code and locks are unchanged. The two mobile-tooling advisories remain unresolved (see DEPENDENCY-REVIEW.md).

The current source candidate is `pilot-20261022-01`. Deliver its ZIP, adjacent `.sha256` and `RELEASE-MANIFEST.json` from the private release directory. Confirm the expected ZIP digest through a trusted channel. The manifest records the exact source-file digests and migration head; it is not a signature, built image or deployment approval.

Follow [PILOT-PACKAGE.md](PILOT-PACKAGE.md) to verify the checksum, extract into a new private directory and run the read-only host preflight. Never extract over a running installation or into `public_html`. Using the verifier from the checked package, compare the selected extracted source with the trusted ZIP:

```sh
python3 scripts/package-staging.py compare \
  --archive /private/releases/phonebuzz-pilot-20261022-01.zip \
  --sha256 EXPECTED_TRUSTED_ZIP_SHA256
```

The example archive location and digest must be replaced with the actual values. Exit 0 means all selected source files match; exit 1 means mismatch/invalid input. The JSON lists missing, changed and unexpected selected files, without file contents. Private settings, dependencies, build products and databases are intentionally excluded. This is a source identity check, not a full filesystem/security scan. Repeat it before builds and after hand edits; do not proceed using an unexplained mismatch.

Before installation, run the [combined offline release check](RELEASE-CHECK.md) in an API Python environment with the locked dependencies. Keep its private receipt with the trusted archive. It checks the extracted source and synthetic workflow/recovery; a passing receipt is not hosted or staff acceptance.

## Installation and acceptance order

1. **Prerequisites:** run `python3 scripts/check-host.py`. Record its results. Fix failed prerequisites before continuing.
2. **Private configuration:** follow [STAGING.md](STAGING.md) to generate new settings/keys with the actual hostnames and allowed networks. Run `python3 scripts/check-host.py --require-config`. Keep all integrations disabled initially. Never run the initial setup generator over an existing installation.
3. **File protection and build:** provision the local scanner and include `compose.scan.yml` using [PILOT-HARDENING.md](PILOT-HARDENING.md). Production file uploads/imports/downloads fail closed until this is configured; run the explicit clean/test-marker probe and record signature freshness. Migration `31c8b020d6a1` adds shared sign-in admission counters; `42d9c131e7b2` adds retained delivery-report evidence; `53eac242f8c3` adds administrator investigation history and current head `64fbd353a9d4` adds case responsibility/deadline history, without historical backfill. Back up before upgrading. Follow the staging runbook's database initialization, migration/grant and application startup order. Record the source release, migration head, all resolved image digests, build time and operator. Linux image build/startup remains unverified on the development Mac.
4. **Access:** verify DNS/TLS, allowed and denied external networks, no public API/database/model ports, secure cookies and rejection of untrusted browser origins. Verify a fresh matching CSP/script nonce on repeated workspace loads, no-store document responses, production script execution restrictions and preserved attachment sandbox headers; see BROWSER-PROTECTIONS.md. Do not add CDN caching or HTML rewriting to the workspace document. `/ready` must pass, but does not establish full functionality.
5. **Staff exercise:** use temporary synthetic accounts/data for sign-in/MFA, manual stock/wanted matching, exact quote totals, separate quote approval, customer acceptance, separate order confirmation, IMEI allocation/dispatch, private attachments and delivery/return quarantine. Include viewer denial checks. The local [15-checkpoint rehearsal](PILOT-REHEARSAL.md) is a repeatable API precheck. The [local HTTPS browser suite](LOCAL-HTTPS.md) exercises the production web build with synthetic data; real hosted HTTPS/browser staff acceptance is separate.
6. **Recovery:** stop writers and follow the coordinated PostgreSQL/files/MFA-key backup and isolated restore procedure in STAGING.md. Verify restored MFA sign-in, records, attachments and continued workflow. Record duration and evidence; protect an encrypted off-server backup. A database-only backup is incomplete.
7. **Operations:** agree operator coverage, incident escalation, disk/certificate/backup monitoring, retention, patching and account/MFA policies. Exercise worker failure visibility and recovery on staging. Independent security and representative load review remain required.
8. **Optional AI:** provision the private model only after the base stack is healthy. Record the image/model digest, remove download-network access and run synthetic diagnostics per SERVER-AI.md. Keep teaching off until representative staff examples, separate evaluation data and acceptance thresholds are available. Then use the read-only [assistant comparison](ASSISTANT-BENCHMARK.md) and [supplier extraction comparison](EXTRACTION-BENCHMARK.md) in the API image; a completed run is not automatic approval to enable teaching.
9. **Pilot decision:** record which gates passed, evidence locations, unresolved issues, responsible owners and explicit staff sign-off. Keep excluded features disabled. Do not call the environment production-ready because containers start or automated tests pass.

Live email testing remains deferred. WhatsApp/Meta setup, push activation, formal tax invoice details/implementation and public customer access remain outside this pilot. iOS/Android exports are unsigned; signed builds and physical-device checks remain pending. The refreshed 2026-10-15 dependency audit still flags two underlying Expo/Metro tooling advisories; see [DEPENDENCY-REVIEW.md](DEPENDENCY-REVIEW.md).

## How development and server updates stay connected

The server does not automatically sync with the local project. Use explicit versioned release packages initially. DevOps keeps a private deployment record mapping source checksum → built image digests → schema revision → backup identifier → deployment time/operator. Share sanitized pass/fail summaries and reproducible steps for issues; development produces a new immutable candidate for review. Never copy real databases/keys back into source control or this upload package.

For updates, preserve private settings and persistent volumes, verify the new source, build/tag new images, take and verify the coordinated backup, stop writers and run the migration service explicitly. Follow STAGING.md for startup and failure handling. An old image may be incompatible with a new schema; rollback requires a reviewed compatible plan or complete backup restoration into an isolated installation. Do not use `down -v` as an update step.

## Return record

The operator should return a sanitized record with these fields:

| Field | Required evidence |
| --- | --- |
| Release | Source label, trusted ZIP SHA-256, source comparison result |
| Build | Linux/Docker/Compose versions and web/API/database/proxy image digests |
| Offline release | Exact ZIP/source hashes, locked dependency check, migration/evaluator checks and 15 synthetic workflow/recovery checkpoints from RELEASE-CHECK.md |
| File protection | Scanner probe, engine/signature update age, representative file limits, unavailable-scanner rejection and recovery |
| Sign-in admission | Concurrent worker budget checks, expected staff login capacity and upstream limits |
| Schema/startup | Migration head, successful migration/grant exit, `/ready` result |
| Access | Approved staging URLs, allowed/denied-network and TLS results |
| Workflow | Named tester, date, passed/failed staff scenarios and issue references |
| Recovery | Protected backup identifier, isolated restore result, duration, MFA/file verification |
| Model, if enabled | Local image/model digest, smoke result, observed timing, teaching state |
| Open items | Responsible owner, evidence needed and whether pilot access is blocked |

Do not include passwords, tokens, seeds, backup codes, private keys, resolved secret-bearing configuration or customer content. Keep detailed private evidence on the authorized operator system. See [RELEASE-READINESS.md](RELEASE-READINESS.md) for the remaining gates.