Skip to content
Uvilo OS
archived Visibility internal Owner erik@uvilo.com Approver _ Created 2026-05-28 Updated 2026-05-28

Container Base Image Plan 5

Scope: Knowledge extraction — capture all hard-won infrastructure knowledge from this project into permanent, self-contained documents so the environment can be rebuilt from scratch without repeating painful lessons. Prior plan: Container Base Image Plan 6 (archived)

Context

The Alpine→Debian-slim migration was rough because previous setup was inadequately documented. This plan ensures that never happens again by extracting:

  1. A complete declarative description of the environment (update Forge/Forge_Infrastructure.md)
  2. Step-by-step rebuild instructions for disaster recovery (create Forge/Forge_Setup.md)
  3. A disaster recovery plan covering what to back up, how, and how to restore (part of Forge/Forge_Setup.md)
  4. All hard-won learnings folded into permanent docs so we don’t go in circles

Extraction Targets

#Target DocumentContent to ExtractSource
1Forge/Forge_Infrastructure.mdUpdate to fully reflect current Debian-slim reality; remove stale Alpine artifacts; ensure complete declarative descriptionState 4, Dockerfile, Infrastructure doc itself
2Forge/Forge_Setup.mdStep-by-step environment rebuild instructions + disaster recovery planResearch, Dockerfile, startup.sh, State 4, all Learnings
3Forge/Forge_Infrastructure.mdOperational gotchas from Learnings (L5–L18) as first-class documentationLearnings

Task 1 — Update Forge_Infrastructure.md to be a complete declarative description

The current Infrastructure doc is close but has gaps and stale references. It must be a single source of truth for “what exists and how it’s configured.”

  1. Audit every section against the current live environment:
  • Architecture diagram: verify all services, volumes, MCP servers listed match reality
  • Railway IDs: verify project ID, service ID, env ID are current
  • MCP Server Details: verify every server’s command, args, env, startup status
  • Image Details: verify node:22-slim, :debian-slim tag, Configs-debian/ folder
  • Path Constants: verify all paths
  • Environment Variables: verify key vars list
  1. Remove outdated
  • Verify that Alpine Container Constraints no longer apply, and if so, remove section
  • Any reference to Forge/Configs/ that should now be Forge/Configs-debian/
  1. Add any missing declarative sections:
  • Persistent volume contents and structure
  • Docker image build details (3-stage build pattern, key ENV vars)
  • GHCR image naming convention (:debian-slim tag)
  • The UV_SYSTEM_PYTHON=1 ENV var and why it exists

  1. Verify the document is self-contained — no dangling references to the project folder

  2. Make sure all env vars, secrets, etc. and their setup are documented (including .secrets, .internal/.env, env vars in Vercel, GitHub secrets)

Task 2 — Create Forge/Forge_Setup.md — rebuild instructions + disaster recovery

This is the document that, if followed from scratch on a blank Railway account, reproduces the entire Forge environment. It also defines what must be backed up, how, and how to restore.

Structure:

Part A: Disaster Recovery — What to Back Up

  1. MongoDB data — all LibreChat conversations, user accounts, agent configs
  • Backup method: mongodump to local or S3 (automated if possible, manual otherwise)
  • Restore: mongorestore
  • Frequency: before any destructive operation; ideally daily
  1. Typesense index — 814 documents (503 repo + 311 website)
  • Backup method: Typesense snapshot API
  • Restore: snapshot import
  1. Railway persistent volume (/workspace):
  • /workspace/librechat/.secrets — credentials file (NOT in git) must be recreated from RoboForm safe note
  • /workspace/librechat/librechat.yaml — deployed config (can be re-seeded from repo)
  • /workspace/erik/uvilo-os/ — git working copy (can be re-cloned)

IMPORTANT: Add to Project_Complete skill: When .secrets changes, always prompt Erik to back it up to RoboForm

  1. Docker image — ghcr.io/erikdakoda/librechat-git:debian-slim
  • Can be rebuilt from Forge/Configs-debian/Dockerfile.librechat + git clone
  • Rebuild requires: local Docker, GHCR PAT with write:packages, --platform linux/amd64
  1. Railway environment variables — ~60 variables
  • Backup: export via dashboard LibreChat Service > Variables > Raw Editor > JSON
  • Restore: reimport the same way

IMPORTANT: Add to Project_Complete skill: When env vars change, always prompt Erik to back them up to RoboForm IMPORTANT: Add to Project_Check and Project_Complete skill: Update TypeSense index

  1. DNS records — librechat.uvilo.ai, os.uvilo.com
  2. Vercel project config — root directory .internal/, framework Astro, protection bypass secret

Part B: Step-by-Step Environment Rebuild

  1. Prerequisites — what you need before starting (GitHub PAT, Docker, Railway CLI, domain access)
  2. Railway project setup — create project, get IDs
  3. MongoDB service — provision, configure auth, set start command with --ipv6 --bind_ip
  4. LibreChat service — custom image, start command, volume, env vars (bulk-set!)
  5. Typesense service — provision, configure, re-index
  6. Playwright MCP service — image, serverless config, allowed hostnames
  7. DNS — configure librechat.uvilo.ai and os.uvilo.com
  8. Vercel project — connect repo, configure root directory, protection bypass
  9. Verification checklist — confirm everything works
  10. Post-rebuild — seed .secrets, test MCP servers, verify git operations

Part C: Operational Gotchas (from Learnings)

Scope: L5–L19, only items that don’t fit anywhere else (i.e., not already covered in Forge_Infrastructure.md or earlier sections of Forge_Setup.md).

Extract the non-trivial operational knowledge from L5–L19 as first-class reference sections (only items not already covered elsewhere):

  • Railway variable_bulk_set — always bulk, never individual (L5, L8)
  • In spite of that, during initial setup use env var backup in RoboForm to restore manually and quickly
  • Railway volume mount hides image contents at mount path (L6)
  • Dockerfile USER node breaks volume write access (L9)
  • node:20-slim missing ca-certificates (L11)
  • Docker build platform must match Railway linux/amd64 (L12)
  • Railway targetPort — use “default”, not explicit (L13)
  • Failed Railway services — delete and recreate, not redeploy (L14)
  • MongoDB --ipv6 --bind_ip for internal networking (L15)
  • MongoDB auth requires ?authSource=admin (L16)
  • Python 3.12+ vs 3.11 TarFile.extractall(filter=) (L17)
  • Seed MongoDB via PyMongo, not mongodump/mongorestore (L18)
  • UV_SYSTEM_PYTHON=1 prevents uv PATH shadowing (L19)
  • Railway env vars NOT in os.environ — use /proc/1/environ (L6-derived)

Part D: Post-Setup Verification Checklist

A complete and detailed verification checklist confirming the environment is fully operational after setup or rebuild.

Self-Contained & Integrity Checks

  1. Verify the document is self-contained — no dangling references to the project folder
  2. Double-check that the environment can be set up completely and cleanly using only the instructions in this document
  3. Link to Forge_Setup.md from AGENTS.md

Task 3 — Clear Learnings

After all knowledge is extracted to permanent homes, the project Learnings file should be emptied (per project flow convention — Learnings are temporary and cleared during evaluation/extraction).

  1. Verify every Learning (L1–L20) has a permanent home in either Forge_Infrastructure.md or Forge_Setup.md
  2. Wipe learnings points clear