# Railway Deployment Runbook (Common Platform)

Last updated: 2026-02-16

This runbook covers repeatable deploys for shared services in `learning_ai_common_plat`.

## Scope

Deployable Railway services from this repo:

1. `platform-service`
2. `extraction-service`

There are currently **2 Railway backend services** in this repo. Monitoring (`loki`, `grafana`, `gateway`) is local Docker Compose infra, not deployed by Railway scripts.

## Deploy Scripts Inventory

| Script | Purpose | Services Affected |
| --- | --- | --- |
| `scripts/railway-deploy.sh` | Deploy code to Railway via `railway up` | `platform-service`, `extraction-service`, or both |
| `scripts/railway-sync-env.sh` | Sync selected vars from local `.env` into Railway service variables | `platform-service`, `extraction-service`, or both |
| `scripts/docker-prep.sh` | Build shared packages for local Docker builds | No Railway deploy; local prep only |

## One-Time Setup

1. Install Railway CLI:
```bash
npm i -g @railway/cli
```
2. Login:
```bash
railway login
```
3. Optional shell defaults:
```bash
export RAILWAY_PROJECT_ID="a6bc4ea7-e89c-42da-819a-8879fb022a0d"
export RAILWAY_ENVIRONMENT="production"
```

## First Deploy (or Env Changes)

1. Update local `.env` at repo root.
2. Sync env vars to Railway (no deploy per var):
```bash
scripts/railway-sync-env.sh all --env-file .env
```
3. Deploy both services:
```bash
scripts/railway-deploy.sh all
```

## Repeat Deploy for New Code

If only code changed:
```bash
scripts/railway-deploy.sh all
```

Single-service deploys:
```bash
scripts/railway-deploy.sh platform
scripts/railway-deploy.sh extraction
```

If env vars changed too:
```bash
scripts/railway-sync-env.sh all --env-file .env
scripts/railway-deploy.sh all
```

## Useful Flags

### `scripts/railway-deploy.sh`

```bash
# Sync env before deploy, then deploy extraction
scripts/railway-deploy.sh extraction --sync-env --env-file .env

# Custom message + attach to logs
scripts/railway-deploy.sh platform --message "hotfix: auth token handling" --attach

# Dry run
scripts/railway-deploy.sh all --sync-env --dry-run
```

### `scripts/railway-sync-env.sh`

```bash
# Sync only platform-service
scripts/railway-sync-env.sh platform --env-file .env

# Trigger deploys while setting vars (normally skipped)
scripts/railway-sync-env.sh extraction --trigger-deploys

# Dry run
scripts/railway-sync-env.sh all --dry-run
```

## Verification

After deploy:

```bash
railway link --project "$RAILWAY_PROJECT_ID" --environment "$RAILWAY_ENVIRONMENT"
railway service status -a -e "$RAILWAY_ENVIRONMENT"
```

Service logs:

```bash
railway logs --service platform-service --environment "$RAILWAY_ENVIRONMENT" --deployment --lines 200
railway logs --service extraction-service --environment "$RAILWAY_ENVIRONMENT" --deployment --lines 200
```

## Troubleshooting

1. `Railway CLI is not authenticated`:
```bash
railway login
```
2. `Unable to access Railway service ...`:
   - Confirm project ID and environment.
   - Confirm service names: `platform-service`, `extraction-service`.
3. Missing required vars during sync:
   - Provide `COSMOS_ENDPOINT`, `COSMOS_KEY`, `JWT_SECRET` in `.env`, or
   - Set `AZURE_KEYVAULT_URL` and ensure runtime identity can fetch secrets.
4. Deploy command succeeds but app is unhealthy:
   - Check deployment logs using `railway logs --deployment`.
   - Validate env vars synced for the affected service.