ServerBee Docs

This guide covers production deployment best practices for ServerBee, including Railway, Docker, systemd, reverse proxy configuration, TLS, and backup strategies.

Railway (One-Click Deploy)

The fastest way to get ServerBee running. Click the button above and configure the environment variables:

SERVERBEE_ADMIN__USERNAME="admin"              # Admin username (auto-generated if empty, check logs)
SERVERBEE_ADMIN__PASSWORD=""                   # Admin password (auto-generated if empty, check logs)
SERVERBEE_AUTH__AUTO_DISCOVERY_KEY=""           # Agent auto-registration key (auto-generated if empty, check logs)

SERVERBEE_LOG__LEVEL="info"                    # Log level (trace/debug/info/warn/error)

SERVERBEE_RETENTION__RECORDS_DAYS="7"          # Raw metrics retention in days
SERVERBEE_RETENTION__RECORDS_HOURLY_DAYS="90"  # Hourly aggregates retention in days
SERVERBEE_RETENTION__AUDIT_LOGS_DAYS="180"     # Audit log retention in days
SERVERBEE_SCHEDULER__TIMEZONE="UTC"            # Timezone for daily traffic aggregation (e.g. Asia/Shanghai)

SERVERBEE_OAUTH__BASE_URL=""                   # OAuth callback URL (e.g. https://xxx.up.railway.app)
SERVERBEE_OAUTH__GITHUB__CLIENT_ID=""          # GitHub OAuth Client ID
SERVERBEE_OAUTH__GITHUB__CLIENT_SECRET=""      # GitHub OAuth Client Secret
SERVERBEE_OAUTH__ALLOW_REGISTRATION="false"    # Auto-create accounts on first OAuth login (true=open, false=linked only)

After deploying:

Add a Volume mounted at /data to persist data across deploys
Configure your agents to connect using the Railway-provided URL

Railway automatically assigns a port and provides HTTPS. No need to configure SERVERBEE_SERVER__LISTEN or TLS certificates.

Docker Compose (Recommended)

Docker Compose is the simplest way to deploy ServerBee in production. Create a docker-compose.yml:

services:
  serverbee-server:
    image: ghcr.io/zingerlittlebee/serverbee-server:latest
    container_name: serverbee-server
    restart: unless-stopped
    ports:
      - "127.0.0.1:9527:9527"
    volumes:
      - serverbee-data:/data
      - ./server.toml:/app/server.toml:ro
    environment:
      - SERVERBEE_ADMIN__PASSWORD=change-this-password
      - SERVERBEE_AUTH__SECURE_COOKIE=true
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:9527/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

volumes:
  serverbee-data:

Binding to 127.0.0.1:9527 instead of 0.0.0.0:9527 ensures the server is only accessible through the reverse proxy, not directly from the internet.

Start the service:

docker compose up -d

View logs:

docker compose logs -f serverbee-server

Systemd Services

For deployments without Docker, use systemd to manage both the server and agent processes.

Server Service

Create /etc/systemd/system/serverbee-server.service:

[Unit]
Description=ServerBee Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/serverbee-server
Restart=always
RestartSec=5
User=serverbee
Group=serverbee
WorkingDirectory=/var/lib/serverbee

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/serverbee /var/log/serverbee
PrivateTmp=true

# Resource limits
MemoryMax=512M

[Install]
WantedBy=multi-user.target

Create the service user and directories:

# Create system user
sudo useradd -r -s /sbin/nologin -d /var/lib/serverbee serverbee

# Create directories
sudo mkdir -p /var/lib/serverbee /var/log/serverbee /etc/serverbee
sudo chown serverbee:serverbee /var/lib/serverbee /var/log/serverbee

# Place configuration
sudo cp server.toml /etc/serverbee/server.toml

# Place binary
sudo cp serverbee-server /usr/local/bin/
sudo chmod +x /usr/local/bin/serverbee-server

A production server.toml for systemd:

[server]
listen = "127.0.0.1:9527"
data_dir = "/var/lib/serverbee"

[admin]
password = "change-this-immediately"

[log]
level = "info"
file = "/var/log/serverbee/server.log"

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable serverbee-server
sudo systemctl start serverbee-server
sudo systemctl status serverbee-server

Agent Service

See the Agent Setup guide for a complete systemd service unit file.

Reverse Proxy

Running ServerBee behind a reverse proxy is strongly recommended for production. It provides TLS termination, HTTP/2, and additional security headers.

Nginx

upstream serverbee {
    server 127.0.0.1:9527;
}

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

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

    ssl_certificate     /etc/letsencrypt/live/monitor.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/monitor.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    location / {
        proxy_pass http://serverbee;
        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 (required for agents, browser updates, and terminal)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Long timeouts for persistent WebSocket connections
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;

        # Disable buffering for real-time data
        proxy_buffering off;
    }
}

Caddy

Caddy handles TLS automatically with Let's Encrypt:

monitor.example.com {
    reverse_proxy 127.0.0.1:9527 {
        # WebSocket support is automatic in Caddy
    }
}

That is the entire Caddy configuration needed. Caddy handles HTTPS certificates, HTTP/2, WebSocket upgrades, and security headers by default.

Traefik

Traefik integrates with Docker via labels — no separate config file needed. Traefik automatically detects WebSocket connections, so no extra configuration is required.

services:
  serverbee-server:
    image: ghcr.io/zingerlittlebee/serverbee-server:latest
    volumes:
      - serverbee-data:/data
    environment:
      - SERVERBEE_ADMIN__PASSWORD=your_secure_password
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.serverbee.rule=Host(`monitor.example.com`)"
      - "traefik.http.routers.serverbee.entrypoints=websecure"
      - "traefik.http.routers.serverbee.tls.certresolver=letsencrypt"
      - "traefik.http.services.serverbee.loadbalancer.server.port=9527"
    restart: unless-stopped
    networks:
      - traefik

networks:
  traefik:
    external: true

volumes:
  serverbee-data:

TLS / HTTPS

For production deployments, always use HTTPS. The recommended approaches:

Let's Encrypt with Certbot (Nginx)

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

Certbot will automatically configure nginx and set up certificate renewal.

Let's Encrypt with Caddy

Caddy obtains and renews certificates automatically. No additional setup is needed.

If you have your own certificates, place them in a secure directory and reference them in your reverse proxy configuration. Ensure the certificate files are readable by the proxy process and that you have a renewal process in place.

Agent Configuration for HTTPS

When your server is behind HTTPS, update the agent's server_url accordingly:

server_url = "https://monitor.example.com"

The agent automatically handles WebSocket connections using the provided URL.

When using HTTPS, ensure auth.secure_cookie = true in your server configuration (this is the default). If you set it to false, session cookies will not be sent over HTTPS connections, breaking browser authentication.

Backup and Restore

What to Back Up

ServerBee stores all data in a single SQLite database file and the configuration files:

Item	Location	Description
Database	`{data_dir}/serverbee.db`	All monitoring data, users, alerts, and settings
WAL file	`{data_dir}/serverbee.db-wal`	Write-ahead log (include if backing up while running)
SHM file	`{data_dir}/serverbee.db-shm`	Shared memory file (include if backing up while running)
Server config	`/etc/serverbee/server.toml`	Server configuration
Agent configs	`/etc/serverbee/agent.toml`	Agent configuration (on each monitored server)
GeoIP database	Varies	MaxMind MMDB file (if used)

Backup Strategy

Option 1: SQLite backup command (recommended for running server)

sqlite3 /var/lib/serverbee/serverbee.db ".backup '/backups/serverbee-$(date +%Y%m%d).db'"

This creates a consistent point-in-time backup without stopping the server.

Option 2: File copy (requires stopping the server)

sudo systemctl stop serverbee-server
cp /var/lib/serverbee/serverbee.db /backups/serverbee-$(date +%Y%m%d).db
sudo systemctl start serverbee-server

Option 3: Docker volume backup

docker compose stop
docker run --rm \
  -v serverbee-data:/data \
  -v $(pwd)/backups:/backups \
  alpine tar czf /backups/serverbee-$(date +%Y%m%d).tar.gz -C /data .
docker compose start

Restore

To restore from a backup:

Stop the server
Replace the database file with the backup
Start the server (migrations will run automatically if needed)

sudo systemctl stop serverbee-server
cp /backups/serverbee-20260314.db /var/lib/serverbee/serverbee.db
sudo chown serverbee:serverbee /var/lib/serverbee/serverbee.db
sudo systemctl start serverbee-server

Automated Backups

Set up a cron job for daily backups:

# /etc/cron.d/serverbee-backup
0 2 * * * root sqlite3 /var/lib/serverbee/serverbee.db ".backup '/backups/serverbee-$(date +\%Y\%m\%d).db'" && find /backups -name 'serverbee-*.db' -mtime +30 -delete

This runs at 2:00 AM daily and deletes backups older than 30 days.

Health Checks

ServerBee exposes a health check endpoint:

GET /healthz

Use this to verify the server is running and responsive. Configure it in your monitoring system, Docker health check, or load balancer.

Docker Health Check

The Docker Compose example above includes a health check configuration. Docker will automatically restart the container if the health check fails 3 consecutive times.

External Monitoring

If you are using an external uptime monitoring service, point it at:

https://monitor.example.com/healthz

This creates a "monitor the monitor" setup, so you know if ServerBee itself goes down.

Resource Requirements

ServerBee is designed for lightweight VPS instances:

Component	Minimum	Recommended
Server CPU	1 vCPU	2 vCPU
Server RAM	128 MB	256 MB
Server Disk	100 MB + data	1 GB+ (depends on retention)
Agent CPU	Negligible	< 1% of 1 core
Agent RAM	10 MB	20 MB

Database size depends on the number of monitored servers and retention settings. As a rough guide, expect about 1 MB per server per day of raw records. With 50 servers and default 7-day retention, the database will be approximately 350 MB.

Security Checklist

Before exposing ServerBee to the internet:

Deployment Guide