Beszel Deployment and Usage Guide

1. Prerequisites

Required Software

Go 1.21+ - The project is written in Go and requires the Go toolchain
Docker (optional) - For containerized deployment and Docker stats monitoring
Git - For cloning the repository
SSH - For remote system monitoring via SSH

System Requirements

Linux, macOS, or Windows (with WSL2 recommended for Windows)
For GPU monitoring: NVIDIA drivers with nvidia-smi or AMD ROCm with rocm-smi
For SMART monitoring: smartctl (smartmontools) - automatically downloaded for Windows
For Docker stats: Docker Engine API access

Accounts

No external API keys required
Optional: Domain name for production deployment

2. Installation

Clone the Repository

git clone https://github.com/henrygd/beszel.git
cd beszel

Install Dependencies

# Install Go dependencies
go mod download

# Install frontend dependencies (if building from source)
npm install  # or pnpm install or yarn install

Build the Agent (Optional)

The agent is pre-built for most platforms, but you can build it yourself:

# Build the agent for your current platform
go build -o beszel-agent ./cmd/agent

# Build for specific platforms
GOOS=linux GOARCH=amd64 go build -o beszel-agent-linux-amd64 ./cmd/agent
GOOS=darwin GOARCH=arm64 go build -o beszel-agent-darwin-arm64 ./cmd/agent

3. Configuration

Environment Variables

Hub (Server) Configuration

# Required
BESZEL_PORT=8080                    # Port for the web interface
BESZEL_AGENT_PORT=8081             # Port for agent connections

# Optional
BESZEL_DB_PATH=./beszel_data       # Path for PocketBase database
BESZEL_LOG_LEVEL=info              # Log level: debug, info, warn, error
BESZEL_DOMAIN=monitor.example.com  # Domain for production
BESZEL_SSL_CERT=/path/to/cert.pem  # SSL certificate path
BESZEL_SSL_KEY=/path/to/key.pem    # SSL key path

Agent Configuration

# Required for SSH mode
BESZEL_SSH_HOST=your-server.com    # Remote host to monitor
BESZEL_SSH_PORT=22                 # SSH port (default: 22)
BESZEL_SSH_USER=username           # SSH username
BESZEL_SSH_KEY_PATH=/path/to/key   # SSH private key path

# Optional
BESZEL_AGENT_INTERVAL=10           # Data collection interval in seconds
BESZEL_DOCKER_SOCK=/var/run/docker.sock  # Docker socket path
BESZEL_GPU_MONITORING=true         # Enable GPU monitoring
BESZEL_SMART_MONITORING=true       # Enable SMART disk monitoring

SSH Key Setup

Generate an SSH key pair if you don't have one:
```
ssh-keygen -t ed25519 -f ~/.ssh/beszel_agent
```

Copy the public key to the remote server:

ssh-copy-id -i ~/.ssh/beszel_agent.pub user@your-server.com

Set the environment variable:

export BESZEL_SSH_KEY_PATH=~/.ssh/beszel_agent

Docker Permissions

If monitoring Docker containers, ensure the agent has access to the Docker socket:

# Add user to docker group (Linux)
sudo usermod -aG docker $USER

# Or run with appropriate permissions
sudo BESZEL_DOCKER_SOCK=/var/run/docker.sock ./beszel-agent

4. Build & Run

Development Mode

Start the Hub (Development)

# From the project root
go run ./cmd/hub

# Or with custom port
BESZEL_PORT=3000 go run ./cmd/hub

Start the Agent (Development)

# Connect via SSH to a remote system
go run ./cmd/agent --ssh-host your-server.com --ssh-user username

# Or monitor local system
go run ./cmd/agent --local

Production Build

Build Both Components

# Build hub
go build -ldflags="-s -w" -o beszel-hub ./cmd/hub

# Build agent
go build -ldflags="-s -w" -o beszel-agent ./cmd/agent

Run Production Build

# Start hub
./beszel-hub

# Start agent (connect to hub)
./beszel-agent --hub-url http://localhost:8081 --token YOUR_TOKEN

# Or use SSH mode
./beszel-agent --ssh-host server.example.com --ssh-user admin

Docker Deployment

Using Docker Compose

Create a docker-compose.yml:

version: '3.8'

services:
  beszel-hub:
    image: ghcr.io/henrygd/beszel:latest
    container_name: beszel-hub
    ports:
      - "8080:8080"
      - "8081:8081"
    volumes:
      - ./beszel_data:/app/data
    environment:
      - BESZEL_PORT=8080
      - BESZEL_AGENT_PORT=8081
      - BESZEL_DB_PATH=/app/data
    restart: unless-stopped

  beszel-agent:
    image: ghcr.io/henrygd/beszel-agent:latest
    container_name: beszel-agent
    network_mode: host  # For local monitoring
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /:/host:ro
    environment:
      - BESZEL_HUB_URL=http://localhost:8081
      - BESZEL_AGENT_INTERVAL=10
    restart: unless-stopped
    depends_on:
      - beszel-hub

Run with:

docker-compose up -d

5. Deployment

Recommended Platforms

Self-Hosted (Recommended)

Docker - Simplest deployment with containerization
Bare Metal - Direct installation on Linux server
Kubernetes - For scalable deployments

Cloud Providers

AWS: EC2 for hub, agents on various instances
Google Cloud: Compute Engine with Cloud Storage for backups
Azure: Virtual Machines with Azure Database
DigitalOcean: Droplets with Spaces for storage

Deployment Steps

Set up the Hub:

# On your monitoring server
docker run -d \
  --name beszel-hub \
  -p 8080:8080 \
  -p 8081:8081 \
  -v /path/to/data:/app/data \
  -e BESZEL_DOMAIN=monitor.yourdomain.com \
  ghcr.io/henrygd/beszel:latest

Set up Reverse Proxy (Recommended):

# Nginx configuration
server {
    listen 80;
    server_name monitor.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Deploy Agents:

# On each monitored server
docker run -d \
  --name beszel-agent \
  --network host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /:/host:ro \
  -e BESZEL_HUB_URL=https://monitor.yourdomain.com:8081 \
  -e BESZEL_AGENT_INTERVAL=10 \
  ghcr.io/henrygd/beszel-agent:latest

Set up SSL (Let's Encrypt):

# Using certbot with Nginx
sudo certbot --nginx -d monitor.yourdomain.com

6. Troubleshooting

Common Issues

Agent Connection Issues

Problem: Agent cannot connect to hub Solution:

# Check network connectivity
curl http://hub-address:8081/health

# Verify ports are open
sudo netstat -tulpn | grep 8081

# Check firewall rules
sudo ufw allow 8081/tcp

SSH Authentication Failures

Problem: "Permission denied" when connecting via SSH Solution:

# Test SSH connection manually
ssh -i /path/to/key user@host

# Verify key permissions
chmod 600 ~/.ssh/beszel_agent

# Check SSH daemon configuration on remote host
sudo tail -f /var/log/auth.log

Docker Stats Not Showing

Problem: Docker containers not appearing in dashboard Solution:

# Check Docker socket permissions
ls -la /var/run/docker.sock

# Test Docker API access
curl --unix-socket /var/run/docker.sock http://localhost/containers/json

# Run agent with Docker group
docker run --group-add $(stat -c '%g' /var/run/docker.sock) ...

GPU Monitoring Not Working

Problem: GPU data not appearing Solution:

# Verify nvidia-smi works
nvidia-smi

# Check ROCm installation
rocm-smi

# For NVIDIA, ensure drivers are installed
nvidia-detector

# For AMD, ensure ROCm is installed
/opt/rocm/bin/rocm-smi

SMART Data Not Available

Problem: Disk health information missing Solution:

# Install smartmontools
sudo apt install smartmontools  # Debian/Ubuntu
sudo yum install smartmontools  # RHEL/CentOS

# Check disk detection
sudo smartctl --scan

# Test on specific device
sudo smartctl -a /dev/sda

High Memory Usage

Problem: Agent using too much memory Solution:

# Reduce collection interval
export BESZEL_AGENT_INTERVAL=30

# Disable unused features
export BESZEL_GPU_MONITORING=false
export BESZEL_SMART_MONITORING=false

# Limit Docker log collection
export BESZEL_DOCKER_LOG_LIMIT=100

WebSocket Connection Drops

Problem: Intermittent disconnections Solution:

# Increase timeout settings
export BESZEL_WS_TIMEOUT=60

# Check for network issues
ping hub-address

# Verify WebSocket endpoint
wscat -c ws://hub-address:8081/ws

Logs and Debugging

Enable Debug Logging

# For hub
BESZEL_LOG_LEVEL=debug ./beszel-hub

# For agent
BESZEL_LOG_LEVEL=debug ./beszel-agent --local

Check Container Logs

# Hub logs
docker logs beszel-hub

# Agent logs
docker logs beszel-agent

# Follow logs in real-time
docker logs -f beszel-hub

Database Issues

If PocketBase database has issues:

# Backup current data
cp -r ./beszel_data ./beszel_data_backup

# Reset database (warning: loses data)
rm -rf ./beszel_data/pb_data

Performance Optimization

Reduce Collection Frequency:

export BESZEL_AGENT_INTERVAL=30  # Collect every 30 seconds instead of 10

Disable Unused Features:

export BESZEL_GPU_MONITORING=false
export BESZEL_SMART_MONITORING=false
export BESZEL_DOCKER_LOGS=false

Limit Historical Data:

export BESZEL_RETENTION_DAYS=7  # Keep only 7 days of history

Use Lightweight Database:

export BESZEL_DB_MAX_CONNS=5  # Reduce database connections

Getting Help

Check the official documentation: https://beszel.dev/guide
Review source code on GitHub: https://github.com/henrygd/beszel
Enable debug logging for detailed error messages
Check system resource limits (ulimit -n)
Verify all required ports are accessible

For persistent issues, create an issue on GitHub with:

Log output with debug level enabled
Your configuration (without secrets)
OS and version information
Steps to reproduce the issue

How to Deploy & Use beszel