Beszel: Lightweight Server Monitoring Made Simple

Monitoring your home server doesn’t need to be complicated. While tools like Prometheus and Grafana offer powerful features, they can be overkill for smaller setups. Enter Beszel—a lightweight, modern server monitoring solution designed specifically for self-hosters who want simplicity without sacrificing functionality.

What is Beszel?

Beszel is a minimalist server monitoring platform that provides real-time metrics for your infrastructure. Built with Go and featuring a clean web interface, it tracks essential system metrics like CPU usage, memory, disk space, and network activity across multiple servers.

Why Choose Beszel?

Lightweight Resource Usage
Beszel consumes minimal resources—typically under 50MB of RAM per monitored server. Perfect for Raspberry Pis and older hardware.

Modern Interface
Unlike dated monitoring tools, Beszel features a responsive, mobile-friendly dashboard that looks professional without requiring customization.

Easy Setup
No complex configuration files or database setup required. Docker deployment takes minutes, and adding new servers is straightforward.

Multi-Server Support
Monitor your entire home lab from one dashboard—track your main server, NAS, Raspberry Pi, and VPS simultaneously.

Open Source
Licensed under MIT, Beszel is completely free and community-driven. Review the code, contribute improvements, or self-host with confidence.

Requirements

Before you begin, ensure you have:

• A server running Docker and Docker Compose
• At least 100MB of free disk space
• Port 8090 available (customizable)
• Basic command line knowledge

Installing Beszel

Step 1: Create Docker Compose File

Create a directory for Beszel and navigate to it:

mkdir -p ~/beszel
cd ~/beszel

Create docker-compose.yml:

version: '3.8'

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    ports:
      - "8090:8090"
    volumes:
      - ./data:/beszel/data
    environment:
      - TZ=America/New_York  # Set your timezone

Step 2: Start Beszel

Launch the container:

docker-compose up -d

Verify it’s running:

docker ps | grep beszel

Step 3: Access the Dashboard

Open your browser and navigate to:

You’ll be greeted with the initial setup wizard.

Step 4: Create Admin Account

On first access, create your admin credentials:

• Username: Choose a secure username
• Password: Use a strong password (store it in your password manager!)

Click “Create Account” to complete setup.

Adding Servers to Monitor

Beszel uses lightweight agents to collect metrics from each server.

Install Agent on Linux Server

SSH into the server you want to monitor and run:

curl -sL https://github.com/henrygd/beszel/releases/latest/download/install-agent.sh | bash

The script will:

1. Download the Beszel agent binary
2. Create a systemd service
3. Start the agent automatically

Configure Agent

Edit the agent configuration:

sudo nano /etc/beszel/agent.conf

Set your hub URL:

HUB_URL=http://YOUR_BESZEL_SERVER_IP:8090

Restart the agent:

sudo systemctl restart beszel-agent

Add Server in Dashboard

1. Return to the Beszel web dashboard
2. Click “Add Server”
3. Enter a name (e.g., “Main Server” or “NAS”)
4. The agent will automatically connect
5. Click “Save”

Within seconds, you’ll see live metrics appear.

Understanding the Dashboard

System Overview

The main dashboard displays:

• CPU Usage: Real-time processor load percentage
• Memory: RAM usage and available memory
• Disk Space: Storage usage per partition
• Network: Upload/download speeds and traffic

Historical Data

Click any server card to view:

• Graphs showing trends over 1 hour, 24 hours, or 7 days
• Peak usage times
• Resource bottlenecks

Alerts (Optional)

Configure notifications for critical events:

1. Go to Settings → Alerts
2. Set thresholds (e.g., CPU > 90% for 5 minutes)
3. Add notification webhook (compatible with Discord, Slack, ntfy)

Docker Container Monitoring

Beszel can track Docker containers running on your servers.

Enable Docker monitoring in the agent config:

sudo nano /etc/beszel/agent.conf

Add:

DOCKER_ENABLED=true

Restart the agent:

sudo systemctl restart beszel-agent

The dashboard will now show:

• Container CPU and memory usage
• Container status (running/stopped)
• Quick restart buttons

Advanced Configuration

Reverse Proxy with Nginx

Secure Beszel behind a domain with HTTPS:

server {
    listen 443 ssl http2;
    server_name beszel.yourdomain.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://localhost:8090;
        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
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Custom Metrics

Beszel supports custom metrics via environment variables in the agent:

CUSTOM_METRIC_1=temperature:/sys/class/thermal/thermal_zone0/temp

This adds server temperature to your dashboard.

Authentication with Authentik

Integrate Beszel with your SSO solution:

1. Create an OAuth2 provider in Authentik
2. Note the Client ID and Secret
3. Add to Beszel’s docker-compose.yml:

environment:
  - OAUTH_CLIENT_ID=your_client_id
  - OAUTH_CLIENT_SECRET=your_secret
  - OAUTH_ISSUER_URL=https://authentik.yourdomain.com/application/o/beszel/

Comparing Beszel to Alternatives

When to use Beszel:

• You want quick setup without configuration complexity
• You’re monitoring 2-10 servers in a home lab
• You prefer lightweight resource usage
• You don’t need advanced alerting workflows

When to use alternatives:

• Netdata: You want extreme detail and built-in anomaly detection
• Grafana: You need custom dashboards and complex metrics
• Uptime Kuma: You only care about service availability, not system metrics

Troubleshooting

Agent Not Connecting

Check agent status:

sudo systemctl status beszel-agent

View logs:

sudo journalctl -u beszel-agent -f

Common fixes:

• Verify HUB_URL is correct in agent config
• Ensure port 8090 isn’t blocked by firewall
• Check server and agent are on the same network (or open ports)

Missing Docker Stats

Grant agent access to Docker socket:

sudo usermod -aG docker beszel
sudo systemctl restart beszel-agent

High Memory Usage

If Beszel’s database grows large:

cd ~/beszel
docker-compose down
sqlite3 data/beszel.db "VACUUM;"
docker-compose up -d

Security Best Practices

1. Use HTTPS: Always run Beszel behind a reverse proxy with SSL
2. Strong Passwords: Enable two-factor auth if using OAuth
3. Network Isolation: Consider running Beszel on a dedicated monitoring VLAN
4. Regular Updates: Keep Beszel and agents up to date:

docker-compose pull
docker-compose up -d

5. Firewall Rules: Only expose port 8090 to trusted networks

Backup and Restore

Backup Configuration

Create a backup script:

#!/bin/bash
tar -czf beszel-backup-$(date +%Y%m%d).tar.gz ~/beszel/data

Run via cron weekly:

0 2 * * 0 /home/user/backup-beszel.sh

Restore

cd ~/beszel
docker-compose down
tar -xzf beszel-backup-YYYYMMDD.tar.gz
docker-compose up -d

Conclusion

Beszel strikes the perfect balance between simplicity and functionality for home server monitoring. In just minutes, you can deploy a professional monitoring dashboard that tracks your entire infrastructure without the bloat of enterprise solutions.

Whether you’re running a single Raspberry Pi or managing a multi-server home lab, Beszel provides the visibility you need without overwhelming you with complexity.

Next Steps:

• Set up alerting for critical thresholds
• Add all your servers to centralized monitoring
• Integrate with Uptime Kuma for service checks
• Configure a reverse proxy for secure remote access

Happy monitoring! 🖥️📊