tomevault-io Railway Deployment & Management
Verification
BEFORE using this skill, verify the project uses Railway:
- User explicitly mentions "Railway", OR
- Check for Railway artifacts:
railway.json,railway.toml,.railway/directory - When in doubt, ASK: "Is this project deployed to Railway?"
DO NOT use for: Vercel, AWS, Heroku, Fly.io, or unknown platforms.
Quick Reference (CLI 2026-02)
| Task | Command |
|---|---|
| Deploy | railway up --detach |
| Deploy subdirectory | railway up --path-as-root ./web |
| Check status | railway status |
| View logs | railway logs |
| Build logs | railway logs --build |
| Last N lines | railway logs -n 100 |
| Set variable | railway variable set KEY=VALUE |
| Set multiple | railway variable set K1=V1 K2=V2 |
| List variables | railway variable list |
| List as KV | railway variable list --kv |
| Delete variable | railway variable delete KEY |
| Skip redeploy on set | railway variable set K=V --skip-deploys |
| Connect to DB | railway connect postgres |
| Run with env | railway run npm start |
| Open dashboard | railway open |
| Redeploy | railway redeploy --yes |
| Switch env | railway environment staging |
| SSH into container | railway ssh |
| Service link | railway service backend |
| Deployment list | railway deployment list --limit 5 |
| Domain | railway domain |
Global Options
These flags work across most commands:
| Option | Short | Purpose |
|---|---|---|
--service <SERVICE> |
-s |
Target specific service |
--environment <ENV> |
-e |
Target specific environment |
--project <ID> |
-p |
Target specific project |
--json |
— | Scriptable JSON output |
--yes |
-y |
Skip confirmation prompts |
Essential Patterns
Deploy Workflow:
railway status && railway up --detach
railway logs -n 20 # check after deploy
Monorepo Deploy (CRITICAL: use --path-as-root):
railway up --path-as-root ./web --service web
railway up --path-as-root ./backend --service backend
Debug Failed Deployment:
railway logs --build # Build errors
railway variable list # Verify env vars
railway run npm run build # Test locally with Railway env
Database Migration (ALWAYS backup first):
railway run pg_dump -Fc > backup.dump # 1. BACKUP
railway connect postgres # 2. Verify state
railway run npm run migrate # 3. Migrate
railway connect postgres # 4. Verify
Set Variables:
railway variable set API_KEY=secret123 NODE_ENV=production
railway variable set KEY=VALUE --skip-deploys # no redeploy
echo "multiline" | railway variable set KEY --stdin
Key Gotchas
--path-as-rootis required for monorepo subdirectory deploys — without it, subdirectory nests in archive--projectrequires--environment— both must be specified together- Variable changes trigger redeploy by default — use
--skip-deploysto prevent railway logsstreams live by default;-n Nfetches history and exits (NOT--limit)railway variable(singular) is the command —variables,vars,varare aliases- TLS between Railway services may fail with
UNABLE_TO_GET_ISSUER_CERT_LOCALLY— useNODE_TLS_REJECT_UNAUTHORIZED=0or private networking - CI/CD tokens:
RAILWAY_TOKEN(project-scoped) orRAILWAY_API_TOKEN(account-level)
Common Errors
| Error | Fix |
|---|---|
undefined variable 'npm' in Nixpacks |
Don't add npm to nixPkgs — comes with nodejs |
Tracker 'idealTree' already exists |
npm cache clean --force && npm install |
gyp ERR! build error |
Add nixPkgs = ["nodejs", "python3", "gcc", "gnumake"] |
Cannot find module (workspace) |
Use repo root, not subdirectory, as Root Directory |
EACCES: permission denied |
Use /tmp for temp files or add a volume |
| Service crashes on start | Check railway logs, verify env vars, check healthcheck |
Additional Resources
Detailed docs in supporting files:
- reference.md — Complete CLI command reference with all flags
- examples.md — Real-world workflows, scripts, CI/CD pipelines
- troubleshooting.md — Error messages, diagnosis, solutions
- migrations.md — Database migration strategies
Official: docs.railway.com · CLI Reference
Converted and distributed by TomeVault — claim your Tome and manage your conversions.