Claude Code for Railway Deploy — Workflow Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are deploying applications with Railway, the cloud platform that auto-detects your framework, provisions databases, and deploys from GitHub with zero configuration needed. Claude Code can set up Railway deployments, but it generates Heroku Procfiles or Docker configs that are unnecessary for Railway’s auto-detection.

What Claude Code Gets Wrong By Default

  1. Creates Procfile for process management. Claude writes Heroku-style Procfile with web: node server.js. Railway auto-detects the start command from package.json scripts — no Procfile needed.

  2. Sets up Docker manually. Claude generates Dockerfiles for Railway. Railway uses Nixpacks for automatic builds from source — it detects Node.js, Python, Go, etc. and builds without a Dockerfile (though Dockerfiles are supported if present).

  3. Provisions databases externally. Claude configures external database connections. Railway provides one-click PostgreSQL, MySQL, Redis, and MongoDB — add them as services in the project and connection variables are auto-injected.

  4. Uses railway.toml for basic configs. Claude creates complex config files. Railway works with zero config for most projects. Only add railway.toml for custom build/start commands or health checks.

The CLAUDE.md Configuration


# Railway Deployment Project

## Platform
- Deploy: Railway (auto-detect, GitHub integration)
- Build: Nixpacks (auto) or Dockerfile (optional)
- Database: Railway-provisioned PostgreSQL/Redis
- Variables: configured in Railway dashboard or CLI

## Railway Rules
- Zero config for most frameworks (Next.js, Express, Django)
- Railway auto-detects start command from package.json
- Database services: add in Railway dashboard, vars auto-injected
- DATABASE_URL auto-set when PostgreSQL service is linked
- Custom config: railway.toml only if needed
- Deploy: push to GitHub (auto-deploy) or railway up (CLI)
- Regions: configure in project settings
- Private networking: services communicate via internal URLs

## Conventions
- Railway CLI: railway login, railway up, railway logs
- Environment vars in Railway dashboard, not .env files
- Database: Railway-provisioned, connection auto-configured
- Use ${{service.VARIABLE}} for cross-service references
- Health checks: /health endpoint recommended
- Build: let Nixpacks detect, override only if needed
- Custom domains: configure in Railway dashboard

Workflow Example

You want to deploy a Next.js app with PostgreSQL. Prompt Claude Code:

“Set up this Next.js project for Railway deployment. Add a PostgreSQL database service, configure the connection for Prisma, and set up a custom domain. No Docker needed.”

Claude Code should verify the project has a proper build and start script in package.json, configure Prisma to use DATABASE_URL (auto-provided by Railway), create a railway.toml only if custom build steps are needed, and document the Railway dashboard steps for adding PostgreSQL and configuring the domain.

Common Pitfalls

  1. Hardcoding localhost in database connections. Claude sets DATABASE_URL=postgresql://localhost:5432. Railway injects the connection string automatically when a database is linked — use process.env.DATABASE_URL without hardcoding.

  2. Missing PORT environment variable. Claude hardcodes app.listen(3000). Railway assigns a dynamic port via the PORT environment variable. Use process.env.PORT || 3000 for the listen port.

  3. Large repository slow builds. Claude does not configure .railwayignore. Railway uploads the entire repository for builds. Add a .railwayignore (same format as .gitignore) to exclude test files, documentation, and large assets.