Railway
Deploy bigRAG to Railway with managed Postgres, Redis, local ingestion staging, and Turbopuffer search.
Deploy the API, Dramatiq worker, admin UI, Postgres, and Redis in one Railway project. Turbopuffer provides managed vector, keyword, and hybrid search.
Template files
The repository includes Railway template assets under railway/:
| File | Purpose |
|---|---|
railway/api.json | API build, healthcheck, restart, and shutdown settings |
railway/worker.json | Worker build, start command, restart, and shutdown settings |
railway/app.json | Admin UI build, healthcheck, restart, and shutdown settings |
railway/variables/api.env | API variables for the Railway raw editor |
railway/variables/worker.env | Worker variables for the Railway raw editor |
railway/variables/app.env | Admin UI variables for the Railway raw editor |
Railway templates are finalized in the Railway template composer. Use these files as the source of truth when creating or updating the published bigRAG template.
What you get
| Service | Notes |
|---|---|
| API | FastAPI backend, public HTTP domain |
| Worker | Dramatiq background jobs for ingestion, connectors, webhooks, and cleanup |
| App | Admin UI, public HTTP domain |
| Postgres 17 | Railway managed database, referenced as Postgres |
| Redis 7 | Railway managed cache and queue, referenced as Redis |
| Turbopuffer | Managed vector, keyword, and hybrid search |
Prerequisites
- Railway Pro plan for comfortable API and worker memory limits.
- A Turbopuffer API key.
- An OpenAI, Cohere, Voyage, or OpenAI-compatible embedding provider key.
- A region close to your users, Turbopuffer region, and embedding provider.
Template composer
Use these exact service names unless you also update the reference variables in railway/variables/*.env.
| Service | Railway source | Root directory | Config file | Public networking |
|---|---|---|---|---|
Postgres | Database → PostgreSQL | — | — | no |
Redis | Database → Redis | — | — | no |
API | GitHub repo | /api | /railway/api.json | HTTP |
Worker | GitHub repo | /api | /railway/worker.json | no |
App | GitHub repo | / | /railway/app.json | HTTP |
The API, Worker, and App services all build from Dockerfiles. The API and worker use the same backend image, but separate Railway config files because their runtime commands are different.
Variables
Paste railway/variables/api.env into the API raw editor, railway/variables/worker.env into the Worker raw editor, and railway/variables/app.env into the App raw editor.
Fill these required values before the first deploy:
| Variable | Services | Value |
|---|---|---|
BIGRAG_MASTER_KEY | API, Worker | Fernet key from the command below |
BIGRAG_TURBOPUFFER_API_KEY | API, Worker | Turbopuffer API key |
BIGRAG_EMBEDDING_API_KEY | API, Worker | Embedding provider key |
Generate the master key locally:
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"Back the master key up immediately. It encrypts provider secrets, webhook secrets, embedding-cache rows, and Redis cache payloads; losing it loses decrypt access.
Storage
Ingestion staging is local-only:
BIGRAG_UPLOAD_DIR=/data/uploadsWhen the API and worker run as separate Railway services, they must mount the same upload directory. If your Railway project cannot provide a shared local volume for both services, run API and worker in the same service or deploy the split API/worker topology on a platform with shared filesystem mounts. Staged originals are deleted after terminal processing, cancellation, or document deletion.
First run
- Deploy all five services.
- Open the
Apppublic URL. - Complete
/setupto create the first admin account. - Complete onboarding and create a verified embedding preset.
- Create a collection and upload a small document.
- Check
https://API_DOMAIN/health/ready; it should reportvector_store: true.
Updating the template
After changing any Railway config, deploy a normal Railway project from the GitHub repo first. When the project is healthy, open the Railway project settings and generate or update the template from that project.