Deployment on Railway
Relevant source files
The following files were used as context for generating this wiki page:This project, the official documentation for Railway, is hosted and deployed on the Railway platform itself. This provides a practical example of deploying a Next.js application on Railway. Deployments are handled automatically when pull requests are merged into the main branch.
The deployment process is primarily configured through the railway.json file, which defines the build and deploy settings. This includes specifying the build commands, start command, health check path, and multi-region deployment strategy. The project utilizes Railway's built-in RAILPACK builder, which simplifies the configuration for Node.js projects.
Sources: README.md:9-10, railway.json
Deployment Configuration (railway.json)
The core of the deployment process is defined in the railway.json file. This file uses a specific schema to instruct the Railway platform on how to build and deploy the application.
Sources: railway.json:1-2
Build Configuration
The build object specifies how to prepare the application for deployment. This project uses RAILPACK as its builder, which is Railway's system of pre-built build and start logic for various languages and frameworks.
| Key | Value | Description |
|---|---|---|
builder | RAILPACK | Specifies the use of Railway's automatic build system. |
buildCommand | pnpm build && pnpm postbuild | The command executed to build the project. It first runs the build script, then the postbuild script. |
Sources: railway.json:3-6
The following diagram illustrates the sequence of commands executed during the build process as defined in package.json.
This diagram shows the build flow starting from the main build command.
Sources: package.json:6-7, railway.json:5
Deploy Configuration
The deploy object contains settings for the runtime environment of the application.
| Key | Value | Description |
|---|---|---|
healthcheckPath | / | The endpoint Railway pings to determine if the application is healthy. |
startCommand | pnpm run start | The command used to start the application server after a successful build. |
multiRegionConfig | (object) | Defines the default multi-region deployment strategy. |
Sources: railway.json:7-14
The start script in package.json executes next start --port ${PORT-3001}, which starts the Next.js server on the port provided by Railway's $PORT environment variable, defaulting to 3001 locally.
Sources: package.json:8
Environment-Specific Deployments
The railway.json file also defines environment-specific configurations. The production environment has a more extensive multi-region deployment strategy to ensure high availability and low latency for users across the globe.
The following regions are configured for the production environment:
us-west2us-east4-eqdc4aeurope-west4-drams3aasia-southeast1-eqsg3a
Each region is configured to run one replica of the application.
Sources: railway.json:15-29
The diagram below shows the multi-region deployment architecture for the production environment.
This diagram illustrates how user traffic is distributed across multiple geographic regions.
Sources: railway.json:18-28
Automated Deployment Flow
Deployments are triggered automatically upon merging a pull request to the main branch. This CI/CD process is a key feature of hosting on Railway.
Sources: README.md:9-10
The sequence diagram below outlines the automated deployment process.
This diagram shows the steps from code merge to a live deployment on Railway.
Sources: README.md:9-10, railway.json:5,8-9
Deployment-Related Documentation
The documentation site itself contains numerous guides and reference materials related to deploying applications on Railway. The structure in src/data/sidebar.ts reveals the breadth of topics covered.
Key deployment topics include:
- Builds:
Build Configuration,Dockerfiles,Private Registries - Deployments:
Start Command,GitHub Autodeploys,Healthchecks,Restart Policy,Monorepo,Cron Jobs - Networking:
Public Networking,Private Networking - Databases:
PostgreSQL,MySQL,Redis,MongoDB
Sources: src/data/sidebar.ts:60-101
The project also handles URL redirections for legacy deployment-related paths to their new locations, ensuring that old links continue to work. For example, /deploy/exposing-your-app is permanently redirected to /guides/public-networking.
Sources: redirects.js:13-16
Common Deployment Considerations
The project's FAQ file highlights common issues faced during deployment on Railway. A notable example is the Bad Gateway error, which typically occurs when the PORT environment variable is not correctly configured in the application. Railway uses this variable to expose the correct port to the internet.
Sources: public/static/faq.json:5-12