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.

What You'll Need

Before deploying to Railway, ensure you have:

• A Railway Account to manage your deployments
• Your ADK-TS project ready for deployment
• Docker installed and configured on your local machine (Optional)
• A Container Registry Account (e.g., Docker Hub) for storing your Docker images (Optional)

Deployment Options

Railway offers three deployment methods:

1. GitHub Auto-Deploy (No Docker Required): Railway automatically detects and builds your project from GitHub.
2. Custom Dockerfile via GitHub: Use a Dockerfile in your repo for custom builds
3. Pre-Built Docker Image from Docker Hub: Build and push your Docker image to Docker Hub, then deploy it on Railway

Option 1: GitHub Auto-Deploy (No Docker Required)

Railway uses Railpack to automatically detect and build your Node.js/TypeScript project without requiring Docker knowledge. Recommended for beginners.

Step 1: Push to GitHub

Commit and push your code to GitHub:

git add .
git commit -m "Prepare 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 (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 3: Configure Environment Variables

See Configuring Environment Variables below for detailed instructions.

Step 4: Automatic Deployment

Railway handles everything automatically:

• First deployment: Clones your repo, installs dependencies, builds, and deploys
• Future updates: Every time you push to your connected branch, Railway rebuilds and redeploys
• No manual steps needed after initial setup

Option 2: Custom Dockerfile via GitHub

Use a custom Dockerfile when you need more control over the build process or require system-level dependencies.

Step 1: Create Dockerfile and Push to GitHub

Create a Dockerfile in your project root. See the Docker deployment guide for a complete Dockerfile example.

Commit and push the Dockerfile to GitHub:

git add Dockerfile
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 (if first time)
5. Choose your ADK-TS repository from the list
6. Railway will detect the Dockerfile and use it for building

Step 3: Configure Environment Variables

See Configuring Environment Variables below.

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: Pre-Built Docker Image from Docker Hub

Build your Docker image locally and deploy it to Railway from Docker Hub for maximum control over the build process.

Step 1: Build and Push Docker Image

First, create a Dockerfile in your project root. See the Docker deployment guide for a complete Dockerfile example.

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 Docker Hub:

# Login to Docker Hub
docker login

# Push the image
docker push your_docker_username/your_agent_name:tag

Step 2: Connect to Railway

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

See Configuring Environment Variables below.

Step 4: Deploy

Click "Deploy" and Railway will start your container using the pulled image.

Configuring Environment Variables

All three deployment options require environment variables to be configured in Railway. This is a one-time setup for each project.

Add Environment Variables to Railway

1. In your Railway project dashboard, click the "Variables" tab
2. Click "New Variable" to add each required environment variable

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 Docker Hub 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

• Railpack Detection: If Railway fails to detect your project type, ensure your package.json and lockfile are in the repository root, or use a custom Dockerfile.
• Deployment Stuck: If a deployment is stuck in "Building", check the logs for dependency conflicts or build-time timeouts.

Railway Best Practices

• Preview Environments: Use Railway's PR environments to test changes in an isolated production-like environment before merging to main.
• Sleeping Services: For development or non-critical bots, use the "Sleep" feature to save on credits when the bot is inactive.
• Project Structure: Keep related services (e.g., your agent and a database) within the same Railway project for easier networking and management.

Next Steps