Documentation

# GO! — Public Artifact Demo Deployment Protocol ## Activation This package makes the public-demo deployment resumable. Its existence is not authorization to change the repository, VPS, DNS, or provider firewall. The exact instruction `GO`, when it refers to deploying the rad-nlp public demo, adopts and activates `DEP-000` through `DEP-006`. After activation, continue through every ready ticket without asking for routine supervision. The adopted target is the artifact-backed demonstration on `168.235.65.28`. It does not authorize deploying the live Python/Prolog NLP stack, accepting arbitrary transcription, moving the existing `v0.1.0` tag, or publishing material outside the documented allowlist. ## Required reading At activation or resumption, read the durable sources rather than relying on a conversation summary: 1. the applicable machine and project agent instructions; 2. `../PUBLIC-DEMO-DEPLOYMENT-PLAN.md`; 3. `STATE.md`, `DECISIONS.md`, and `ACCEPTANCE-MATRIX.md`; 4. the active ticket, or the lowest-numbered ready ticket; 5. the ticket's cited deployment-plan sections; and 6. the current implementation and tests in every area the ticket will change. ## Adopted execution boundary ~~~text DEP-000 freeze authority and establish baselines ↓ DEP-001 establish named administration and harden Debian ↓ DEP-002 implement the allowlisted public-demo application profile ↓ DEP-003 build, inspect, and verify an immutable release bundle ↓ DEP-004 deploy and accept the release on VPS loopback ↓ DEP-005 activate DNS, TLS, and public web ports ↓ DEP-006 prove restart/rollback/recovery and complete the handoff ~~~ Only the final two phases make the application publicly reachable. TCP 80 and 443 remain closed through DEP-004. ## Required operator inputs The execution uses these explicit values: ~~~sh export DEMO_SSH_KEY=/home/raddev/.ssh/id_ed25519 export DEMO_BOOTSTRAP_HOST=root@168.235.65.28 export DEMO_HOST=radnlp-admin@168.235.65.28 export DEMO_ADMIN_SOURCE_IPV4=107.161.20.175 export DEMO_ARCH=amd64 export DEMO_RELEASE=v0.1.1 export DEMO_DOMAIN=nlp-and-expert.elementsketchpad.com ~~~ The SSH key is operated on by path. Its private contents are never printed, embedded, copied to the VPS, or placed in an artifact. Control of the supplied domain's DNS record is the remaining external fact required before DEP-005. The domain currently returns Cloudflare proxy addresses, not the VPS address. That does not block DEP-000 through DEP-004. DEP-005 requires changing only this record to DNS-only A `168.235.65.28` and removing AAAA unless origin IPv6 is confirmed. Provider-console recovery is not part of the adopted model. DEP-001 instead preserves the current root session and key-only root login, restricts SSH to RADPAIR's confirmed `107.161.20.175/32`, and wraps every live firewall change in a timed automatic rollback. ## Execution loop 1. Confirm `STATE.md` records adoption after the deployment `GO`. 2. Resume the one `in_progress` ticket, or select the lowest ready ticket. 3. Update the ticket and `STATE.md` to `in_progress` together. 4. Establish the ticket's narrow baseline before changing anything. 5. Preserve unrelated user changes and the dirty UCxn source submodule. 6. Implement the complete ticket obligation. 7. Run narrow tests first, then the ticket gate, then inherited regressions. 8. Record exact commands, outcomes, digests, service state, and deviations. 9. Mark acceptance rows passed only from named executable or observed evidence. 10. Update the ticket, state, decisions, and acceptance matrix together. 11. Continue immediately to the next ready ticket. Only one ticket may be `in_progress`. ## State machine ~~~text planned → ready → in_progress → complete └────────→ blocked ~~~ `blocked` means that safe progress requires an unavailable external input, provider action, or authority outside this protocol. A failing test, package surprise, configuration error, or difficult implementation problem is not a blocker while safe diagnostic and corrective work remains. ## Host mutation discipline - Start every mutating host ticket with a fresh read-only inventory. - Save the prior configuration before replacing a firewall, SSH, systemd, or Caddy file. - Resolve destructive targets to explicit paths; do not use broad globs. - Keep an existing root session open until two named-administrator sessions and noninteractive sudo pass. - Validate nftables and SSH syntax before loading or reloading them. - Reload SSH, never terminate the last verified session during a policy change. - Force administrative SSH over IPv4 and verify that the VPS sees RADPAIR as `107.161.20.175` before applying an SSH allowlist. - Permit TCP 22 only from `107.161.20.175/32`. - Schedule an automatic restoration of the prior firewall rules before every live firewall change and cancel it only after fresh administrator and root sessions pass. - Keep key-only root login from RADPAIR as the no-console recovery path. - Keep TCP 80/443 closed until VPS loopback acceptance and Caddy validation pass. - If public activation fails, close 80/443 and retain SSH recovery. - Never expose 8170, 5355, Python, Prolog, model, or database ports. ## Application and release discipline - Select routes at registration time from an explicit `research` or `public-demo` profile. - The public profile contains only the reviewed transcription and immutable R0–R5 artifacts. - Do not deploy the full corpus, historical reports, evaluation state, credentials, private resources, or machine-specific operational documents. - A dirty worktree cannot produce a promotable release identity. - The release archive is allowlisted, checksummed, scanned, and run outside the checkout before upload. - Releases are installed in immutable directories and promoted atomically. - `v0.1.0` is never moved. The adopted public-demo release is `v0.1.1` unless the human changes that identity before activation. ## Verification hierarchy Where applicable, verify in this order: ~~~text unit and route-registration tests → public-profile application tests → local bundle inventory and digest checks → unpacked-bundle smoke outside the checkout → Debian configuration syntax checks → VPS loopback acceptance with web ports closed → public HTTPS acceptance and route denial → process restart and host reboot → rollback and restoration ~~~ The broad final gate includes existing interpreter and infrastructure regressions. Deployment success may not be obtained by weakening current R0–R5, security-header, SPA, accessibility, or documentation behavior. ## Decision discipline Record durable choices affecting public routes, data inventory, host access, firewall policy, release identity, TLS, rollback, logging, or truthfulness in `DECISIONS.md`. Small implementation choices that preserve the plan do not require human approval. If evidence contradicts the deployment plan, stop the contradictory mutation, record the evidence, and surface the mismatch. Do not silently reinterpret a security or data boundary to keep moving. ## External side-effect boundary The deployment `GO` authorizes repository implementation, new commits and the `v0.1.1` tag, and SSH changes on the named VPS within these tickets. It does not authorize purchasing services, changing unrelated DNS records, changing a provider account, or pushing to an external Git remote. DNS and provider-firewall changes are performed by the human unless the specific control interface is later supplied and explicitly placed in scope. The agent prepares exact required values, verifies the observed result, and continues once the external state is correct. ## Stop conditions Continue until one of these conditions holds: 1. **Complete:** DEP-000 through DEP-006 and every acceptance row pass, the public HTTPS URL is healthy, restart and rollback are proven, and the final deployment report is recorded. 2. **Externally blocked:** DNS control or another required external action is unavailable after all safe independent work is complete. 3. **Unsafe or outside scope:** continuation would risk lockout, publish unapproved data, deploy arbitrary-input NLP, or mutate an unrelated system. When blocked, update `STATE.md` and the active ticket with the exact condition, evidence, completed safe work, and first action required to resume. ## Completion handoff Completion records: - the public URL and resolved address; - application version, commit, tag, archive digest, and artifact digests; - effective public route and port inventories; - Debian, nftables, SSH, systemd, and Caddy verification evidence; - public acceptance results; - restart, reboot, rollback, and restoration results; - monitoring and update commands; - any explicit temporary security exception; and - a statement that this is an artifact-backed research demo, not a clinical or live-NLP service.