You can deploy a Node.js or TypeScript API to Railway from GitHub, the Railway CLI, or a Docker image. For an API that also processes background jobs, use two persistent services: one for HTTP requests and one for the worker. This walkthrough is designed for a roughly 15-minute setup when the project is ready, but that is a pace target—not a guaranteed deployment time.
Choose a deployment route
Railway documents three ways to deploy a project. Choose based on where your code is and how you want to manage deployments:
As an Amazon Associate I earn from qualifying purchases.
| Route | How it works | Best fit |
|---|---|---|
| GitHub | Connect a repository and start a deployment; the service can deploy from the connected source. | A repository-based workflow where you want Railway connected to your code. |
| Railway CLI | From the project directory, run railway init, then railway up. |
Deploying local project code from your terminal. |
| Docker image | Deploy an existing Docker image. | A project that already produces and publishes an image. |
See Railway’s Quick Start Tutorial for the documented route details. The rest of this guide focuses on configuring the services and verifying the deployment.
Prepare the Node.js or TypeScript project
Before deploying, check that the repository can build for production and has a command that starts the built API. The command names and exact syntax depend on your framework, package manager, and repository layout; use your project’s production scripts rather than assuming that running a TypeScript file directly is appropriate.
#1 Best Overall
- Confirm the production build script completes successfully.
- Confirm the start script launches the built server and listens on the port provided by the deployment environment.
- For a monorepo, identify the API package and its working directory so the service builds and starts the intended application.
Railway’s Railpack can detect build and start commands, and you can override the detected commands when necessary. After the initial build, inspect what Railway selected and compare it with the scripts and directory structure in your repository. See Railway’s build and start commands guide.
Create and configure the API service
- Create the service: connect the GitHub repository, or deploy from the project directory using
railway initfollowed byrailway up. You can also deploy an existing Docker image. - Check the build and start commands: review Railpack’s detected commands after the first build. Override them if your production scripts or monorepo layout need explicit commands.
- Set the service’s runtime variables: add the configuration and secrets the API needs, as described below.
- Set an HTTP health-check path: choose a route in your API that returns a successful response when the service is ready.
- Deploy and inspect the result: check the deployment state and logs. Railway marks a deployment Active after its configured health check succeeds.
For a Dockerfile or image deployment, note that Railway runs a configured start command in exec form. If the command needs shell expansion of environment variables, wrap it in a shell as described in the command documentation.
Rank #2
Run the worker as a separate service
Use a second persistent service for background work instead of making the API service run both processes. Railway describes persistent services as suitable for APIs and background workers, and its infrastructure-as-code reference illustrates separate API and worker services with different commands.
| Service | Responsibility | Production command |
|---|---|---|
| API | Accept incoming HTTP requests and return responses. | The API’s production start command. |
| Worker | Process asynchronous or background jobs. | The worker’s production start command. |
- Create another service from the appropriate source repository or project.
- Set its root directory and build command to match the worker package, especially in a monorepo.
- Set its start command to the worker’s production command—not the API command.
- Give it only the runtime variables it needs, then deploy it.
This deployment pattern separates process responsibilities; it does not provide the job transport or define how jobs are retried. Your application still needs its own queue or other job-delivery mechanism and failure-handling behavior. Railway’s service model and configuration examples are documented under Services and the Infrastructure as Code reference.
Rank #3
Set variables without putting secrets in source code
Store secrets and runtime configuration in Railway service variables, not in committed application code. Add the database, queue, and application settings each process requires. The exact names depend on your application.
Configure variables separately for the API and worker according to their needs. If both services use the same value, Railway’s reference-variable and configuration-as-code features can help share configuration without copying a value into source code. See Railway’s overview of variables and its infrastructure-as-code reference.
Rank #4
Verify the API and worker independently
API: confirm readiness
- Check that the configured health-check route returns a successful response.
- Inspect the deployment state; a configured health check must succeed before Railway reports the deployment as Active.
- Review service logs if the check fails, focusing on startup errors, missing variables, and whether the application is listening as expected.
Railway’s deployment reference explains the deployment lifecycle and Active state.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Worker: confirm job processing
- Inspect the worker’s logs to confirm it starts with the worker command and can connect to the resources it needs.
- Submit a real test job through your application’s normal job-delivery path.
- Confirm the worker receives and processes that job, using application logs or the application’s own status reporting.
The Railway documentation describes persistent workers but does not establish a universal worker-specific health check or queue test. Use checks that match your application’s job system.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
