Railway Deployment Guide¶

This guide covers deploying feature branches to Railway for testing and development.

Prerequisites¶

Railway CLI installed (brew install railway)
Railway account with project access
Local development environment set up
Database dump file (if restoring data)

Quick Start¶

1. Create a New Railway Environment¶

# Create environment from current git branch
fab railway.create-branch-env

# Or specify source environment (default is 'main')
fab railway.create-branch-env --source-env=feature/xzy-branch

# Skip database copy if not needed
fab railway.create-branch-env --no-copy-database

2. Manual Configuration Steps¶

After running create-branch-env, you must complete these manual steps:

a. Configure GitHub Branch (prompted during setup)¶

When prompted, go to Railway dashboard
Select your web service
Go to Settings → Source
Change branch from 'main' to your feature branch
Press Enter to continue

b. Set Database Variables¶

Go to Railway dashboard → Your web service → Variables tab
Click "New Variable" and add these (they will autocomplete): - DATABASE_URL - Reference to Postgres service - DATABASE_PUBLIC_URL - Public URL for local access - REDIS_URL - Reference to Redis service
Click "Deploy" to apply changes

c. Set Up Development Database¶

# After database restore
fab railway.setup-dev-database --after-restore

# Or for fresh database
fab railway.setup-dev-database

d. Update Site Domain¶

Railway may assign a different domain than expected. Check the actual domain in Railway dashboard, then update:

# Replace YOUR-DOMAIN with actual Railway domain
fab railway.manage --command='shell -c "from wagtail.models import Site; s = Site.objects.filter(is_default_site=True).first(); s.hostname = \"YOUR-DOMAIN.up.railway.app\"; s.save()"'

Common Railway Commands¶

Environment Management¶

# Switch to environment
railway environment <env-name>

# List environments
railway environment list

# Delete environment
fab railway.delete-branch-env
# Or specify branch
fab railway.delete-branch-env --branch=feature/my-feature

Database Operations¶

# Connect to database
fab railway.psql

# Run SQL command
fab railway.psql --command="SELECT COUNT(*) FROM wagtailcore_page;"

# Restore database from dump
fab railway.restore-db database_dumps/prod-full-20250718.dump

# Dump database
fab railway.dump-db

# Pull data from production and set up for dev
fab railway.pull-data-dev

Django Management¶

# Run any Django management command
fab railway.manage --command=migrate
fab railway.manage --command=createsuperuser
fab railway.manage --command="collectstatic --noinput"

# Open Django shell
fab railway.manage --command=shell

Monitoring¶

# View logs
railway logs

# View service status
railway status

# View environment variables
railway variables

Troubleshooting¶

DATABASE_PUBLIC_URL Not Found¶

Error: "DATABASE_PUBLIC_URL not found in Railway environment variables"
Solution: Add DATABASE_PUBLIC_URL to your web service variables in Railway dashboard
Find the public URL in your Postgres service's Connect tab

Database Already Exists Error¶

Error: "relation already exists" during migrations
Solution: Use fab railway.setup-dev-database --after-restore instead of regular setup

Internal URL Error¶

Error: "could not translate host name 'xxx.railway.internal'"
Solution: Ensure DATABASE_PUBLIC_URL is set with the public connection string, not the internal one

Domain Not Working¶

Issue: Railway assigns a different domain than the service name
Solution: Check actual domain in Railway dashboard and update site hostname accordingly

Environment Naming¶

Railway truncates long environment names. For example: - Branch: feature/railway-deployment-improvements - Environment: feature-railway-deployment-impro (truncated to 32 chars) - Domain: May be further shortened (e.g., eidra-discovery-tool-main.up.railway.app)

Best Practices¶

Always use --after-restore when setting up dev database after a restore
Check actual domains in Railway dashboard - they may differ from service names
Set DATABASE_PUBLIC_URL immediately after creating services
Use descriptive branch names but be aware of truncation
Delete unused environments to avoid clutter and costs

Cost Considerations¶

Each environment runs its own services (web, Postgres, Redis)
Delete feature environments when no longer needed
Use fab railway.delete-branch-env for clean removal