Skip to main content

Deploy SkillFlaw on Railway

SkillFlaw can run on Railway, but it does not ship a first-party one-click Railway template.

The correct way to think about Railway is: it is a generic container platform, so your Railway deployment should mirror the same runtime contract already used by docker/docker-compose.yml instead of relying on an external template with its own assumptions.

What Railway needs to host​

At minimum, a SkillFlaw deployment on Railway needs these building blocks:

ServiceImage / dependencyNotes
Backendghcr.io/cwinux/skillflaw_backend:latestRequired
PostgreSQLRailway PostgreSQL or another managed PostgreSQLRequired
RedisRailway Redis or another managed RedisRequired when using SKILLFLAW_CACHE_TYPE=redis
Persistent storageRailway volume or equivalentRequired for SKILLFLAW_CONFIG_DIR
Secret file mountYour deployment process must provide a real file for SKILLFLAW_SECRET_KEY_FILERequired
Frontendghcr.io/cwinux/skillflaw_frontend:latestOptional if you need the web UI
Docsghcr.io/cwinux/skillflaw_docs:latestOptional

Decide the deployment shape first​

Choose deliberately:

  • API-first: backend + PostgreSQL + Redis
  • Full web deployment: add the frontend image
  • Docs exposure: add the docs image only if you need public documentation on Railway too

Do not add every service just because Railway can host them.

Backend runtime contract​

The backend service should keep the same settings and semantics used elsewhere in the documented runtime contract.

At minimum, configure Railway so the backend receives values for:

  • SKILLFLAW_DATABASE_URL
  • SKILLFLAW_CACHE_TYPE=redis
  • SKILLFLAW_REDIS_HOST
  • SKILLFLAW_REDIS_PORT
  • SKILLFLAW_CONFIG_DIR
  • SKILLFLAW_SECRET_KEY_FILE
  • SKILLFLAW_HOST=0.0.0.0
  • SKILLFLAW_PORT=7860

The backend health endpoint remains /health.

Important: SKILLFLAW_SECRET_KEY_FILE is still a file requirement​

SkillFlaw's deployment contract expects SKILLFLAW_SECRET_KEY_FILE to point to a real file.

If your Railway setup cannot provide a stable file-backed secret path, do not pretend the requirement disappeared. Solve that runtime requirement first, or choose a platform that matches the deployment contract more naturally.

Frontend runtime contract​

If you deploy the frontend image, set:

  • BACKEND_URL to the backend URL that the frontend should use in that Railway environment

Keep the frontend service focused on the UI. Backend API traffic should still terminate at the backend service, and docs can remain separate if you expose them.

Suggested rollout sequence​

  1. Create PostgreSQL and Redis services.
  2. Deploy the backend image and confirm GET /health succeeds.
  3. Attach persistent storage for SKILLFLAW_CONFIG_DIR.
  4. Provide the secret key file required by SKILLFLAW_SECRET_KEY_FILE.
  5. Only after the backend is healthy, add the frontend service if you need the browser UI.
  6. Add the docs service only if your Railway environment also hosts public documentation.

Verify the result​

Validate the exact public surfaces you intend to support:

  • backend health: /health
  • API traffic: /api/v1/run/{flow_id} or /api/v1/responses
  • MCP traffic: /api/v1/mcp/streamable
  • frontend UI if deployed
  • docs if deployed

What this page does not promise​

This page intentionally does not document a one-click button, a generated template repository, or a Railway-specific compatibility layer, because none of those are maintained as part of the documented deployment path today.

If you want the primary deployment reference, use: