Beszel Lightweight Server Monitor: Docker Stats and Alerts Setup

Beszel is a lightweight monitoring solution designed for simplicity and efficiency. It tracks Docker container metrics, retains historical data, and triggers alerts based on user-defined thresholds. The setup process is straightforward, with features like OAuth login, multi-user support, automated backups, and a REST API included by default.

The dashboard provides real-time and historical views of CPU, memory, and network usage for every container. Alerts can be configured to trigger on CPU spikes, low memory availability, disk pressure, bandwidth saturation, temperature thresholds, or container status changes. The permission model allows users to manage their own systems while enabling administrators to share access across teams. Security is handled via OAuth2 providers, though password authentication is available (and can be disabled for stricter security). Backups can be written to local storage or any S3-compatible bucket.

Beszel consists of two primary components:

Hub. A web application powered by PocketBase. It hosts the dashboard UI and manages all connected systems.

Agent. A lightweight service that runs on each monitored host. It utilizes a minimalist, embedded SSH server to push system metrics to the Hub securely.

Deploy Beszel

1. Start the Hub

The Hub can be deployed as a standalone binary or as a containerized service.

Docker / Podman

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    ports:
      - 8090:8090
    volumes:
      - ./beszel_data:/beszel_data

Save the above as docker-compose.yml and execute:

docker compose up -d

Binary Installation

curl -sL https://get.beszel.dev/hub -o /tmp/install-hub.sh && chmod +x /tmp/install-hub.sh && /tmp/install-hub.sh

2. Create an Admin User

Navigate to http://localhost:8090 in your browser. Follow the setup prompts to create an account using your email or a GitHub login.

3. Add Your First System

Click the "Add System" button in the top-right corner of the dashboard. Keep this dialog open, as you will need the generated keys for the next step. Do not click the final "Add System" confirmation button yet.

4. Start the Agent

Docker
Create a directory for the agent and paste the configuration provided in the Hub's dialog into a new docker-compose.yml file.

mkdir beszel-agent
cd beszel-agent
nano docker-compose.yml

Once configured, start the agent:

docker compose up -d

Binary (Linux)
Copy the provided one-line installation command from the Hub dialog and run it in your terminal. This script automatically downloads, installs, and configures the agent service.

5. Finalize Connection

Return to the Hub dialog and click the "Add System" confirmation button. A green status indicator confirms a successful connection. If the indicator is red, consult the official troubleshooting documentation to check network or firewall settings.

Hub Installation Details

Docker Basic Setup

services:
  beszel:
    image: henrygd/beszel
    container_name: beszel
    restart: unless-stopped
    ports:
      - 8090:8090
    volumes:
      - ./beszel_data:/beszel_data

Hub with Local Agent (Same Host)
For monitoring the host where the Hub itself is running, you can use Unix sockets for communication:

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    ports:
      - 8090:8090
    volumes:
      - ./beszel_data:/beszel_data
      - ./beszel_socket:/beszel_socket

  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./beszel_socket:/beszel_socket
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      LISTEN: /beszel_socket/beszel.sock
      KEY: 'Replace with the public key from the "Add System" dialog'

Binary Setup (Linux)

Run the automated installation script:

curl -sL https://get.beszel.dev/hub -o /tmp/install-hub.sh && chmod +x /tmp/install-hub.sh && /tmp/install-hub.sh

Alternatively, download the binary manually and start it with specific flags:

./beszel serve --http "0.0.0.0:8090"

Systemd Service Configuration

To ensure the Hub stays active, create /etc/systemd/system/beszel.service:

[Unit]
Description=Beszel Hub
After=network.target

[Service]
Type=simple
Restart=always
RestartSec=3
User=root
WorkingDirectory=/path/to/working/directory
ExecStart=/path/to/working/directory/beszel serve --http "0.0.0.0:8090"

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable beszel.service
sudo systemctl start beszel.service

Agent Installation Methods

Docker Basic

services:
  beszel-agent:
    image: henrygd/beszel-agent
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      LISTEN: 45876
      KEY: '<your-public-key>'

Binary Installation Script (Linux)

curl -sL https://get.beszel.dev -o /tmp/install-agent.sh && chmod +x /tmp/install-agent.sh && /tmp/install-agent.sh

Commonly used flags:
-k Public key (must be wrapped in quotes).
-p Custom port or address (default is 45876).
-u Triggers uninstallation.
--auto-update Enables automated daily updates for the agent.

Homebrew (macOS, Linux)

curl -sL https://get.beszel.dev/brew -o /tmp/install-agent.sh && chmod +x /tmp/install-agent.sh && /tmp/install-agent.sh

For a manual Homebrew setup:

mkdir -p ~/.config/beszel ~/.cache/beszel
echo 'KEY="ssh-ed25519 AAAA..."' > ~/.config/beszel/beszel-agent.env
brew tap henrygd/beszel
brew install beszel-agent
brew services start beszel-agent

Windows (WinGet / Scoop)

Run this PowerShell command to install the agent on Windows:

& iwr -useb https://get.beszel.dev -OutFile "$env:TEMP\install-agent.ps1"; & Powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-agent.ps1"

Advanced Deployment

Ansible

Community members have developed roles for Beszel, such as those by dbrennand. Below is a logic snippet for an Ansible playbook:

- name: Download install-agent.sh script
  get_url:
    url: https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-agent.sh
    dest: /tmp/install-agent.sh
    mode: '0755'

- name: Execute agent installation with auto-update enabled
  shell: yes | /tmp/install-agent.sh -p {{ beszel_agent_ssh_port }} -k "{{ beszel_agent_ssh_key }}"
  when: beszel_agent_autoupdate | bool

Recommended variables for all.yml:

beszel_agent: true
beszel_agent_autoupdate: true
beszel_agent_ssh_key: 'ssh-ed25519 ...'
beszel_agent_ssh_port: 45876

Docker Swarm

You can define a service stack using placement constraints to ensure agents run on every node. The agent requires host networking mode and a read-only mount of the Docker socket to report container statistics accurately.

Kubernetes DaemonSet

For Kubernetes environments, deploy the agent as a DaemonSet to ensure coverage across all nodes. Set hostNetwork: true in the pod spec. When adding the system to the Hub, use the node’s internal or external physical IP address. Detailed YAML manifests are available in the official documentation.

Beszel offers a high-performance, clutter-free way to monitor your infrastructure. Choose the deployment method that fits your environment and begin tracking your server metrics today.