New System

A Railway skill for creating new projects, services, and databases from scratch. New System handles project initialization, service creation from source code or Docker images, and database provisioning — all through the Railway CLI with proper configuration.

When to Use This Skill

Choose New System when:

• Starting a new Railway project from scratch
• Adding a new service to an existing Railway project
• Provisioning a database plugin (PostgreSQL, Redis, MySQL, MongoDB)
• Setting up a project with multiple services and databases

Consider alternatives when:

• You need to manage existing deployments (use a deployment management skill)
• You want to deploy from a template (use Railway Templates)
• You're configuring CI/CD integration (use GitHub Actions)

Quick Start

Copy
claude "Create a new Railway project with a Node.js service and PostgreSQL"

Copy
# Initialize a new Railway project
railway init

# Or create a new project with a name
railway init --name my-app

# Link current directory to the project
railway link

# Add a PostgreSQL database
railway add --plugin postgresql

# Deploy the service
railway up

Core Concepts

Project Architecture

Component	CLI Command	Purpose
Project	railway init	Top-level container for services
Service	railway up	Deployed application instance
Plugin	railway add --plugin <type>	Managed database or add-on
Environment	railway environment create	Isolated variable/deploy scope

Service Creation Options

Copy
# From current directory (auto-detect language)
railway up

# From a GitHub repository
railway init --repo https://github.com/user/repo

# From a Docker image
railway up --image node:18-alpine

# With a specific build configuration
# railway.json in project root:
{
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm ci && npm run build"
  },
  "deploy": {
    "startCommand": "npm start",
    "healthcheckPath": "/health"
  }
}

Multi-Service Setup

Copy
# Create project
railway init --name my-fullstack-app

# Add backend service
cd backend && railway link && railway up

# Add frontend service
cd ../frontend && railway link && railway up

# Add database
railway add --plugin postgresql

# Add Redis cache
railway add --plugin redis

# Wire services together using variable references
railway variables --set DATABASE_URL='${{Postgres.DATABASE_URL}}'
railway variables --set REDIS_URL='${{Redis.REDIS_URL}}'

Configuration

Parameter	Description	Default
project_name	Name for the Railway project	Directory name
builder	Build system: NIXPACKS or DOCKERFILE	NIXPACKS
region	Deployment region	us-west1
auto_deploy	Deploy on Git push	true
root_directory	Subdirectory for monorepo builds	/

Best Practices

1. Initialize with railway init before deploying. Creating a project first gives you control over naming and configuration. Running railway up in an unlinked directory may create a project with a random name.

2. Use variable references between services. When your API needs to connect to PostgreSQL, use ${{Postgres.DATABASE_URL}} instead of copying connection strings. References auto-update when the database is re-provisioned.

3. Set up a railway.json for reproducible builds. Define build and deploy commands in railway.json so deployments are consistent regardless of who triggers them. This file should be committed to version control.

4. Create environments early. Set up staging and production environments at project creation time. It's easier to configure variables per-environment from the start than to separate them later.

5. Add health checks to every service. Include a healthcheckPath in your deployment config. Without health checks, Railway can't distinguish between a service that's starting up and one that's crashed — leading to traffic being routed to unhealthy instances.

Common Issues

railway init fails with authentication error. Run railway login first. If you're in a CI environment, set the RAILWAY_TOKEN environment variable with a project token from the Railway dashboard. Ensure the token has the necessary permissions.

Service deploys but isn't accessible. A newly deployed service doesn't have a domain by default. Run railway domain to generate a Railway subdomain, or use railway domain --set custom.example.com for a custom domain. The service must listen on process.env.PORT.

Database plugin not connecting to service. Ensure the service and database are in the same project. Check that you're using reference variables (${{Postgres.DATABASE_URL}}) and that the service was redeployed after adding the variable. Variables set after deployment require a redeploy to take effect.