Deploying an Agent

Prerequisites

Before you begin, ensure you have:

• Docker: Installed and configured on your local machine.
• DockerHub Account: To push your Docker image (optional if using GitHub CI).
• Railway Account: Sign up at railway.app.
• ADK-TS Project: Set up with a .env file containing required variables (e.g., DISCORD_TOKEN, GOOGLE_API_KEY).
• GitHub Repository: Your project pushed to GitHub (e.g., your-username/your-repo).

Steps

1. Configure, Build and Push Docker Image

1. Configure a Dockerfile
   Create a Dockerfile in your project root directory. This file defines how to build your Docker image:

   # 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 configuration
   COPY tsconfig.json ./
   # Copy source code
   COPY src ./src
   # Build the TypeScript 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"]

   Key Points:

   • Alpine Linux: Lightweight base image for smaller container size
   • pnpm: Fast, disk space efficient package manager
   • Layer Caching: Copying package files before source code optimizes build time
   • Frozen Lockfile: Ensures exact dependency versions for reproducible builds
   • Production Build: Compiles TypeScript to JavaScript for runtime

2. Build the Docker Image
   In your project root directory, run one of the following commands to build your Docker image:

   Syntax:

   docker build -t your_docker_username/your_agent_name:tag .

   For cross-platform compatibility:

   docker buildx build --platform linux/amd64 -t your_docker_username/your_agent_name:tag .

3. Push to DockerHub
   Log in to DockerHub and push the image:

   docker login
   docker push your_docker_username/your_agent_name:tag

   Alternative: GitHub CI with Railway
   Push your Dockerfile to your GitHub repository. Configure a GitHub Actions workflow to build and push the Docker image to DockerHub. Link your Railway project to the GitHub repo, enabling Railway to automatically deploy updates from the CI pipeline.

2. Set Up Railway

1. Create a New Project

   • Log in to Railway.
   • Click "New Project" and select "Deploy from Docker Image" or connect your GitHub repository.

2. Configure the Docker Image

   • For DockerHub: Enter the image name your_docker_username/your_agent_name:tag.
   • For GitHub CI: Select your repo and branch; Railway will use the Dockerfile from the repository.

3. Add Environment Variables

   • In the Railway dashboard, go to "Variables" and add required variables from your .env file, e.g.:

     DISCORD_TOKEN=your_discord_bot_token_here
     LLM_MODEL=gemini-2.5-flash
     GOOGLE_API_KEY=your_google_api_key_here
     ADK_DEBUG=false

4. Deploy the Service

   • Click "Deploy" to launch the container with your Docker image or GitHub CI build.

3. Verify Deployment

• You can test your bot on Telegram/Discord to confirm functionality.

Common Issues

• Docker Push Fails: Ensure DockerHub login and correct image name.
• Missing Variables: Verify all environment variables are set in Railway.
• CI Failure: Check GitHub Actions logs for build errors.

Next Steps

• Monitor deployment via Railway logs.
• Update your Dockerfile or code, push to GitHub, and redeploy via CI or manually.