Update Infrastructure

When to Use

A project involves changes to Forge infrastructure: Railway services, databases, volumes, environment variables, Docker images, or deployment configuration.

Prerequisites

• Access to Railway (via railway MCP or dashboard)
• Current Forge_Infrastructure.md reflects the live state
• Access to the uvilo-mono repository (prodRepoRoot — /workspace/erik@uvilo.com/uvilo-mono) for deployment docs and repo structure

Procedure

1. Read Forge/Forge_Infrastructure.md for current state
2. For current deployment procedures, refer to docs/deployment.md in the uvilo-mono repository (prodRepoRoot — /workspace/erik@uvilo.com/uvilo-mono)
3. For database branching, migration, and environment configuration procedures, refer to the uvilo-mono repository structure
4. If deploying a new service, run the Setup sub-procedure (below) before planning
5. Plan the change — identify every service, variable, and dependency affected
6. Run the persistence checklist (below) for every stateful service touched
7. Execute the change
8. Verify every item in the persistence checklist passes (stateless services: skip if no checklist items apply)
9. Update Forge_Infrastructure.md to reflect the new state — place lessons next to the relevant section, not in a catch-all at the bottom
10. If a lesson has no related section, append it to the bottom “Lessons” section
11. Commit

Setup Sub-Procedure (New Services Only)

Run these steps when adding a service that does not yet exist in the project:

1. Check prerequisites from upstream docs (minimum version, required API surface, auth requirements)
2. Classify the service as stateful (database, search index, queue — needs volume + backups) or stateless (API, UI, proxy — no volume)
3. Generate and store any required secrets before creating the service (store in RoboForm)
4. Create the service: service_create_from_image for Docker images; Railway “Add Database” for stateful data services
5. Set all required env vars and create a public domain
6. Verify the deployment is healthy before proceeding with the rest of the procedure

Persistence Checklist

Run for every stateful service (database, search index, queue, object store) that the change touches:

#	Check	How to verify
P1	Version matches spec/requirements	Check image tag or db.version()
P2	Persistent volume attached	Railway: Volumes tab visible; data survives redeploy
P3	Backups available	Railway: Backups tab exists and is not empty
P4	Connection strings point to correct service	Verify service-specific connection URL / host env vars match the target service
P5	Auth configured and working	Follow the current uvilo-mono deployment docs and repo structure for the touched service; test with that service’s supported client/tooling
P6	If any secrets or env vars have been changed	Prompted Operator to update secrets in RoboForm

If any check fails, stop and fix before proceeding. Do not mark the change complete with a failing check.

Rules

• Never deploy a stateful service without a persistent volume
• Never assume a service version — verify it
• Every infrastructure change must update references/infrastructure_state.md and Forge_Infrastructure.md in the same commit
• Lessons go next to the relevant section; only genuinely unplaceable lessons go at the bottom