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

Container Base Image Plan 2

Scope: Deploy the Debian-slim build to Railway as a completely separate, parallel project with its own services, volumes, and environment. Validate all MCP servers and functionality end-to-end on the new infrastructure. Prior plan: Container Base Image Plan 1

Task 1 — Create a new Railway project for the Debian-slim build

Requirement R6: both builds must run simultaneously during migration. The new build gets its own Railway project — completely separated from the existing uvilo-libre-chat project. This ensures clean isolation: no shared services, no cross-contamination, no risk to the existing deployment.

The existing Railway project is uvilo-libre-chat (ID: c1dc2ebe-2cd0-4bd2-a327-c0d1be1a8616). Do NOT modify this project in any way.

  1. Create a new Railway project (e.g., uvilo-libre-chat-v2 or similar)
  2. Create a new LibreChat service in the new project:
    • Use the custom image: ghcr.io/erikdakoda/librechat-git:debian-slim (the image built in Plan 1)
    • Set the custom start command: /bin/bash /workspace/startup.sh
  3. Provision a NEW persistent volume (5GB) for the new LibreChat service, mounted at /workspace
    • Do NOT reuse or share the existing Alpine deployment’s volume
  4. Set all environment variables for the new service (duplicate from the existing Alpine service):
    • LLM API keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_KEY, OPENROUTER_KEY
    • Service tokens: SUPRSEND_SERVICE_TOKEN, RAILWAY_API_TOKEN, etc.
    • Infrastructure: MONGO_URI, MEILI_HOST, MEILI_MASTER_KEY
    • Git credentials: GITHUB_TOKEN, GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL
    • Auth: CREDS_KEY, CREDS_IV, JWT_SECRET, JWT_REFRESH_SECRET
    • Email: EMAIL_HOST, EMAIL_USERNAME, EMAIL_PASSWORD
    • Analytics: POSTHOG_API_KEY, etc.
  5. Create a new MongoDB service in the new project with its own volume
    • Seed it with a dump from the existing MongoDB instance (use mongodump/mongorestore)
    • Point the new LibreChat service’s MONGO_URI to this new MongoDB instance
  6. Create a new Meilisearch service in the new project with its own volume
    • Point the new LibreChat service’s MEILI_HOST and MEILI_MASTER_KEY to this new instance
  7. If applicable, create new services for Rag API and VectoDB in the new project, each with their own volumes
  8. Assign a separate public URL (e.g., librechat-new.uvilo.ai or Railway-generated URL) for testing
  9. Deploy the new service and verify it starts without errors

Why a separate project?

  • Clean separation: no shared state, no risk of one deployment affecting the other
  • Independent lifecycle: can redeploy, restart, or tear down either project without affecting the other
  • Dedicated volumes: no risk of volume conflicts or data corruption
  • True parallel operation: both environments function concurrently and independently

Task 2 — Install Typesense on the new build

Requirement R6: the Typesense index must be transferred or rebuilt on the new build. Without Typesense, the uvilo-typesense MCP server cannot function, and all knowledge search capabilities are offline.

  1. Provision a new Typesense service in the Railway project (or install Typesense as a sidecar/container)
  2. Configure the Typesense API key and host in the new LibreChat service’s environment variables
  3. Transfer the existing Typesense index data (snapshot/export from the current Alpine deployment) or rebuild the index from scratch
  4. Verify the uvilo-typesense MCP server can connect and return search results
  5. Record the service details (host, port, API key) in the State document

Task 3 — Validate all MCP servers on the new build

Requirement R1: all MCP servers must work without musl-specific workarounds. This is the core validation. Test each MCP server configured in librechat.yaml on the new Debian-slim build.

  1. Access the new build via its test URL

  2. For each MCP server in Forge/Configs/LibreChat_Service/librechat.yaml, verify it starts and responds to a basic tool call:

    MCP ServerCommandValidation
    uvilo-filesystemnpx -y @modelcontextprotocol/server-filesystem /workspace/erik/uvilo-osList a file
    uvilo-gituvx mcp-server-git --repository /workspace/erik/uvilo-osRun git status
    uvilo-git-remoteuvx --with mcp python3 /workspace/uvilo-git-push.pyList branches
    vercelnpx vercel-mcpList deployments
    uvilo-shelluvx --with mcp python3 .../uvilo-shell.pyRun echo hello
    uvilo-typesenseuvx --with mcp python3 .../typesense-mcp.pySearch knowledge
    uvilo-trash(uvilo-trash.py)List trash
    suprsend-dev/staging/prodpython3 .../suprsend-mcp-proxy.pyList templates
    Playwrightmcr.microsoft.com/playwright/mcpNavigate to a URL
    context7npx -y @upstash/context7-mcp@latestResolve a library
    notionnpx -y @notionhq/notion-mcp-serverSearch pages
    linearnpx -y @touchlab/linear-mcp-integrationList issues
    railwaynpx -y @jasontanswe/railway-mcpList services
    posthognpx -y mcp-remote@latest ...List insights
    neonnpx -y mcp-remote@latest ...List databases

  3. If any server fails, debug and fix (likely causes: missing system deps, path differences between Alpine and Debian)

  4. Record results in the State document

Task 4 — Validate Forge scripts and full functionality

Requirement R5: no regression in existing LibreChat functionality or Forge scripts.

  1. Verify Forge startup script completes successfully on the new build (check container logs)
  2. Verify git operations work: clone, pull, push (test with the uvilo-git-remote MCP)
  3. Verify Python scripts run: uvx --with mcp python3 works for all custom MCP servers
  4. Verify the Typesense search index is accessible and returns results
  5. Verify chat functionality: send a message, receive a response, test artifact generation
  6. Verify file operations via uvilo-filesystem: read, write, search files
  7. Verify Playwright MCP: navigate to a URL and take a snapshot
  8. Compare behavior with the existing Alpine build — there should be no functional differences

Task 5 — Ask Erik to validate the new configuration

Before proceeding to DNS cutover, Erik must validate that the new Debian-slim deployment works correctly end-to-end. This is a hard gate — Plan 3 (DNS cutover) must not begin until Erik explicitly approves.

  1. Present Erik with a summary of the validation results from Tasks 3 and 4
  2. Provide the test URL for the new build so Erik can test it himself
  3. List any known issues or differences from the Alpine build
  4. Wait for Erik’s explicit approval before proceeding to Plan 3
  5. If Erik finds issues, create a fix task list and resolve them before re-requesting approval