Mastering Your Homelab: An Introduction to Beszel

henrygd/beszel

From a software engineer's perspective, Beszel is great because it gives you a quick, at-a-glance view of your server's health and performance. It's not as complex as a full-blown enterprise monitoring solution, but that's its strength—it's fast, efficient, and easy to set up.

Here's how it helps

Real-time & Historical Data
You can see CPU, memory, disk, and network usage in real time. The historical data allows you to track trends and troubleshoot issues that might have occurred in the past. If a server suddenly became slow yesterday, you can check Beszel's history to see if there was a sudden spike in resource usage.

Docker Stats
This is a big one for modern development. Beszel can monitor your Docker containers, showing you their resource usage individually. This is incredibly helpful for identifying a runaway container that's consuming too much memory or CPU.

Alerts
You can set up alerts to get notified when something goes wrong, like a server running out of disk space or a container using too much CPU. This proactive monitoring helps you catch problems before they become critical.

Lightweight & Self-Hosted
Being lightweight means it won't hog resources on the very servers you're trying to monitor. And since it's self-hosted, you maintain full control over your data.

The easiest and recommended way to install Beszel is by using Docker. This method handles all the dependencies and makes the setup process very straightforward.

Prerequisites
Make sure you have Docker and Docker Compose installed on your server.

Create a Directory
First, create a new directory for Beszel on your server.

mkdir beszel
cd beszel

Create the Docker Compose file
Create a file named docker-compose.yml and paste the following content into it. This file tells Docker how to set up the Beszel service.

version: "3"
services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    ports:
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./data:/app/data
    restart: unless-stopped
    environment:
      - [email protected]
      - [email protected]
      - BESZEL_SMTP_HOST=smtp.example.com
      - [email protected]
      - BESZEL_SMTP_PASSWORD=your-email-password

Launch Beszel
Once you've saved the file, simply run the following command in the same directory.

docker-compose up -d

This command downloads the Beszel image and starts the container in the background.

Access the Dashboard
After a minute or two, Beszel should be running. You can access the dashboard by navigating to http://<your-server-ip>:8080 in your web browser.

Beszel has a simple REST API that you can use to interact with your monitoring data programmatically. This is great for automating tasks or integrating with other tools.

Here’s an example using Python to fetch server stats. You can use this to create custom scripts or dashboards.

import requests
import json

# Replace with your Beszel server's IP address and port
BESZEL_URL = "http://<your-server-ip>:8080/api/v1/stats"

def get_server_stats():
    """
    Fetches and prints the latest server statistics from Beszel.
    """
    try:
        response = requests.get(BESZEL_URL)
        response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)

        stats = response.json()
        print("--- Beszel Server Stats ---")
        
        # CPU
        cpu_usage = stats.get('cpu_usage')
        print(f"CPU Usage: {cpu_usage:.2f}%")

        # Memory
        mem_info = stats.get('memory_info', {})
        total_mem = mem_info.get('total', 0)
        used_mem = mem_info.get('used', 0)
        print(f"Memory Usage: {used_mem / (1024**3):.2f} GB / {total_mem / (1024**3):.2f} GB")

        # Docker Containers
        print("\n--- Docker Containers ---")
        docker_stats = stats.get('docker_stats', [])
        for container in docker_stats:
            name = container.get('name')
            cpu_percent = container.get('cpu_percent')
            mem_usage = container.get('memory_usage')
            print(f"- {name}: CPU {cpu_percent:.2f}%, Memory {mem_usage / (1024**2):.2f} MB")

    except requests.exceptions.RequestException as e:
        print(f"Error fetching data from Beszel: {e}")

if __name__ == "__main__":
    get_server_stats()

This simple script shows how you can programmatically pull data from Beszel. You could extend this to log data to a database, send custom alerts via a messaging app, or build a personalized dashboard.