botserver/docs/guides/deployment.md

Deployment Guide

Deploy General Bots in production environments with security, scalability, and reliability.

Deployment Options

Method	Best For	Complexity
Single Server	Small teams, development	Low
Docker Compose	Medium deployments	Medium
LXC Containers	Isolated multi-tenant	Medium
Kubernetes	Large scale, high availability	High

Single Server Deployment

Requirements

• CPU: 4+ cores
• RAM: 16GB minimum
• Disk: 100GB SSD
• OS: Ubuntu 22.04 LTS / Debian 12

Installation

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Clone and build
git clone https://github.com/GeneralBots/BotServer
cd BotServer
cargo build --release

# Run as service
sudo cp target/release/botserver /usr/local/bin/
sudo cp scripts/botserver.service /etc/systemd/system/
sudo systemctl enable botserver
sudo systemctl start botserver

Systemd Service

# /etc/systemd/system/botserver.service
[Unit]
Description=General Bots Server
After=network.target postgresql.service

[Service]
Type=simple
User=botserver
Group=botserver
WorkingDirectory=/opt/botserver
ExecStart=/usr/local/bin/botserver --noconsole
Restart=always
RestartSec=5
Environment=RUST_LOG=info

[Install]
WantedBy=multi-user.target

Docker Deployment

Docker Compose

# docker-compose.yml
version: '3.8'

services:
  botserver:
    image: generalbots/botserver:latest
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgres://bot:password@postgres/botserver
      - REDIS_URL=redis://redis:6379
      - S3_ENDPOINT=http://minio:9000
    depends_on:
      - postgres
      - redis
      - minio
    volumes:
      - ./templates:/app/templates
      - ./data:/app/data
    restart: unless-stopped

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=bot
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=botserver
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped

  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    environment:
      - MINIO_ROOT_USER=minioadmin
      - MINIO_ROOT_PASSWORD=minioadmin
    volumes:
      - minio_data:/data
    ports:
      - "9001:9001"
    restart: unless-stopped

  qdrant:
    image: qdrant/qdrant
    volumes:
      - qdrant_data:/qdrant/storage
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:
  minio_data:
  qdrant_data:

Start Services

docker-compose up -d
docker-compose logs -f botserver

LXC Container Deployment

LXC provides lightweight isolation for multi-tenant deployments.

Create Container

# Create container
lxc launch ubuntu:22.04 botserver

# Configure resources
lxc config set botserver limits.cpu 4
lxc config set botserver limits.memory 8GB

# Enter container
lxc exec botserver -- bash

Inside Container

# Install dependencies
apt update && apt install -y curl build-essential

# Install Rust and build
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
git clone https://github.com/GeneralBots/BotServer
cd BotServer
cargo build --release

# Run
./target/release/botserver --container

Container Networking

# Forward port from host
lxc config device add botserver http proxy \
  listen=tcp:0.0.0.0:8080 \
  connect=tcp:127.0.0.1:8080

Reverse Proxy Setup

Nginx

# /etc/nginx/sites-available/botserver
upstream botserver {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 80;
    server_name bot.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name bot.example.com;

    ssl_certificate /etc/letsencrypt/live/bot.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/bot.example.com/privkey.pem;

    # Security headers
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";

    location / {
        proxy_pass http://botserver;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket support
    location /ws {
        proxy_pass http://botserver;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }
}

Enable Site

sudo ln -s /etc/nginx/sites-available/botserver /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

SSL Certificates

Let's Encrypt

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d bot.example.com

Auto-Renewal

sudo certbot renew --dry-run

Environment Configuration

Production Environment

# /opt/botserver/.env
RUST_LOG=warn,botserver=info

# Directory Service (required)
DIRECTORY_URL=https://auth.example.com
DIRECTORY_CLIENT_ID=your-client-id
DIRECTORY_CLIENT_SECRET=your-secret

# Optional overrides
DATABASE_URL=postgres://user:pass@localhost/botserver
REDIS_URL=redis://localhost:6379
S3_ENDPOINT=https://s3.example.com

# Rate limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_API_RPS=100

Database Setup

PostgreSQL Production Config

-- Create database and user
CREATE USER botserver WITH PASSWORD 'secure_password';
CREATE DATABASE botserver OWNER botserver;
GRANT ALL PRIVILEGES ON DATABASE botserver TO botserver;

-- Enable extensions
\c botserver
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pg_trgm";

Connection Pooling (PgBouncer)

# /etc/pgbouncer/pgbouncer.ini
[databases]
botserver = host=localhost dbname=botserver

[pgbouncer]
listen_addr = 127.0.0.1
listen_port = 6432
auth_type = md5
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 20

Monitoring

Health Check Endpoint

curl http://localhost:8080/api/health

Prometheus Metrics

# prometheus.yml
scrape_configs:
  - job_name: 'botserver'
    static_configs:
      - targets: ['localhost:8080']
    metrics_path: /metrics

Log Aggregation

# Stream logs to file
journalctl -u botserver -f >> /var/log/botserver/app.log

# Logrotate config
# /etc/logrotate.d/botserver
/var/log/botserver/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
}

Backup Strategy

Database Backup

#!/bin/bash
# /opt/botserver/scripts/backup.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=/backups/botserver

# PostgreSQL
pg_dump -U botserver botserver | gzip > $BACKUP_DIR/db_$DATE.sql.gz

# File storage
tar -czf $BACKUP_DIR/files_$DATE.tar.gz /opt/botserver/data

# Retain 30 days
find $BACKUP_DIR -mtime +30 -delete

Cron Schedule

# Daily backup at 2 AM
0 2 * * * /opt/botserver/scripts/backup.sh

Security Checklist

• Run as non-root user
• Enable firewall (only ports 80, 443)
• Configure SSL/TLS
• Set secure file permissions
• Enable rate limiting
• Configure authentication
• Regular security updates
• Audit logging enabled
• Backup encryption
• Network isolation for database

Scaling

Horizontal Scaling

# docker-compose.scale.yml
services:
  botserver:
    deploy:
      replicas: 3
    
  nginx:
    image: nginx
    ports:
      - "80:80"
    volumes:
      - ./nginx-lb.conf:/etc/nginx/nginx.conf

Load Balancer Config

upstream botserver_cluster {
    least_conn;
    server botserver1:8080;
    server botserver2:8080;
    server botserver3:8080;
}

Troubleshooting

Check Service Status

sudo systemctl status botserver
journalctl -u botserver -n 100

Database Connection Issues

psql -U botserver -h localhost -d botserver -c "SELECT 1"

Memory Issues

# Check memory usage
free -h
cat /proc/meminfo | grep -E "MemTotal|MemFree|Cached"

# Increase swap if needed
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Updates

Rolling Update

# Build new version
cd /opt/botserver
git pull
cargo build --release

# Graceful restart
sudo systemctl reload botserver

Zero-Downtime with Docker

docker-compose pull
docker-compose up -d --no-deps --build botserver