Deploy API to Railway

[JohnRDOrazio]

Goal

Ship the OntoKit API on Railway so we have a low-cost hosted deployment.

Blocker hit

Railway's free/hobby tier caps build images at 4 GB. The existing Dockerfile.prod produced an image > 5 GB, so the build step failed.

Root cause

• sentence-transformers is a core dependency, pulling in PyTorch + transformers + scipy (~2–3 GB).
• Dockerfile.prod was single-stage, so pip cache, build tools, and libgit2-dev headers all ended up in the final image.
• The Dockerfile also pre-downloaded the all-MiniLM-L6-v2 model (~90 MB + cache) at build time.

Work

• Shrink the image to fit Railway's 4 GB cap — see chore(docker): shrink prod image from >5GB to ~606MB for Railway #101
• Provision the dependent services on Railway (see comment below)
• Wire env vars (DATABASE_URL, REDIS_URL, MINIO_*, ZITADEL_*, SECRET_KEY, …) into the Railway API service
• Verify DB migrations run cleanly on first boot via scripts/entrypoint.sh
• Verify pgvector extension is available on the chosen Postgres
• End-to-end smoke test: auth → project CRUD → embedding query

[JohnRDOrazio]

Dependent services: what Railway will and won't host for us

railway.json only builds/deploys the API service via Dockerfile.prod. Railway does not read compose.prod.yaml, so Postgres, Redis, MinIO, and Zitadel need to be provisioned separately.

Per-service options

Service	Railway option	Notes
PostgreSQL	Managed Postgres plugin (one-click)	⚠️ We need pgvector (ontokit/models/embedding.py). Railway's managed Postgres ships with pgvector enabled on newer images — verify before relying on it. Fallback: run a custom pgvector/pgvector:pg17 image as a separate Railway service.
Redis	Managed Redis plugin (one-click)	Works out of the box.
MinIO	No managed option	Either deploy minio/minio as a separate Railway service (persistent volume + 2 ports), or point MINIO_ENDPOINT at external S3-compatible storage (Cloudflare R2, Backblaze B2, AWS S3).
Zitadel	No managed option	Three realistic choices: (1) run ghcr.io/zitadel/zitadel as its own Railway service — fiddly (needs the login sidecar, shared volume for PATs, a public domain because Zitadel enforces ZITADEL_EXTERNALDOMAIN). (2) Use Zitadel Cloud (free tier). (3) Host Zitadel elsewhere and point the API at it via ZITADEL_ISSUER.

Free-tier caveat

Railway's free/hobby tier has a total resource budget across all services in the project. Running API + Postgres + Redis + MinIO + Zitadel + Zitadel-Login in one project will very likely exceed it. Image size was the first wall; RAM/egress will be the next.

Recommended shape for staying on the free tier

• API on Railway (the Dockerfile optimized in chore(docker): shrink prod image from >5GB to ~606MB for Railway #101)
• Postgres + Redis as Railway managed plugins
• Zitadel Cloud (SaaS, free tier) instead of self-hosting
• Cloudflare R2 (free egress, S3-compatible) instead of MinIO