Railway

Railway is a cloud platform that simplifies deploying containerized applications with built-in CI/CD and automatic scaling. Best for: Quick deployments, containerized applications, and managed infrastructure. Railway offers simple setup and automatic scaling, though pricing may be higher for large-scale deployments. This guide shows you how to deploy your ADK-TS agent to Railway using a Docker image.

Prerequisites

Required:

• Railway Account: Sign up at railway.app
• GitHub Repository: Your ADK-TS project pushed to GitHub
• Built and tested ADK-TS agent locally
• Environment variables documented

Optional (only for custom Docker builds):

• Docker: Installed locally - Get Docker
• DockerHub Account: For pre-built image deployment

Deployment Options

Railway offers three deployment methods:

1. GitHub Auto-Deploy: Railway automatically detects and builds your project (Recommended - No Docker needed)
2. GitHub with Dockerfile: Use a custom Dockerfile for advanced build requirements
3. DockerHub Image: Build locally, push to DockerHub, deploy from Railway

Option 1: GitHub Auto-Deploy (Recommended)

This is the easiest way to deploy to Railway. It automatically detects your Node.js/TypeScript project and handles everything for you with Railway's auto-detection and build system. No Docker knowledge required.

When to Use This Option

Use auto-deploy when your agent:

• Uses standard ADK-TS features (LLM APIs, tools, memory)
• Has a typical TypeScript build process
• Doesn't need special system dependencies or custom build steps

Step 1: Prepare Your Project

Ensure your package.json has proper build and start scripts:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Railway will automatically run pnpm install, pnpm build, and then pnpm start.

Step 2: Push to GitHub

Commit and push your code to GitHub:

git add .
git commit -m "Prepare for Railway deployment"
git push origin main

Step 3: Connect to Railway

1. Log in to Railway
2. Click "New Project"
3. Select "Deploy from GitHub repo"
4. Authorize Railway to access your GitHub account (if first time)
5. Choose your ADK-TS repository from the list
6. Railway automatically detects it's a Node.js project and starts building

Step 4: Configure Environment Variables

In Railway:

1. In your Railway project, click the "Variables" tab
2. Click "New Variable" for each required variable
3. Add your configuration:
   • OPENAI_API_KEY or GOOGLE_API_KEY (depending on your LLM provider)
   • LLM_MODEL (e.g., gpt-4, gemini-2.5-flash)
   • Bot tokens (DISCORD_TOKEN, TELEGRAM_BOT_TOKEN, etc.)
   • Any other variables your agent needs

Railway encrypts all environment variables automatically.

Step 5: Monitor Deployment

Railway automatically deploys after the build completes. Check the "Deployments" tab to see:

• Build logs (dependency installation, TypeScript compilation)
• Runtime logs (your agent starting up)
• Deployment status

Verifying Your Deployment

After deployment:

• Check Railway logs for successful startup messages
• Test your agent (send a Discord message, make an API call, etc.)
• Monitor the Railway dashboard for resource usage and errors

Option 2: GitHub with Custom Dockerfile

Use this option when you need more control over the build process or have special requirements.

When to Use This Option

Use a custom Dockerfile when your agent needs:

• System-level dependencies (ffmpeg, Chrome/Puppeteer, image processing libraries)
• Custom build processes or optimizations
• Multi-stage builds for smaller production images
• Non-standard runtime configurations
• Specific versions of Node.js or system packages

Step 1: Push Dockerfile to GitHub

Commit and push your Dockerfile to your GitHub repository:

git add Dockerfile .dockerignore
git commit -m "Add Dockerfile for Railway deployment"
git push origin main

Step 2: Connect to Railway

1. Log in to Railway
2. Click "New Project"
3. Select "Deploy from GitHub repo"
4. Authorize Railway to access your GitHub account (first time only)
5. Choose your repository from the list
6. Select the branch to deploy (usually main)
7. Railway will detect the Dockerfile and use it for building

Step 3: Configure Environment Variables

Add your environment variables in Railway's "Variables" tab, just like in Option 1.

Step 4: Automatic Deployment

Railway now handles everything automatically:

• First deployment: Detects your Dockerfile, builds the image, and deploys
• Future updates: Every time you push to your connected branch, Railway rebuilds and redeploys
• No manual steps needed after initial setup

Option 3: Deploy from DockerHub

Step 1: Build and Push Docker Image

Create a Dockerfile in your project root:

# Use Node.js 20 Alpine as the base image (lightweight Linux distribution)
FROM node:20-alpine

# Enable pnpm package manager and set a specific version for consistency
RUN corepack enable && corepack prepare pnpm@9.12.0 --activate

# Set the working directory inside the container
WORKDIR /app

# Copy package files first for better Docker layer caching
COPY package.json pnpm-lock.yaml ./

# Install dependencies using frozen lockfile for reproducible builds
RUN pnpm install --frozen-lockfile

# Copy TypeScript config and source code
COPY tsconfig.json ./
COPY src ./src

# Build the project
RUN pnpm build

# Set production environment
ENV NODE_ENV=production

# Define the command to run when the container starts
CMD ["node", "dist/index.js"]

Build for Railway:

Railway uses AMD64 processors, so build specifically for that platform:

# Build for Railway (AMD64 platform)
docker buildx build --platform linux/amd64 -t your_docker_username/your_agent_name:tag .

Replace your_docker_username with your Docker Hub username, your_agent_name with your project name, and tag with a version (like v1.0 or latest).

Push to DockerHub:

1. Login to Docker Hub:

docker login

2. Push your image:

docker push your_docker_username/your_agent_name:tag

Step 2: Set Up Railway Project

In the Railway dashboard:

1. Log in to Railway
2. Click "New Project" in the top right
3. Select "Deploy from Docker Image" from the options
4. Enter your full image name exactly as you pushed it: your_docker_username/your_agent_name:tag
5. Railway will pull your image from Docker Hub

Step 3: Configure Environment Variables

Add variables in the Railway dashboard Variables tab (same process as Option 1).

Step 4: Deploy

Click "Deploy" to launch your agent. Railway will pull the Docker image and start your container.

Verifying Deployment

Check Deployment Status

In your Railway project dashboard:

1. Look for the "Deployments" section - it should show "Active" with a green indicator
2. Click on the latest deployment to view detailed logs
3. Check the logs for your agent's startup messages
4. Look for any error messages (shown in red)

Test Your Agent

Once deployment is active, test that it works:

• Discord bots: Send a command in your Discord server
• Telegram bots: Message your bot
• API agents: Make a test HTTP request to your endpoint
• Check logs: Watch Railway logs in real-time to see your agent responding

Monitoring and Updates

View Logs

Railway provides real-time logs in the "Logs" tab of your deployment. Use them to:

• Debug issues by viewing error messages
• Monitor your agent's activity and responses
• Track warnings or performance issues

Updating Your Deployment

For GitHub deployments (Options 1 & 2):

1. Make code changes locally
2. Test changes locally
3. Commit and push to your connected branch:

   git add .
   git commit -m "Update agent features"
   git push origin main

4. Railway automatically detects changes, rebuilds, and redeploys
5. Watch the deployment logs to confirm success

For DockerHub deployments (Option 3):

1. Make code changes locally
2. Build and push new Docker image with a new tag (e.g., v1.1)
3. In Railway dashboard, update the image reference to the new tag
4. Railway pulls the new image and redeploys automatically

Railway Troubleshooting

Docker Push Fails

Problem: Can't push image to Docker Hub

• Verify you're logged in (run docker login)
• Check your image name format matches username/image:tag
• Confirm you have permission to push to this repository
• Check your internet connection

Missing Environment Variables

Problem: Agent crashes or features don't work

• Go to Railway's "Variables" tab and verify all variables are present
• Check that variable names match exactly what your code expects (case-sensitive)
• Look for typos in variable values
• Restart the deployment after adding missing variables

Build Failures

Problem: Railway build fails

• Click on the failed deployment to view detailed build logs
• Look for error messages about missing dependencies or syntax errors
• Verify your Dockerfile has correct syntax
• Ensure all dependencies are listed in package.json
• Check for TypeScript compilation errors in the logs

Agent Not Starting

Problem: Deployment succeeds but agent doesn't run

• Check Railway logs for runtime error messages
• Verify the CMD in your Dockerfile points to the correct file
• Ensure all required environment variables are set
• Confirm your build process creates the expected output files (check dist/ folder exists)

Railway Best Practices

Version Control

• Use specific image tags (like v1.0, v1.1) instead of latest for better tracking
• Tag images with version numbers or git commit hashes

Cost Management

• Set resource limits in Railway's settings to prevent unexpected charges
• Monitor usage in Railway's dashboard
• Use Railway's sleep feature for non-critical deployments

Reliability

• Enable health checks if your agent exposes an HTTP endpoint
• Use Railway's preview environments to test changes before deploying to production
• Monitor logs regularly to catch issues early

Security

• Never commit environment variables or secrets to git
• Railway automatically encrypts environment variables
• Rotate API keys and tokens regularly
• Use Railway's audit logs to track changes

Next Steps

• Explore the Docker deployment guide for more Docker options
• Learn about production best practices (guide coming soon)
• Set up monitoring and alerting for your agent