Star on GitHub

Docker Deployment

Docker is the recommended way to deploy OrcBot on servers. It packages everything into a single container — no need to install Node.js, npm, or system dependencies manually.

Why Docker?

Zero setup — No Node.js or npm installation needed
Portable — Runs identically on any machine (Windows, Mac, Linux, cloud)
Isolated — Won't interfere with other software on your system
Easy updates — git pull && docker compose build && docker compose up -d
Persistent data — Docker volumes survive container restarts

Prerequisites

Install Docker Desktop (Windows/Mac) or Docker Engine (Linux):

# Linux — install Docker Engine
curl -fsSL https://get.docker.com | sh

# Verify
docker --version
docker compose version

At least one LLM API key (OpenAI or Google Gemini)

Quick Start

Option A: Minimal (Recommended)

Uses Alpine Linux + Lightpanda browser. Smallest footprint (~150MB):

# 1. Clone and configure
git clone https://github.com/fredabila/orcbot.git
cd orcbot

# 2. Copy environment file and add your API keys
cp .env.example .env
nano .env

# 3. Start OrcBot + Lightpanda
docker compose -f docker-compose.minimal.yml up -d

# 4. View logs
docker logs -f orcbot

# 5. Open dashboard
# http://localhost:3100

Option B: Full Setup

Includes Playwright/Chrome browser support for full web automation (~500MB):

# Start OrcBot with Playwright
docker compose up -d

# Optionally also start Lightpanda
docker compose --profile lightpanda up -d

Environment Variables

Create a .env file from the example template:

cp .env.example .env

Then set the following variables:

Variable	Required	Description
`OPENAI_API_KEY`	One of these	OpenAI API key (GPT-4o, etc.)
`GOOGLE_API_KEY`	One of these	Google Gemini API key
`NVIDIA_API_KEY`	Optional	NVIDIA AI API key
`ANTHROPIC_API_KEY`	Optional	Anthropic Claude API key
`OPENROUTER_API_KEY`	Optional	OpenRouter API key
`TELEGRAM_TOKEN`	Optional	Telegram Bot token
`DISCORD_TOKEN`	Optional	Discord Bot token
`SERPER_API_KEY`	Optional	Serper.dev key for web search
`GATEWAY_API_KEY`	Optional	Secure the dashboard/API

Docker Commands Reference

Command	Description
`docker compose up -d`	Start containers in background
`docker compose down`	Stop and remove containers
`docker compose logs -f`	Follow live logs
`docker compose restart`	Restart containers
`docker compose build --no-cache`	Rebuild from scratch
`docker compose down -v`	Stop + delete all data

Container Architecture

┌─────────────────────────────────────────────┐
│              Docker Network                 │
│                                             │
│  ┌─────────────┐      ┌─────────────────┐  │
│  │   OrcBot    │      │   Lightpanda    │  │
│  │  Container  │─────▶│    Container    │  │
│  │  :3100      │      │    :9222        │  │
│  └─────────────┘      └─────────────────┘  │
│         │                                   │
└─────────┼───────────────────────────────────┘
          │
          ▼
    ┌───────────┐
    │  Volume   │  (persistent data)
    │orcbot-data│
    └───────────┘

The OrcBot container runs the agent + gateway (dashboard on port 3100). The Lightpanda container provides a lightweight browser for web automation. Both share a Docker network so OrcBot can reach Lightpanda at ws://lightpanda:9222.

Data Persistence & Backups

All OrcBot data is stored in a Docker volume (orcbot-data) that survives container restarts and rebuilds.

# View volume location
docker volume inspect orcbot-data

# Backup data to a tar archive
docker run --rm -v orcbot-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/orcbot-backup.tar.gz /data

# Restore from backup
docker run --rm -v orcbot-data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/orcbot-backup.tar.gz -C /

Custom Configuration

Mount a local config file for advanced settings:

# Create your config file
cat > my-config.yaml << 'EOF'
agentName: MyBot
modelName: gpt-4o
llmProvider: openai
autonomyEnabled: true
autonomyInterval: 15
telegramAutoReplyEnabled: true
whatsappEnabled: false
discordAutoReplyEnabled: false
EOF

# Mount it (add to docker-compose.yml volumes section)
volumes:
  - orcbot-data:/root/.orcbot
  - ./my-config.yaml:/root/.orcbot/orcbot.config.yaml:ro

Deploy on DigitalOcean

Docker is the easiest way to run OrcBot on a DigitalOcean Droplet:

# 1. Create a Droplet: Ubuntu 22.04, $6/mo (1GB RAM)
# 2. SSH in and install Docker
ssh root@YOUR_DROPLET_IP
curl -fsSL https://get.docker.com | sh

# 3. Clone, configure, and start
git clone https://github.com/fredabila/orcbot.git
cd orcbot
cp .env.example .env
nano .env   # add your API keys

# 4. Start with minimal setup (best for $6/mo droplets)
docker compose -f docker-compose.minimal.yml up -d

# 5. Verify
docker ps
docker logs orcbot

That's it! Dashboard available at http://YOUR_DROPLET_IP:3100.

Building a Custom Image

# Build locally
docker build -t my-orcbot .

# Build minimal version
docker build -f Dockerfile.minimal -t my-orcbot:minimal .

# Run custom image
docker run -d --name orcbot -p 3100:3100 --env-file .env my-orcbot

Updating

# Pull latest code
git pull

# Rebuild and restart (data is preserved in volume)
docker compose build --no-cache
docker compose up -d

Troubleshooting

Container won't start

# Check logs for errors
docker logs orcbot

# Common: missing API keys in .env
# Common: port 3100 already in use

Can't connect to dashboard

# Verify container is running
docker ps

# Check port mapping
docker port orcbot

# If on a server, ensure firewall allows port 3100
ufw allow 3100

WhatsApp QR code

WhatsApp requires QR code scanning on first launch. View the QR in the logs:

docker logs orcbot

Out of memory

Use the minimal image (Dockerfile.minimal) with Lightpanda — it uses 9x less RAM than Chrome/Playwright. Add swap on low-memory servers:

fallocate -l 2G /swapfile && chmod 600 /swapfile
mkswap /swapfile && swapon /swapfile

Reset everything

# Stop containers and delete all data
docker compose down -v

# Remove image to force full rebuild
docker rmi orcbot-orcbot

Production Tips

Secrets

Never commit .env files. Use Docker secrets or a secrets manager in production.

Restart Policy

restart: unless-stopped is set by default — containers auto-restart after crashes or reboots.

Monitoring

Use docker stats orcbot for real-time resource usage. Health checks are built into both Dockerfiles.