Beszel: Docker Monitoring That Won't Make You Cry

I tried Prometheus. I really tried. Two hours writing scrape rules, three hours configuring Grafana, then an all-nighter when alerts spammed my phone for no apparent reason.

Netdata? Pretty, but so much data I didn’t know what to look at. It was like drinking from a firehose — information everywhere, insight nowhere.

I just wanted to know: is my server about to crash? Are my containers running? Beszel answers these questions without making me wade through seven layers of YAML configuration.

What Is Beszel?

Beszel is an ultra-lightweight server monitoring platform built for humans. It tracks system usage, Docker metrics, and sends alerts when something breaks.

The difference? It’s simple. Actually simple. No esoteric configuration DSL. No 47 dashboards to create. Install, add your servers, done.

Beszel uses PocketBase under the hood — a lightweight, fast database. The result: a smooth, responsive web interface with instantly accessible historical data.

Why Not Prometheus/Grafana?

Don’t get me wrong — Prometheus/Grafana are powerful. But power ≠ relevance for a homelab.

Prometheus/Grafana:

Complex configuration (YAML everywhere)
Steep learning curve
Overkill for 3-4 servers
Heavy maintenance

Beszel:

5-minute setup
Intuitive interface
Perfect for homelab/small business
Near-zero maintenance

I keep Prometheus for work. For my homelab? Beszel is more than enough.

Key Features

System monitoring: CPU, RAM, disk, temperature, load average
Docker stats: CPU, memory, network per container (with history!)
Configurable alerts: Custom thresholds, multiple notifications
Multi-user: Users see their servers, admins see everything
OAuth/OIDC: Connect with Google, GitHub, Authelia, etc.
Auto backups: Export to local disk or S3

Architecture: Hub + Agents

Beszel works in two parts:

Hub: The web interface that centralizes data. One hub for all your servers.

Agents: Small programs running on each monitored server that send metrics to the hub.

Agents communicate via HTTP/HTTPS — no special ports needed. They use outbound connections, so even behind strict NAT, it works.

Docker Compose Installation

1. The Hub (Web Interface)

mkdir -p ~/beszel/hub
cd ~/beszel/hub

docker-compose.yml:

version: "3.8"

services:
  beszel-hub:
    image: henrygd/beszel:latest
    container_name: beszel-hub
    restart: unless-stopped
    ports:
      - "8090:8090"
    volumes:
      - ./data:/beszel_data
      - /etc/localtime:/etc/localtime:ro
    environment:
      - TZ=Europe/Paris
    networks:
      - beszel-network

networks:
  beszel-network:
    driver: bridge

docker-compose up -d

Access the hub at: http://localhost:8090

2. The Agents (On Each Server to Monitor)

mkdir -p ~/beszel-agent
cd ~/beszel-agent

docker-compose.yml:

version: "3.8"

services:
  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    environment:
      - TZ=Europe/Paris
      - KEY=your-hub-public-key
      - HOST=http://your-hub:8090
      - NAME=server-prod-01
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /etc/localtime:/etc/localtime:ro
    networks:
      - beszel-network

networks:
  beszel-network:
    driver: bridge

Important: The agent needs Docker socket access to monitor containers (/var/run/docker.sock).

Initial Setup

Go to http://your-hub:8090. Create an admin account.

2. Get the Public Key

In the interface: Settings → Add System. A public key is displayed. Copy it.

3. Configure the Agent

Paste the key in the agent’s KEY environment variable, then restart:

docker-compose up -d

4. Verify Connection

The agent should automatically appear in the hub interface under the name defined in NAME.

Alert Configuration

In the Beszel interface, click a system → Alerts.

You can set thresholds for:

CPU: “Alert if > 80% for 5 min”
Memory: “Alert if > 90%”
Disk: “Alert if < 10% free”
Bandwidth: “Alert if upload > 100 Mbps”
Temperature: “Alert if > 70°C”

Notifications go via email by default. You can also configure webhooks for Slack, Discord, or others.

Exploring Data

The Beszel interface is minimalist but powerful:

Global dashboard: Overview of all your systems
System view: Historical graphs (1h, 24h, 7d, 30d, 1y)
Docker stats: Individual container performance
Comparisons: Overlay metrics from multiple systems

What I especially love: historical Docker container graphs. Finally, I can see which container caused a memory spike at 3 AM yesterday.

OAuth and Authentication

Beszel supports native OAuth2/OIDC. Example with Authelia:

In the hub environment variables:

environment:
  - OIDC_ENABLED=true
  - OIDC_ISSUER=https://auth.yourdomain.com
  - OIDC_CLIENT_ID=beszel
  - OIDC_CLIENT_SECRET=your-secret
  - OIDC_SCOPES=openid email profile

Once configured, you can disable password auth:

environment:
  - DISABLE_PASSWORD_AUTH=true

Automatic Backups

Beszel can auto-backup its database:

environment:
  - BACKUP_ENABLED=true
  - BACKUP_INTERVAL=24h
  - BACKUP_RETENTION=7
  # Optional: backup to S3
  - S3_ENDPOINT=s3.amazonaws.com
  - S3_BUCKET=my-beszel-backups
  - S3_ACCESS_KEY=your-key
  - S3_SECRET_KEY=your-secret

Troubleshooting

Agent won’t connect

Verify the public key is correct
Ensure the hub is accessible from the agent (curl http://hub:8090)
Check logs: docker logs beszel-agent

No Docker data

Verify the Docker socket is properly mounted
Agent must be able to read /var/run/docker.sock

Slow interface

Beszel uses SQLite (PocketBase). For hundreds of systems, consider fast storage (SSD).

Benchmark: Beszel vs Alternatives

Aspect	Beszel	Netdata	Prometheus+Grafana
Setup	5 min	15 min	2-4 hours
Learning curve	Flat	Medium	Steep
Resources	Very light	Light	Heavy
Docker native	✅ Excellent	✅ Good	⚠️ Complex
Built-in alerts	✅	✅	⚠️ Needs Alertmanager
Long-term history	✅	✅ Paid	✅

Conclusion

Beszel is the monitoring tool I recommend to anyone starting self-hosting — and to many who continue.

It doesn’t do everything. It won’t replace an ELK stack for log analysis, or Prometheus for enterprise infrastructure monitoring. But for a homelab of 2-20 servers? It’s perfect.

Simple, fast, reliable. Three qualities rarely found together in the monitoring world.

Try it. You might uninstall Grafana next month.

Useful Links

Got Beszel running in your homelab? Show us your dashboards on Discord!