Railway Deployer

Infrastructure engineer specializing in Railway platform deployments and service configuration.

Quick Reference

Property	Value
Domain	DevOps
FORGE Stage	4 (DEPLOY)
Version	1.0.0
Output Types	`railway.json`, deployment configs

Overview

Use this agent when you need to:

Deploy Hono APIs or Next.js apps to Railway
Configure environment variables and secrets
Set up PostgreSQL or Redis plugins
Configure domains, SSL, and health checks
Manage multi-environment deployments (staging, production)

The Railway Deployer automates the creation of Railway service configurations, handles environment variable management, and ensures deployments are healthy and production-ready.

Core Capabilities

Service Configuration

Define Railway services with proper resource allocation, build commands, and replica counts

Environment Management

Configure variables per environment with secret references and plugin linkage

Network Setup

Configure custom domains, internal networking, SSL certificates, and health checks

Database Provisioning

Set up PostgreSQL, Redis, and other Railway plugins with optimal configurations

When to Use

Deploying SO1 Control Plane API (Hono backend)

Deploying SO1 Console (Next.js frontend)

Setting up staging and production environments

Configuring PostgreSQL or Redis for an application

Setting up health check endpoints

Managing Railway environment variables

Not suitable for:

Non-Railway platforms (AWS, GCP, Azure)
Manual Railway console configuration
Non-containerized applications

Usage Examples

Deploy Hono API
Deploy Next.js Frontend
Multi-Environment Setup

Deploy the SO1 Control Plane API with PostgreSQL and Redis:

{
  "railwayConfig": {
    "generatedBy": "railway-deployer",
    "version": "1.0.0",
    "project": {
      "name": "so1-control-plane",
      "description": "SO1 Control Plane API - Hono backend"
    },
    "environments": {
      "production": {
        "services": [{
          "name": "api",
          "source": {
            "repo": "so1-io/so1-control-plane-api",
            "branch": "main"
          },
          "build": {
            "builder": "NIXPACKS",
            "buildCommand": "pnpm install --frozen-lockfile && pnpm build"
          },
          "deploy": {
            "startCommand": "pnpm start",
            "healthcheckPath": "/health",
            "numReplicas": 2
          },
          "networking": {
            "publicDomain": "api.so1.io",
            "internalPort": 3000
          }
        }],
        "plugins": [
          {
            "type": "postgresql",
            "name": "so1-db",
            "config": { "version": "15" }
          },
          {
            "type": "redis",
            "name": "so1-cache",
            "config": { "version": "7" }
          }
        ],
        "variables": {
          "NODE_ENV": "production",
          "DATABASE_URL": "${{Postgres.DATABASE_URL}}",
          "REDIS_URL": "${{Redis.REDIS_URL}}"
        }
      }
    }
  }
}

Result: Complete Railway configuration for production API deployment with database, caching, and health checks.

Deploy the SO1 Console frontend application:

{
  "railwayConfig": {
    "project": {
      "name": "so1-console",
      "description": "SO1 Console - Next.js frontend"
    },
    "environments": {
      "production": {
        "services": [{
          "name": "web",
          "source": {
            "repo": "so1-io/so1-console",
            "branch": "main"
          },
          "build": {
            "builder": "NIXPACKS",
            "buildCommand": "pnpm install && pnpm build"
          },
          "deploy": {
            "startCommand": "pnpm start",
            "healthcheckPath": "/api/health",
            "numReplicas": 2
          },
          "networking": {
            "publicDomain": "console.so1.io"
          },
          "resources": {
            "memory": "1GB",
            "cpu": "1"
          }
        }],
        "variables": {
          "NEXT_PUBLIC_API_URL": "https://api.so1.io",
          "CLERK_SECRET_KEY": "${{shared.CLERK_SECRET_KEY}}"
        }
      }
    }
  }
}

Result: Next.js deployment with proper resource allocation and environment variables.

Configure both staging and production environments:

{
  "environments": {
    "production": {
      "services": [{
        "name": "api",
        "source": { "branch": "main" },
        "deploy": { "numReplicas": 2 },
        "networking": { "publicDomain": "api.so1.io" },
        "resources": { "memory": "512MB", "cpu": "0.5" }
      }],
      "variables": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      }
    },
    "staging": {
      "services": [{
        "name": "api",
        "source": { "branch": "develop" },
        "deploy": { "numReplicas": 1 },
        "networking": { "publicDomain": "api-staging.so1.io" },
        "resources": { "memory": "256MB", "cpu": "0.25" }
      }],
      "variables": {
        "NODE_ENV": "staging",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Result: Separate configurations optimized for production (HA, more resources) and staging (cost-effective).

Outputs

Railway Configuration File

// railway.json
{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "pnpm install --frozen-lockfile && pnpm build",
    "watchPatterns": ["src/**", "package.json"]
  },
  "deploy": {
    "numReplicas": 1,
    "startCommand": "pnpm start",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 30,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 3
  }
}

Health Check Implementation

// src/routes/health.ts (Hono)
import { Hono } from 'hono';
import { db } from '../db';

const app = new Hono()
  .get('/health', async (c) => {
    const checks = {
      status: 'healthy',
      timestamp: new Date().toISOString(),
      checks: {
        database: 'unknown',
        redis: 'unknown',
      },
    };

    try {
      await db.execute('SELECT 1');
      checks.checks.database = 'healthy';
    } catch {
      checks.checks.database = 'unhealthy';
      checks.status = 'degraded';
    }

    return c.json(checks, checks.status === 'healthy' ? 200 : 503);
  });

export default app;

Resource Sizing Guide

Application Type	Memory	CPU	Replicas
API (light)	256MB	0.25	1
API (standard)	512MB	0.5	2
API (heavy)	1GB+	1+	2+
Next.js SSR	512MB-1GB	0.5-1	2
Static site	256MB	0.25	1
Worker/Cron	256MB	0.25	1

FORGE Gate Compliance

Entry Gates (Pre-conditions)

Application code passing CI checks

The application must have successfully passed all CI pipeline tests, linting, and build steps before deployment configuration begins.

Environment variables documented

All required environment variables must be listed in .env.example with descriptions of their purpose and where to obtain values.

Railway project exists or creation approved

Either the Railway project already exists in the Railway dashboard, or there is explicit approval to create a new project.

Exit Gates (Post-conditions)

Railway service configuration complete

The railway.json file is created with proper build commands, deploy settings, and resource allocation.

Environment variables configured

All environment variables are set in Railway dashboard with proper references to plugins and shared secrets.

Health check endpoints verified

The /health endpoint returns 200 OK and validates database/Redis connectivity.

Deployment successful and healthy

The deployment completes without errors, health checks pass, and the service is accessible via its public domain.

Integration Points

Control Plane API

// Track deployment status
POST /api/v1/deployments
{
  "service": "so1-control-plane-api",
  "environment": "production",
  "status": "success",
  "healthCheckUrl": "https://api.so1.io/health",
  "deployedAt": "2024-01-15T10:30:00Z"
}

// Retrieve deployment history
GET /api/v1/deployments?service=so1-control-plane-api

Veritas Prompts

Consumed Prompts
Produced Prompts

Prompt ID	Purpose
`vrt-g7h8i9j0`	Railway deployment best practices (service config, scaling, networking)
`vrt-k1l2m3n4`	Container optimization guidelines (build optimization, image size, startup time)

When novel deployment patterns are discovered:

{
  "id": "vrt-railway-pattern-001",
  "category": "task",
  "status": "draft",
  "content": "Railway deployment pattern for Hono API with Drizzle ORM",
  "outputPath": "veritas/agent-prompts/devops/railway-pattern-001.json"
}

Agent	Relationship	Use Case
GitHub Actions Engineer	Upstream	Triggers deployment after CI passes
Pipeline Auditor	Downstream	Reviews deployment config for security issues
Incident Commander	Alerts	Receives alerts on deployment failures
Hono Backend	Creates	Builds the APIs that Railway Deployer deploys

Source Files

View Agent Source

Repository: so1-io/so1-agents
Path: agents/devops/railway-deployer.md
Version: 1.0.0

Common Patterns

Variable Reference Syntax

{
  "variables": {
    // Plugin variables
    "DATABASE_URL": "${{Postgres.DATABASE_URL}}",
    "REDIS_URL": "${{Redis.REDIS_URL}}",
    
    // Shared secrets
    "API_KEY": "${{shared.API_KEY}}",
    
    // Service URLs
    "OTHER_SERVICE_URL": "${{other-service.RAILWAY_PUBLIC_DOMAIN}}"
  }
}

Rollback Procedure

# Railway CLI rollback
railway rollback --service api --to <deployment-id>

# Or via API
curl -X POST "https://backboard.railway.app/graphql/v2" \
  -H "Authorization: Bearer $RAILWAY_TOKEN" \
  -d '{"query": "mutation { deploymentRollback(id: \"<deployment-id>\") { id } }"}'

Common Deployment Errors

Error	Cause	Resolution
Build failed	Missing dependencies or build error	Check build logs, verify `package.json`
Health check timeout	App not starting in time	Increase timeout, check startup logs
OOM killed	Memory limit exceeded	Increase memory allocation
Deploy stuck	Health check never passes	Verify health endpoint returns 200
Variable missing	Secret not configured	Add missing variables in Railway dashboard

Next Steps:

Agents Overview

Orchestration

Automation

Engineering

DevOps

Documentation

Prompts

Incident

Railway Deployer

Railway Deployer

Quick Reference

Overview

Core Capabilities

Service Configuration

Environment Management

Network Setup

Database Provisioning

When to Use

Usage Examples

Outputs

Railway Configuration File

Health Check Implementation

Resource Sizing Guide

FORGE Gate Compliance

Entry Gates (Pre-conditions)

Exit Gates (Post-conditions)

Integration Points

Control Plane API

Veritas Prompts

Source Files

View Agent Source

Common Patterns

Variable Reference Syntax

Rollback Procedure

Common Deployment Errors

Agents Overview

Orchestration

Automation

Engineering

DevOps

Documentation

Prompts

Incident

​Railway Deployer

​Quick Reference

​Overview

​Core Capabilities

Service Configuration

Environment Management

Network Setup

Database Provisioning

​When to Use

​Usage Examples

​Outputs

​Railway Configuration File

​Health Check Implementation

​Resource Sizing Guide

​FORGE Gate Compliance

​Entry Gates (Pre-conditions)

​Exit Gates (Post-conditions)

​Integration Points

​Control Plane API

​Veritas Prompts

​Related Agents

​Source Files

View Agent Source

​Common Patterns

​Variable Reference Syntax

​Rollback Procedure

​Common Deployment Errors

Railway Deployer

Quick Reference

Overview

Core Capabilities

When to Use

Usage Examples

Outputs

Railway Configuration File

Health Check Implementation

Resource Sizing Guide

FORGE Gate Compliance

Entry Gates (Pre-conditions)

Exit Gates (Post-conditions)

Integration Points

Control Plane API

Veritas Prompts

Related Agents

Source Files

Common Patterns

Variable Reference Syntax

Rollback Procedure

Common Deployment Errors