adaptationio/railway-project-management

Railway Project Management

Comprehensive management of Railway.com projects, environments, services, and variables using the Railway CLI.

Overview

This skill provides complete workflows for:

• Creating and linking Railway projects
• Managing environments (production, staging, PR environments)
• Adding services from GitHub, Docker, or local sources
• Configuring variables (service, shared, reference, sealed)
• Syncing and duplicating environments
• Project settings and validation

Prerequisites

• Railway CLI installed and authenticated (use railway-auth skill)
• Git repository (for GitHub integrations)
• Docker (optional, for container deployments)

Workflow

1. Project Creation and Linking

Create new Railway project:

# Initialize new project interactively
railway init

# Create project with specific name
railway init --name "my-project"

# Link to existing project (interactive)
railway link

# Link to specific project by ID
railway link -p <project-id>

# Link to project with specific environment and service
railway link -p <project-id> -e <environment-id> -s <service-id>

# Check current project status
railway status

Project information:

# View project details
railway status

# View project in browser
railway open

# Unlink from current project
railway unlink

2. Environment Management

Create and switch environments:

# List all environments
railway environment

# Create new empty environment
railway environment --name staging

# Create duplicate of current environment
railway environment --name production-backup --duplicate

# Switch to specific environment
railway environment production

# Delete environment (interactive)
railway environment delete

Environment types:

• Production: Main deployment environment
• Staging: Pre-production testing
• PR Environments: Auto-created per pull request
• Custom: Any named environment for specific needs

See references/environment-types.md for detailed guide.

3. Service Operations

Add services from different sources:

# Add service from GitHub repository
railway add --repo owner/repo

# Add service from current directory
railway add

# Add Docker image
railway add --image postgres:15

# Add template (e.g., database)
railway add --template postgres

Service sources:

• GitHub: Auto-deploy from repository
• Docker: Deploy container images
• Local: Deploy from current directory
• Templates: Pre-configured services (databases, etc.)

See references/service-sources.md for detailed configurations.

4. Variable Management

Set variables at different scopes:

# Set service variable (current service only)
railway variables set API_KEY=secret123

# Set shared variable (all services in environment)
railway variables set --shared DATABASE_URL=postgres://...

# Set sealed variable (enhanced security)
railway variables set --sealed STRIPE_KEY=sk_live_...

# Reference variable from another service
railway variables set API_URL='${{ api-service.PUBLIC_URL }}'

# Delete variable
railway variables delete API_KEY

# List all variables
railway variables list

Variable types:

1. Service Variables: Isolated to specific service
2. Shared Variables: Available to all services in environment
3. Reference Variables: Reference other service variables using ${{ service.VAR }} syntax
4. Sealed Variables: Enhanced security, cannot be unsealed or viewed after creation

Variable scoping:

Project
├── Environment (production)
│   ├── Service A
│   │   ├── Service variables (API_KEY)
│   │   └── Can access shared variables
│   ├── Service B
│   │   ├── Service variables (DB_PASSWORD)
│   │   └── Can access shared variables
│   └── Shared variables (LOG_LEVEL, NODE_ENV)

See references/variable-scoping.md for advanced patterns.

5. Configuration and Settings

Project settings:

# View project settings in browser
railway open --settings

# Enable/configure PR environments
# (Done via dashboard - automated per PR)

# Configure deployment triggers
# (Done via dashboard - branch filters, paths)

Service settings:

# View service in browser
railway open

# Configure via railway.json or railway.toml
cat > railway.json <<EOF
{
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm run build"
  },
  "deploy": {
    "startCommand": "npm start",
    "healthcheckPath": "/health",
    "restartPolicyType": "ON_FAILURE"
  }
}
EOF

Advanced configuration:

• Health checks and restart policies
• Resource limits (CPU, memory)
• Custom build commands
• Root directory overrides
• Networking and domains

6. Verification and Validation

Verify project setup:

# Check project status
railway status

# List all environments
railway environment

# List services
railway list

# Check variables
railway variables list

# View logs
railway logs

# Open in browser for visual verification
railway open

Common validation checks:

• ✅ Project linked correctly
• ✅ Environments created (production, staging)
• ✅ Services deployed successfully
• ✅ Variables set at correct scope
• ✅ PR environments enabled (if needed)
• ✅ All services healthy

Common Workflows

Initialize New Full-Stack Project

Use the automation script:

.claude/skills/railway-project-management/scripts/init-project.sh

Or manually:

# 1. Initialize project
railway init --name my-app

# 2. Create environments
railway environment --name staging
railway environment --name production

# 3. Add services (in production)
railway environment production
railway add --repo owner/frontend-repo
railway add --repo owner/api-repo
railway add --template postgres

# 4. Set shared variables
railway variables set --shared NODE_ENV=production
railway variables set --shared LOG_LEVEL=info

# 5. Replicate to staging
railway environment staging
# (Set staging-specific variables)

# 6. Enable PR environments (via dashboard)
railway open --settings

Sync Variables Between Environments

Use the automation script:

.claude/skills/railway-project-management/scripts/sync-env.sh production staging

Add Database to Existing Project

# 1. Switch to desired environment
railway environment production

# 2. Add database template
railway add --template postgres

# 3. Set shared DATABASE_URL
# (Usually auto-set by Railway)

# 4. Reference in other services
railway variables set DATABASE_URL='${{ postgres.DATABASE_URL }}'

Configure PR Environments

# 1. Enable in project settings
railway open --settings

# 2. Configure PR environment settings:
# - Base environment to duplicate
# - Services to include
# - Variable handling

# 3. PR environments auto-create on new PRs
# - Each PR gets isolated environment
# - Auto-deploys on PR updates
# - Auto-deletes on PR close/merge

Reference Variables Pattern

# Service A exposes PUBLIC_URL
railway variables set --service api-service PUBLIC_URL=https://api.railway.app

# Service B references it
railway variables set --service frontend API_URL='${{ api-service.PUBLIC_URL }}'

# Service C uses multiple references
railway variables set --service worker \
  API_URL='${{ api-service.PUBLIC_URL }}' \
  DB_URL='${{ postgres.DATABASE_URL }}'

Benefits:

• DRY (Don't Repeat Yourself)
• Auto-updates when source changes
• Type-safe service connections
• Clear dependency graph

Security Best Practices

Sealed Variables

# Use sealed for production secrets
railway environment production
railway variables set --sealed STRIPE_SECRET_KEY=sk_live_...
railway variables set --sealed AWS_SECRET_ACCESS_KEY=...

# Regular variables for non-sensitive config
railway variables set --shared NODE_ENV=production

When to use sealed variables:

• API keys and secrets
• Database passwords
• OAuth client secrets
• Encryption keys
• Any sensitive credential

Sealed variable characteristics:

• Cannot be viewed after creation (not even in UI)
• Cannot be unsealed
• Can only be overwritten or deleted
• Enhanced security for compliance

Variable Organization

# Shared variables: Cross-service configuration
railway variables set --shared NODE_ENV=production
railway variables set --shared LOG_LEVEL=info
railway variables set --shared REGION=us-west-2

# Service variables: Service-specific config
railway variables set --service api PORT=3000
railway variables set --service api API_VERSION=v1

# Sealed variables: Secrets
railway variables set --sealed DATABASE_PASSWORD=...
railway variables set --sealed JWT_SECRET=...

Environment Strategies

Strategy 1: Production + Staging

production (main branch)
├── All services
├── Production data
└── Sealed secrets

staging (develop branch)
├── All services
├── Test data
└── Staging secrets

Strategy 2: Production + PR Environments

production (main branch)
├── All services
└── Production data

PR-123 (auto-created)
├── All services (from production template)
├── Isolated test data
└── Auto-deploys on PR updates

Strategy 3: Multi-Environment Pipeline

development → staging → production
     ↓            ↓          ↓
  Dev data   Test data  Prod data
  Dev URLs   Stage URLs Prod URLs

Troubleshooting

Project Not Linked

# Symptom: "No project linked"
# Solution:
railway link
# Or specify project ID:
railway link -p abc123

Wrong Environment

# Check current environment
railway status

# Switch to correct environment
railway environment production

Variable Not Found

# List all variables to verify
railway variables list

# Check variable scope (service vs shared)
railway variables list --service api
railway variables list --shared

# Set if missing
railway variables set VAR_NAME=value

Service Not Deploying

# Check deployment logs
railway logs --deployment

# Check service status
railway status

# Redeploy
railway up

Related Skills

• railway-auth: Authenticate with Railway CLI
• railway-deployment: Deploy services and manage deployments
• railway-troubleshooting: Debug Railway issues
• railway-cli: Core Railway CLI operations
• railway-observability: Monitor Railway services

Quick Reference

Project Operations

| Command | Description | |---------|-------------| | railway init | Initialize new project | | railway link | Link to existing project | | railway unlink | Unlink current project | | railway status | Show project status | | railway open | Open project in browser |

Environment Operations

| Command | Description | |---------|-------------| | railway environment | List/switch environments | | railway environment --name <name> | Create new environment | | railway environment --duplicate | Duplicate current environment | | railway environment delete | Delete environment |

Service Operations

| Command | Description | |---------|-------------| | railway add | Add service from current directory | | railway add --repo <owner/repo> | Add from GitHub | | railway add --image <image> | Add Docker image | | railway add --template <name> | Add template service | | railway list | List all services |

Variable Operations

| Command | Description | |---------|-------------| | railway variables set KEY=value | Set service variable | | railway variables set --shared KEY=value | Set shared variable | | railway variables set --sealed KEY=value | Set sealed variable | | railway variables delete KEY | Delete variable | | railway variables list | List all variables |

Additional Resources

• References:

  • references/environment-types.md: Detailed environment guide
  • references/variable-scoping.md: Variable scoping patterns
  • references/service-sources.md: Service deployment sources

• Scripts:

  • scripts/init-project.sh: Initialize complete project
  • scripts/sync-env.sh: Sync variables between environments

• Railway Documentation:

  • Projects
  • Environments
  • Variables
  • PR Environments