Generate Railway Deployment Docs

Generates comprehensive, production-ready documentation for Railway platform deployments based on the official Railway documentation and best practices.

What This Skill Does

This skill creates detailed deployment documentation for applications hosted on Railway, covering:

Instructions

When a user requests Railway deployment documentation:

1. **Analyze the Project Context**

- Identify the application type (web app, API, full-stack, etc.)

- Detect framework and language (Node.js, Python, Go, etc.)

- Check for existing Railway configuration files (`railway.toml`, `railway.json`)

- Review current deployment sources (GitHub repo, Docker image, etc.)

2. **Gather Requirements**

- Ask about deployment environments (dev, staging, production)

- Determine database and storage needs

- Identify external integrations and services

- Understand CI/CD workflow requirements

- Clarify monitoring and alerting needs

3. **Generate Documentation Structure**

Create a comprehensive README or docs file with these sections:

**Overview**

- Brief description of the Railway deployment

- Architecture diagram or description

- Key services and their purposes

**Prerequisites**

- Railway account setup

- CLI installation: `npm i -g @railway/cli`

- Required environment variables

- External service accounts (if any)

**Deployment Configuration**

- Railway project and service setup

- Deployment source configuration (GitHub, Docker, etc.)

- Build and start commands

- Port and networking configuration

- Resource allocation (if customized)

**Environment Management**

- Environment strategy (static vs ephemeral)

- Variable management per environment

- Secrets handling and rotation

- Environment-specific configuration

**Database & Storage**

- Database setup (PostgreSQL, MySQL, MongoDB, Redis, etc.)

- Connection string patterns using Railway variables

- Migration strategy

- Backup and recovery procedures

- Storage bucket configuration (if applicable)

**CI/CD Integration**

- Automated deployment triggers

- GitHub Actions / GitLab CI integration examples

- Deployment hooks and health checks

- Rollback procedures

**Monitoring & Observability**

- Built-in Railway metrics and logs

- Custom monitoring setup

- Alerting configuration

- Performance optimization tips

**Troubleshooting**

- Common deployment issues

- Debug commands using Railway CLI

- Log analysis techniques

- Support resources

**Migration Guide** (if migrating from another platform)

- Step-by-step migration from Heroku/Render/Vercel/Fly/etc.

- Environment variable mapping

- Database migration steps

- DNS and domain configuration

4. **Include Practical Examples**

- Sample `railway.toml` configuration

- Environment variable templates

- CLI command examples for common tasks

- Deployment workflow diagrams

5. **Add Railway-Specific Best Practices**

- Use Railway's private networking for service-to-service communication

- Leverage reference variables (`${{SERVICE.VARIABLE}}`) for internal connections

- Configure proper health check endpoints

- Set up proper logging output (stdout/stderr)

- Handle SIGTERM gracefully for zero-downtime deployments

- Use build caching to speed up deployments

- Configure proper restart policies

6. **Format and Polish**

- Use clear markdown formatting

- Include code blocks with syntax highlighting

- Add links to official Railway documentation

- Create a table of contents for long documents

- Include version information and last updated date

Example Output Structure

```markdown

[Project Name] Railway Deployment Guide

Overview

[Brief description of the application and deployment architecture]

Quick Start

```bash

Install Railway CLI

npm i -g @railway/cli

Login and link project

railway login

railway link

Deploy

railway up

```

Environment Setup

Required Variables

| Variable | Description | Example |

|----------|-------------|---------|

| `DATABASE_URL` | PostgreSQL connection | `${{Postgres.DATABASE_URL}}` |

| `API_KEY` | External service key | (set in Railway dashboard) |

Production Environment

[Specific production configuration details]

Database Configuration

PostgreSQL Setup

1. Add PostgreSQL plugin via Railway dashboard

2. Reference in your service: `DATABASE_URL=${{Postgres.DATABASE_URL}}`

3. Run migrations on deploy:

```toml

[deploy]

startCommand = "npm run migrate && npm start"

```

CI/CD Pipeline

GitHub Actions Integration

[Example workflow file]

Monitoring

Built-in Metrics

Alerting

[How to set up alerts for critical events]

Troubleshooting

Deployment Failures

[Common issues and solutions]

Logs Access

```bash

railway logs

railway logs --service backend --environment production

```

References

```

Constraints

When to Use This Skill

Use this skill when: