Deployment

This guide covers deploying your Brain Framework agent on any long running Node.js server environment, including database setup considerations.

Caution

Currently some plugins don’t support serverless deployments. but we are planning to add support for serverless deployments in the future.

Database Selection

Choose the appropriate database adapter based on your deployment needs:

PostgreSQL

@elizaos/adapter-postgres

• Recommended for production deployments
• Scalable and robust

SQLite

@elizaos/adapter-sqlite

• Great for development and small deployments
• Self-contained file database

Supabase

@elizaos/adapter-supabase

• Cloud-native solution
• Managed database service

Server Requirements

• Node.js 22 or higher
• pnpm 9.x (recommended)
• Database system based on chosen adapter
• Persistent storage for database files (if using SQLite)

Production Setup

1. Install required packages:

   npm

   npm i github:elizaos-plugins/adapter-postgres

   pnpm

   pnpm add github:elizaos-plugins/adapter-postgres

   yarn

   yarn add github:elizaos-plugins/adapter-postgres

2. Create a PM2 ecosystem file (ecosystem.config.js):

   module.exports = {
     apps: [
       {
         name: "brain-agent",
         script: "./dist/index.js",
         instances: 1,
         autorestart: true,
         watch: false,
         max_memory_restart: "1G",
         env: {
           NODE_ENV: "production",
           DATABASE_URL: "postgresql://user:pass@localhost:5432/db",
         },
       },
     ],
   };

3. Configure your database adapter:

   import { AgentBuilder } from "@iqai/agent";
   import { PostgresDatabaseAdapter } from "@elizaos/adapter-postgres";
   
   const agent = new AgentBuilder()
     .withDatabase(
       new PostgresDatabaseAdapter({
         connectionString: process.env.DATABASE_URL,
       })
     )
     .build();

4. Build and start:

      pnpm build
      pm2 start ecosystem.config.js

Database-Specific Considerations

PostgreSQL

# Required environment variables
DATABASE_URL=postgresql://user:pass@localhost:5432/db

SQLite

# Set file location DATABASE_PATH=./data/agent.db

Supabase

# Required environment variables SUPABASE_URL=your-project-url
SUPABASE_KEY=your-api-key

Digital Ocean Deployment Guide

Create a droplet

Here is a link to Digital Ocean guide to create a droplet: Setup a DO Droplet

Initial Server Setup

1. Connect to your droplet:

   ssh root@your_droplet_ip

2. Update the system:

   sudo apt update && sudo apt upgrade -y

Installing and Configuring NGINX

1. Install NGINX

   sudo apt install nginx -y

2. Start and Enable NGINX

   sudo systemctl start nginx
   sudo systemctl enable nginx

3. Verify the Installation

   sudo systemctl status nginx

   You can also open your web browser and navigate to:

   http://your_droplet_ip

4. Configure Firewall for NGINX

   sudo apt install ufw -y
   sudo ufw allow 'Nginx Full'

5. Test and Reload NGINX Configuration

   sudo nginx -t
   sudo systemctl reload nginx

Network Configuration

1. Install Net Tools

   sudo apt install net-tools -y
   netstat --version

2. Configure Firewall for Your Application

   sudo ufw allow ssh  # or sudo ufw allow 22/tcp
   sudo ufw allow 3000/tcp  # Adjust port as needed for your application
   sudo ufw reload
   sudo ufw enable
   sudo ufw status

Setting Up Git

1. Install Git

   sudo apt install git -y
   git --version

2. Configure Git (optional depending on use case)

   git config --global user.name "Your Name"
   git config --global user.email "[email protected]"

Node.js Environment Setup

1. Install Node.js

   curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
   sudo apt install -y nodejs

2. Verify Node.js Installation

   node -v
   npm -v

3. Install PNPM

   npm install -g pnpm
   pnpm -v

Clone Your Repository

sudo mkdir -p /home/ubuntu/
cd /home/ubuntu
git clone https://github.com/username/repository.git
cd your-project
pnpm install

Deployment Methods

You can use the following methods to deploy your agent: PM2, Docker, and Docker Compose.

PM2

PM2 Process Manager

1. Install PM2

   sudo npm install -g pm2

2. Set Up PM2 to Start on Boot (Optional)

   pm2 startup systemd
   pm2 save

3. Start Your Application with PM2

   pm2 start "pnpm dev" --name your-app-name

4. Basic PM2 Commands

   # Restart application
   pm2 restart your-app-name
   
   # Stop application
   pm2 stop your-app-name
   
   # Delete application from PM2
   pm2 delete your-app-name
   
   # View running applications
   pm2 list
   
   # Monitor application
   pm2 monit

Docker

Docker Deployment (Direct)

1. Install Docker

   sudo apt install docker.io -y
   sudo systemctl start docker
   sudo systemctl enable docker

2. Deploy with Docker

   # Build your Docker image
   docker build -t image_name .
   
   # Run your container
   docker run -d --name container_name -p host_port:container_port image_name
   
   # Stop and remove container
   docker stop container_name
   docker rm container_name

3. Sample Setup

   FROM node:23-slim
   
   WORKDIR /app
   
   # Install pnpm
   RUN npm install -g pnpm
   
   # Copy package files and install dependencies
   COPY package.json pnpm-lock.yaml* ./
   RUN pnpm install
   
   # Copy project files
   COPY src/ ./src/
   COPY tsconfig.json ./
   COPY .env ./
   
   # Create data directory for SQLite
   RUN mkdir -p data
   
   # Run the application
   CMD ["pnpm", "dev"]

4. Build and run:

   docker build -t brain-agent .
   docker run -d \
     -p 3000:3000 \
     --name brain-agent \
     -e DATABASE_URL=postgresql://user:pass@host:5432/db \
     brain-agent

5. Common commands:

   # Stop container
   docker stop brain-agent
   
   # Start container
   docker start brain-agent
   
   # View logs
   docker logs -f brain-agent

Docker Compose

Docker Compose Deployment

1. Install Docker Compose

   sudo apt install docker-compose -y

2. Create docker-compose.yml:

   version: '3.8'
   services:
     app:
       build: .
       ports:
         - "3000:3000"
       environment:
         DATABASE_URL: postgresql://user:pass@db:5432/db
       depends_on:
         - db
   
     db:
       image: postgres:15
       environment:
         POSTGRES_USER: user
         POSTGRES_PASSWORD: pass
         POSTGRES_DB: db
       volumes:
         - postgres_data:/var/lib/postgresql/data
   
   volumes:
     postgres_data:

3. Deploy with Docker Compose

   # Navigate to your project directory
   cd /path/to/your/project
   
   # Create or modify docker-compose.yml file
   # Run your containers
   docker-compose up --build -d
   
   # Stop and remove containers
   docker-compose down

4. Management commands:

   # View logs
   docker-compose logs -f

SSL Configuration (Optional)

1. Install Certbot for Let’s Encrypt SSL

   sudo apt install certbot python3-certbot-nginx -y

2. Obtain SSL Certificate

   sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

Troubleshooting

1. Check NGINX Logs

   sudo tail -f /var/log/nginx/access.log
   sudo tail -f /var/log/nginx/error.log

2. Check System Resources

   htop  # Install with: sudo apt install htop

Setting up Github CI/CD

1. Create a folder .github/workflows in your project root
2. Then a file ci.yml in the folder .github/workflows created in your project root
3. Copy and paste the following code in the ci.yml, you can edit further to your specification

name: Brain Agent CI/CD

  on:
    push:
      branches: [main]

  jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 10

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "pnpm"

      - name: Install dependencies
        run: pnpm install

      - name: Lint
        run: pnpm lint

  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "pnpm"

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 10

      - name: Install dependencies
        run: pnpm install

      - name: Build
        run: pnpm build
        env:
          LIST_YOUR_ENV_KEYS: ${{ secrets.GET_THE_SET_VALUES_IN_GITHUB_SECRET }}

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment: production

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 10

      - name: Install dependencies
        run: pnpm install

      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@v41
        with:
          files: |
            apps/**

      - name: Deploy to Server
        if: steps.changed-files.outputs.any_changed == 'true'
        uses: appleboy/[email protected]
        with:
          host: ${{ secrets.DIGITALOCEAN_HOST }}
          username: ${{ secrets.DIGITALOCEAN_USER }}
          key: ${{ secrets.DIGITALOCEAN_PRIVATE_KEY }}
          port: ${{ secrets.DIGITALOCEAN_PORT }}
          script: |
            cd /home/ubuntu/your-project/apps
            git pull origin main
            cat > .env << EOF
            LIST_YOUR_ENV_KEYS: ${{ secrets.GET_THE_SET_VALUES_IN_GITHUB_SECRET }}
            EOF

            chmod 600 .env
            pnpm install
            # pm2 restart your-agent-name or docker-compose down && docker-compose up -d --build

Deploying Your Agent to Google Cloud Run

You can deploy your agent to Google Cloud Run using either the Web UI or Command Line.

Web UI

Google Cloud Console Deployment

1. Prerequisites
   • Google Cloud Account (with billing enabled)
   • Project in GCP (or create new one)
   • Agent Code (Dockerized or supported language)

   Note: If not containerized, Cloud Run can build from source (Python/Node.js/Go)

2. Access Cloud Run
   • Go to Google Cloud Console
   • Select your project
   • Navigation Menu ☰ > Serverless > Cloud Run
3. Create Service
   • Click ”+ CREATE SERVICE”
   • Choose deployment method:
   • Existing container image (if using Docker)
   • Source code (if you want Cloud Run to build the container from your source code ie GitHub/Cloud Source)
4. Configure Service
   • Name: my-agent
   • Region: us-central1 (or closest)
   • Authentication: Allow unauthenticated if public
   • Container: Image URL or source connection
   • Advanced (optional): CPU/Memory, Auto-scaling
5. Remember to set these
   • Set port to be set to 3000
   • Add direct client interface to be used to allow health checks
   • Memory & CPU: Adjust if needed (recommended: 2 CPU, 1-2GB RAM)
   • Environment variables: Define environment variables your agent needs before deployment
   • Scaling: Set minimum and maximum instances (recommended: min. 1)
6. Deploy & Test
   • Click “CREATE” (1-2 minutes)
   • Access Service URL (https://my-agent-xyz.a.run.app)
   • Test:

   curl https://my-agent-xyz.a.run.app

Command Line

gcloud CLI Deployment

1. Prerequisites
   • Install gcloud CLI
   • Authenticate:

   gcloud auth login
   gcloud config set project PROJECT_ID

2. Deploy from Container

   gcloud run deploy my-agent \
     --image=gcr.io/PROJECT_ID/agent-image:latest \
     --platform=managed \
     --region=us-central1 \
     --allow-unauthenticated

3. Deploy from Source

   gcloud run deploy my-agent \
     --source . \
     --platform=managed \
     --region=us-central1

4. Test Deployment

   SERVICE_URL=$(gcloud run services describe my-agent \
     --region=us-central1 \
     --format="value(status.url)")
   
   curl $SERVICE_URL

5. Manage Service

   # Update deployment
   gcloud run deploy my-agent --image=NEW_IMAGE
   
   # View logs
   gcloud logging read "resource.type=cloud_run_revision"
   
   # Delete service
   gcloud run services delete my-agent

Post-Deployment

6. Monitoring
   • Logs: Cloud Console > Logging > Cloud Run
   • Metrics: Monitoring > Cloud Run Dashboard
7. Next Steps
   • Set up CI/CD with Cloud Build
   • Configure custom domains
   • Add event triggers (Pub/Sub, Storage)

For more complex configurations, refer to the: Google Cloud Run documentation