Railway Dev/Prod Environment Setup Guide

This guide walks you through setting up separate dev and production environments on Railway, with isolated databases and environment variables.

---

Prerequisites

1. Railway Account: Sign up at railway.app
2. Railway CLI: Install globally

   npm install -g @railway/cli
   

3. Railway Login: Authenticate

   railway login
   

---

Part 1: Production Environment Setup

Step 1: Create Production PostgreSQL Database

# Create a new Railway project (if you don't have one)
railway init

# Add PostgreSQL service
railway add --database postgres

# Name it: archety-postgres-production

In Railway Dashboard: 1. Go to your project 2. Click on the PostgreSQL service 3. Rename to archety-postgres-production 4. Note the DATABASE_URL connection string

Step 2: Create Production Web Service

# Link to the production service
railway service

# Select: archety-backend-prod (or create new)

In Railway Dashboard: 1. Connect GitHub repository 2. Set branch to master 3. Disable auto-deploy (manual deploys only for prod) 4. Connect to archety-postgres-production database

Step 3: Set Production Environment Variables

Run these commands one at a time (Railway CLI):

# Core Configuration
railway variables set ENVIRONMENT=production
railway variables set LOG_LEVEL=INFO
railway variables set BASE_URL=https://api.ikiro.ai

# Security Keys (generate new ones!)
railway variables set SECRET_KEY=$(openssl rand -hex 32)
railway variables set FERNET_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
railway variables set EDGE_SECRET=$(openssl rand -hex 32)

# Memory Service Keys
railway variables set SUPERMEMORY_API_KEY=your_supermemory_api_key_here  # Primary
railway variables set MEM0_API_KEY=your_mem0_api_key_here  # Legacy fallback (optional)

# LLM Provider Keys
railway variables set OPENAI_API_KEY=your_openai_key_here
railway variables set ANTHROPIC_API_KEY=your_anthropic_key_here
railway variables set PERPLEXITY_API_KEY=your_perplexity_key_here

# Google OAuth (Production)
railway variables set GOOGLE_CLIENT_ID=your_google_client_id
railway variables set GOOGLE_CLIENT_SECRET=your_google_secret
railway variables set OAUTH_REDIRECT_URI=https://api.ikiro.ai/auth/callback

# Other Services
railway variables set OPENWEATHERMAP_API_KEY=your_weather_key
railway variables set SENTRY_DSN=your_sentry_dsn
railway variables set AMPLITUDE_API_KEY=your_amplitude_key

# Payment Processing (if using)
railway variables set STRIPE_SECRET_KEY=<stripe_secret_key>
railway variables set STRIPE_PUBLISHABLE_KEY=<stripe_publishable_key>
railway variables set STRIPE_WEBHOOK_SECRET=<stripe_webhook_secret>

# Frontend URLs
railway variables set FRONTEND_BASE_URL=https://ikiro.ai
railway variables set ONBOARDING_BASE_URL=https://ikiro.ai/onboarding

Or use Railway Dashboard: 1. Go to your service → Variables tab 2. Add each variable manually 3. Click "Deploy" when done

Step 4: Get Production Service IDs

# Get service ID (needed for GitHub Actions)
railway service

# Copy the service ID from the output
# Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Save this as RAILWAY_PROD_SERVICE_ID for GitHub Secrets later.

---

Part 2: Development Environment Setup

Step 5: Create Development PostgreSQL Database

# Add another PostgreSQL service to the same project
railway add --database postgres

# Name it: archety-postgres-dev

In Railway Dashboard: 1. Rename the new service to archety-postgres-dev 2. Note the DATABASE_URL connection string

Step 6: Create Development Web Service

# Create a new service in the same project
railway service

# Select "Create new service"
# Name it: archety-backend-dev

In Railway Dashboard: 1. Connect to the same GitHub repository 2. Set branch to dev 3. Enable auto-deploy (auto-deploy on push to dev) 4. Connect to archety-postgres-dev database

Step 7: Set Development Environment Variables

Switch to dev service:

railway service
# Select: archety-backend-dev

Set dev variables:

# Core Configuration
railway variables set ENVIRONMENT=development
railway variables set LOG_LEVEL=DEBUG
railway variables set BASE_URL=https://archety-backend-dev.up.railway.app

# Security Keys (different from prod!)
railway variables set SECRET_KEY=$(openssl rand -hex 32)
railway variables set FERNET_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
railway variables set EDGE_SECRET=$(openssl rand -hex 32)

# Memory Service Keys (can use same or separate)
railway variables set SUPERMEMORY_API_KEY=your_supermemory_api_key_here  # Primary
railway variables set MEM0_API_KEY=your_mem0_api_key_here  # Legacy fallback (optional)

# LLM Provider Keys (can use same as prod)
railway variables set OPENAI_API_KEY=your_openai_key_here
railway variables set ANTHROPIC_API_KEY=your_anthropic_key_here
railway variables set PERPLEXITY_API_KEY=your_perplexity_key_here

# Google OAuth (Development)
railway variables set GOOGLE_CLIENT_ID=your_google_client_id
railway variables set GOOGLE_CLIENT_SECRET=your_google_secret
railway variables set OAUTH_REDIRECT_URI=https://archety-backend-dev.up.railway.app/auth/callback

# Other Services
railway variables set OPENWEATHERMAP_API_KEY=your_weather_key
railway variables set SENTRY_DSN=your_sentry_dsn
railway variables set AMPLITUDE_API_KEY=your_amplitude_key

# Payment Processing (use TEST keys!)
railway variables set STRIPE_SECRET_KEY=<stripe_test_secret_key>
railway variables set STRIPE_PUBLISHABLE_KEY=<stripe_test_publishable_key>
railway variables set STRIPE_WEBHOOK_SECRET=<stripe_test_webhook_secret>

# Frontend URLs (can be same or dev frontend)
railway variables set FRONTEND_BASE_URL=https://dev.ikiro.ai
railway variables set ONBOARDING_BASE_URL=https://dev.ikiro.ai/onboarding

Step 8: Get Development Service ID

# Make sure you're on dev service
railway service

# Copy the service ID

Save this as RAILWAY_DEV_SERVICE_ID for GitHub Secrets later.

---

Part 3: Verify Setup

Check Production

# Switch to production service
railway service
# Select: archety-backend-prod

# View variables
railway variables

# Check deployment status
railway status

# View logs
railway logs

Check Development

# Switch to dev service
railway service
# Select: archety-backend-dev

# View variables
railway variables

# Check deployment status
railway status

# View logs
railway logs

---

Part 4: Get Railway Token for GitHub Actions

# Generate a Railway API token
railway token

This will output a token like: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Save this as RAILWAY_TOKEN in GitHub Secrets.

---

Part 5: Configure GitHub Repository

Add GitHub Secrets

Go to your GitHub repository → Settings → Secrets and variables → Actions

Add these secrets:

Secret Name	Value	Source
RAILWAY_TOKEN	Railway API token	From railway token
RAILWAY_DEV_SERVICE_ID	Dev service ID	From dev service
RAILWAY_PROD_SERVICE_ID	Prod service ID	From prod service

---

Part 6: Local Development Setup

Link to Dev Environment

# In your project directory
railway link

# Select: archety-backend-dev

Run Locally with Dev Environment

# Pull environment variables from dev
railway run bash

# This opens a shell with all dev env vars loaded
# Now you can run the app:
python -m uvicorn app.main:app --reload

Alternative: Use .env for Local

# Copy template
cp .env.example .env

# Edit .env with your local/dev keys
nano .env

# Run normally
./run.sh

---

Part 7: Database Migrations

Run Migrations on Dev

# Switch to dev service
railway service
# Select: archety-backend-dev

# Run migrations
railway run alembic upgrade head

Run Migrations on Prod

# Switch to prod service
railway service
# Select: archety-backend-production

# Run migrations
railway run alembic upgrade head

Note: Migrations also run automatically on deployment via start_with_migrations.sh.

---

Part 8: Deployment Workflow

Deploy to Dev (Automatic)

# Create dev branch if it doesn't exist
git checkout -b dev

# Push to dev branch
git push origin dev

# Railway auto-deploys! Check status:
railway status  # (make sure you're linked to dev service)

Deploy to Prod (Manual)

# Merge dev to master
git checkout master
git merge dev
git push origin master

# Manually deploy via Railway Dashboard or CLI:
railway up --service archety-backend-production

Or use GitHub Actions (covered in CI/CD docs).

---

Part 9: Monitoring & Debugging

View Logs

# Dev logs
railway service  # Select dev
railway logs --follow

# Prod logs
railway service  # Select prod
railway logs --follow

Health Checks

# Dev health
curl https://archety-backend-dev.up.railway.app/health

# Prod health
curl https://archety-backend-prod.up.railway.app/health

Database Access

# Connect to dev database
railway service  # Select dev
railway connect postgres

# Connect to prod database
railway service  # Select prod
railway connect postgres

---

Quick Reference Commands

# Switch service
railway service

# View variables
railway variables

# Set a variable
railway variables set KEY=value

# Deploy manually
railway up

# View logs
railway logs

# Check status
railway status

# Run command in Railway environment
railway run <command>

# Connect to database
railway connect postgres

---

Security Best Practices

1. Never commit secrets to git
2. Use different tokens for dev and prod
3. Generate new SECRET_KEY and FERNET_KEY for each environment
4. Use Stripe test keys in dev
5. Use separate Telegram bots for dev and prod
6. Rotate keys if they're ever exposed
7. Use Railway's audit logs to track who changed what

---

Troubleshooting

"Service not found"

railway link  # Re-link to correct service

"Database connection failed"

• Check DATABASE_URL is set in Railway
• Verify database service is running
• Check if database and web service are in same project

"Environment variable not set"

railway variables  # List all variables
railway variables set KEY=value  # Set missing variable

"Auto-deploy not working"

• Check GitHub integration in Railway dashboard
• Verify correct branch is selected
• Check Railway deployment logs

---

Next Steps

After completing this setup:

1. ✅ Create GitHub Actions workflows (see docs/CI_CD_SETUP.md)
2. ✅ Set up branch protection rules
3. ✅ Test dev deployment pipeline
4. ✅ Test prod manual deployment
5. ✅ Configure monitoring and alerts

---

Questions? Check the Railway documentation or ask in the team chat.