Railway Deployment Patterns

Railway est une PaaS moderne idéale pour les backends Node/Python/Go/Ruby/PHP avec Postgres/Redis, qui ne rentrent pas dans un modèle serverless pur. Successor spirituel d'Heroku avec un UX modernisé.

1. Setup initial

# Install CLI
npm install -g @railway/cli

# Login
railway login

# Link un projet local à un Railway project
cd my-backend
railway init
# Choisir "Empty Project" ou template

# Deploy
railway up

railway.json

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm run build"
  },
  "deploy": {
    "startCommand": "npm run start",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

Railway utilise Nixpacks par défaut pour détecter le stack et builder — Node, Python, Ruby, Go, Rust, PHP sont auto-détectés.

2. Services et réseau privé

Dans Railway, un Project contient plusieurs Services. Les services d'un même project peuvent communiquer via Private Network (DNS interne).

my-project/
├── api (Node.js service)
├── worker (Node.js service, background jobs)
├── postgres (database)
└── redis (cache)

Chaque service a un DNS interne : postgres.railway.internal, redis.railway.internal.

Depuis api :

const pg = new Pool({
  connectionString: process.env.DATABASE_URL, // auto-injected
  // Via Railway shared env group, DATABASE_URL pointe vers postgres.railway.internal
})

3. Databases

Postgres

# Créer un service Postgres depuis le CLI
railway add postgres

# L'URL est auto-injectée dans les services qui partagent la reference variable

Railway Postgres inclut :

• Backups automatiques (snapshots quotidiens)
• UI pour queries (Data tab)
• Metrics (connections, CPU, memory)
• Upgrade de version managé

Redis, MySQL, MongoDB

railway add redis
railway add mysql
railway add mongodb

Tous suivent le même pattern — auto-provisioning + DNS interne + connection string injectée.

4. Environment variables

Service-level vs shared groups

# Variables du service courant
railway variables set STRIPE_SECRET_KEY=sk_live_xxx

# Liste
railway variables

# Env groups — partager des vars entre services
railway variables --service api

Pattern shared env group :

1. Créer une variable dans l'UI → Shared Variables
2. Référencer dans le service : ${{shared.STRIPE_SECRET_KEY}}
3. Les vars shared sont utilisables sur tous les services du project

Reference variables (inter-service)

DATABASE_URL=${{Postgres.DATABASE_URL}}
REDIS_URL=${{Redis.REDIS_URL}}
API_URL=${{api.RAILWAY_PUBLIC_DOMAIN}}

5. Cron jobs

// railway.json pour un service cron
{
  "deploy": {
    "startCommand": "node scripts/daily-job.js",
    "cronSchedule": "0 9 * * *"
  }
}

Ou créer un service dédié "cron" qui wake up, exécute, et exit.

6. Volumes (persistent storage)

# Créer un volume attaché à un service
railway volume add --mount-path /data

Utile pour :

• SQLite databases (petits projets)
• Upload de fichiers locaux (à migrer vers S3/R2 à terme)
• Logs
• Cache persistant

Limitation : un volume ne peut être attaché qu'à un seul service à la fois. Pour du shared storage, passer par R2/S3/Blob.

7. Custom domains

# Via UI : Service → Settings → Networking → Custom Domain
# Configurer un CNAME vers <project>.up.railway.app

SSL automatique via Let's Encrypt.

8. Monorepo deployment

Dans un monorepo (pnpm / turborepo) :

// railway.json à la racine du monorepo
{
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "pnpm install && pnpm --filter=@app/api build",
    "watchPatterns": ["apps/api/**", "packages/**"]
  },
  "deploy": {
    "startCommand": "pnpm --filter=@app/api start"
  }
}

Ou utiliser le setting Root Directory dans le service pour pointer vers apps/api/.

9. GitHub integration

1. Link le service à un repo GitHub
2. Choisir la branche (ex. main pour prod, staging pour staging)
3. Chaque push déclenche un deploy automatique
4. PR deploys disponibles en setting "Deploy PRs"

10. Rollback

# Liste des deployments
railway status

# Rollback vers un deployment précédent via UI :
# Deployments → ... → Redeploy

Anti-patterns

1. Stocker les secrets dans le code au lieu des variables Railway
2. Exposer Postgres/Redis publiquement — toujours via Private Network
3. Pas de backups off-Railway pour les DB critiques — ajouter un cron qui dump vers S3
4. SQLite sur volume sans migration vers Postgres avant prod → limite rapidement atteinte
5. Cron job long-running (> 5min) → passer par un service worker dédié avec queue
6. Multi-region sans raison → Railway est single-region par service, pas d'infra globale
7. Ignorer les logs — Railway fournit des logs temps-réel, à logger proprement avec pino/winston

Pricing (à jour 2025)

• Hobby : $5 crédit gratuit / mois
• Pro : $20 / membre / mois, usage-based ensuite
• Facturation à la seconde sur CPU + RAM + network + storage

Pour un projet client : monitorer le dashboard "Usage" pour anticiper les coûts.

Checklist deploy Railway

• railway.json committé
• Postgres ou DB provisionné via Railway
• Private network utilisé (pas d'URL publique de DB)
• Shared env group pour les secrets partagés
• Custom domain + SSL vérifié
• Backups DB configurés (natifs Railway ou cron vers S3)
• Logs piped vers un logger structuré
• Cron jobs si nécessaires
• Auto-deploy sur push main
• Ressources monitorées (CPU, memory, network)

Quand déléguer

• Frontend-only apps → skill deploy-vercel (dans ce plugin)
• Edge computing / Workers → skill deploy-cloudflare (dans ce plugin)
• Docker-first / regional → skill deploy-fly (dans ce plugin)
• Docker registries (GHCR, ECR) → skill deploy-docker-registries (dans ce plugin)

Ressources

• https://docs.railway.com/
• https://docs.railway.com/guides/services
• https://docs.railway.com/guides/databases
• https://nixpacks.com/