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_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
On first start the server auto-creates an admin account with a randomly generated password. Open the Railway deploy logs and look for the highlighted credentials banner to retrieve it. On first login you are required to change this password and may optionally choose a different username.

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

Bootstrap Installer

For Linux hosts, the quickest binary/systemd path is the bootstrap installer:

# Install the server
curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s -- server

# Install an agent
curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s -- agent \
  --server-url http://your-server-ip:9527 \
  --enrollment-code YOUR_ONE_TIME_CODE

After installation, manage your deployment with the serverbee CLI (automatically installed to /usr/local/bin/serverbee):

sudo serverbee status
sudo serverbee upgrade -y
sudo serverbee restart
sudo serverbee config
sudo serverbee env
sudo serverbee uninstall agent -y

install server / install agent are bootstrap commands. If the binary already exists in /usr/local/bin, the installer adopts it instead of overwriting it. Use upgrade (or replace the binary manually) when you need to roll out a refreshed release binary to an existing host.

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_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

Build from Source

For developers or users with customization needs, you can build ServerBee from source. Building requires Rust 1.85+ and Bun 1.x (or Node.js 22+).

# Clone the repo
git clone https://github.com/ZingerLittleBee/ServerBee.git
cd ServerBee

# Build the frontend
cd apps/web
bun install
bun run build
cd ../..

# Build the server (embeds the frontend via rust-embed)
cargo build --release -p serverbee-server

# Build the agent
cargo build --release -p serverbee-agent

The binaries will be located in target/release/:

serverbee-server — the server, with the frontend assets embedded
serverbee-agent — the metrics agent

Start the server:

./target/release/serverbee-server

Once you have deployed the compiled binaries to the target host, use the systemd service configuration below to manage the processes.

Systemd Services

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

If you do not need hand-written unit files, prefer the bootstrap installer above. It creates the config files and systemd units for you, then the serverbee CLI handles upgrades, restarts, and config edits.

Note: the unit examples below use custom paths (/usr/local/bin, /var/lib/serverbee, /etc/serverbee) to illustrate a manual deployment. The bootstrap installer uses a different layout — binaries in /opt/serverbee/bin/, config in /opt/serverbee/etc/, data in /opt/serverbee/data/ — managed by the serverbee CLI, with no hand-written units.

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"

[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.

Choose one public access URL and keep the browser URL, agent server_url, and cookie setting aligned:

Scenario	Public URL	`auth.secure_cookie`	Docker Environment Variable	Agent URL
Direct IP over HTTP	`http://203.0.113.10:9527`	`false`	`SERVERBEE_AUTH__SECURE_COOKIE=false`	`http://203.0.113.10:9527`
Domain through HTTPS reverse proxy	`https://monitor.example.com`	`true`	`SERVERBEE_AUTH__SECURE_COOKIE=true` or omit the variable	`https://monitor.example.com`

For domain access, create a DNS A or AAAA record pointing to the server, terminate HTTPS in Nginx, Caddy, or Traefik, and proxy traffic to ServerBee on 127.0.0.1:9527.

If you installed with the quick-start script, it writes auth.secure_cookie = false for direct HTTP access. Before switching that same installation to HTTPS, update /opt/serverbee/etc/server.toml:

[auth]
secure_cookie = true

Then restart the server:

sudo systemctl restart serverbee-server

If ServerBee was installed with the install script, you can also let the CLI configure Caddy HTTPS automatically:

sudo serverbee domain setup --domain monitor.example.com --email admin@example.com -y

This command verifies that the domain resolves to the current server, installs and configures Caddy, changes ServerBee to listen only on 127.0.0.1:9527, and sets auth.secure_cookie = true. If DNS is not ready yet, it stops and prints the A/AAAA record you need to add.

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
    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.

Manual Certificates

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, keep auth.secure_cookie = true in your server configuration. Leaving it false may still allow login, but it removes the browser's Secure cookie protection and is not appropriate for production.

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	`/opt/serverbee/etc/server.toml`	Server configuration (install-script default)
Agent configs	`/opt/serverbee/etc/agent.toml`	Agent configuration (on each monitored server)
GeoIP database	Varies	MaxMind MMDB file (if used)

Backup Strategy

The install-script default data directory is /opt/serverbee/data (database at /opt/serverbee/data/serverbee.db). For a custom hand-written systemd deployment, substitute the data_dir you configured.

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

sqlite3 /opt/serverbee/data/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 /opt/serverbee/data/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 /opt/serverbee/data/serverbee.db
# Custom hardened deploys that run as a dedicated user: also re-apply ownership, e.g.
# sudo chown serverbee:serverbee /opt/serverbee/data/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 /opt/serverbee/data/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