DOCSEARCHbyAlgolia
Submit Docs

Beszel Server Monitoring Platform

repository·main·Indexed 12 days ago

https://github.com/henrygd/beszel

A lightweight server monitoring platform for tracking host and container metrics (Docker/Podman) with low resource usage. It utilizes a client-server architecture consisting of a central Hub for dashboards and management, and lightweight Agents installed on monitored systems to collect CPU, memory, disk, network, GPU, and S.M.A.R.T. data.

Tokens
10K
Snippets
41
Records
53
Agent score
95%

What's inside Beszel

  1. Overview of Beszel

    main
    Beszel is a lightweight server monitoring platform designed for simplicity and low resource consumption. It provides a web interface to monitor host systems and Docker/Podman containers, offering historical data, Docker statistics, and configurable alerts. Key features include multi-user support, OAuth/OIDC authentication, automatic backups (to disk or S3), and a REST API for external integration.

  2. How Beszel architecture works

    main

    Beszel operates using a client-server model consisting of two primary components:

    1. Hub: The central web application (built on PocketBase) that serves as the dashboard for viewing metrics and managing connected systems.
    2. Agent: A lightweight component installed on every system you wish to monitor. The agent collects system metrics and communicates them back to the Hub.

  4. Manually configure Beszel Hub systemd service

    main

    If you prefer not to use the install script, you can manually create a systemd service file at /etc/systemd/system/beszel.service.

    Ensure you replace the placeholders in curly braces with your actual paths and username. After creating the file, reload the daemon, enable the service for boot, and start it.

    # /etc/systemd/system/beszel.service
[Unit]
Description=Beszel Hub Service
After=network.target

[Service]
ExecStart={/path/to/working/directory}/beszel serve
WorkingDirectory={/path/to/working/directory}
User={YOUR_USERNAME}
Restart=always

[Install]
WantedBy=multi-user.target
    sudo systemctl daemon-reload
sudo systemctl enable beszel.service
sudo systemctl start beszel.service

  5. Install Beszel Agent as a systemd service using the install script

    main

    The recommended way to run the Beszel Agent in the background is via the provided install script. This script creates a dedicated beszel user, downloads the latest release, and sets up the systemd service.

    You can optionally provide an SSH key and port as arguments. If using the -k flag for a key, ensure the key is enclosed in quotes.

    # Download the script
curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-agent.sh -o install-agent.sh && chmod +x install-agent.sh

# Install
./install-agent.sh

# View help for arguments
./install-agent.sh -h

  6. Uninstall or Update Beszel Hub

    main

    To remove the Beszel Hub service, run the install script with the -u flag. To update the Hub, use the internal update command and restart the systemd service.

    # Uninstall
./install-hub.sh -u

# Update
sudo /opt/beszel/beszel update && sudo systemctl restart beszel-hub

  7. Uninstall or Update Beszel Agent

    main

    To remove the Beszel Agent service, run the install script with the -u flag. To update the Agent, use the internal update command and restart the systemd service.

    # Uninstall
./install-agent.sh -u

# Update
sudo /opt/beszel-agent/beszel-agent update && sudo systemctl restart beszel-agent

  8. Install Beszel Hub as a systemd service using the install script

    main

    The recommended way to run the Beszel Hub in the background is via the provided install script. This script creates a dedicated beszel user, downloads the latest release, and sets up the systemd service. You must have system administrator privileges.

    To install, download the script, make it executable, and run it. You can optionally specify a custom port using the -p flag (default is 8090).

    # Download the script
curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-hub.sh -o install-hub.sh && chmod +x install-hub.sh

# Install (default port 8090)
./install-hub.sh

# Install with a custom port
./install-hub.sh -p 9000

  9. Manually configure Beszel Agent systemd service

    main

    To manually install the Beszel Agent, create a service file at /etc/systemd/system/beszel-agent.service.

    You can use Environment variables to configure the agent:

    • PORT: The port to run on.
    • KEY: The authentication key.
    • EXTRA_FILESYSTEMS: (Optional) Specify additional filesystems to monitor (e.g., Environment="EXTRA_FILESYSTEMS={sdb}").

    Replace all {} placeholders with your actual configuration values. After creation, reload, enable, and start the service.

    # /etc/systemd/system/beszel-agent.service
[Unit]
Description=Beszel Agent Service
After=network.target

[Service]
Environment="PORT={PASTE_YOUR_PORT_HERE}"
Environment="KEY={PASTE_YOUR_KEY_HERE}"
# Environment="EXTRA_FILESYSTEMS={sdb}"
ExecStart={/path/to/directory}/beszel-agent
User={YOUR_USERNAME}
Restart=always

[Install]
WantedBy=multi-user.target
    sudo systemctl daemon-reload
sudo systemctl enable beszel-agent.service
sudo systemctl start beszel-agent.service

  10. WebSocketClient message routing and decoding

    main

    The WebSocketClient implements the gws.BuiltinEventHandler interface to process incoming traffic:

    • Binary Messages: The client expects gws.OpcodeBinary. Incoming data is unmarshaled from CBOR into a common.HubRequest[cbor.RawMessage] structure.
    • Routing: Once decoded, the request is passed to handleHubRequest, which uses the agent's handlerRegistry to find the appropriate logic to execute based on the message content.
    • Pings: The client automatically responds to OnPing frames with a pong to maintain the connection and resets the wsDeadline.

  11. How WebSocketClient handles authentication and verification

    main

    The WebSocketClient uses a two-step process for secure communication:

    1. Token Authentication: During the initial WebSocket handshake, the client includes the registration token in the X-Token HTTP header.
    2. Hub Verification: Upon connection, the hub may issue an authentication challenge. The client verifies the hub's signature using the agent's configured public keys (client.agent.keys). Once verified, client.hubVerified is set to true, allowing the agent to proceed with sending sensitive system information.

  12. Deploy Beszel Hub using Docker Compose

    main

    To run the Beszel Hub (the central dashboard) on the same system as your agent, use the henrygd/beszel:latest image. The Hub requires a persistent volume for data and a socket for communication.

    Key configuration:

    • Ports: Maps host port 8090 to container port 8090.
    • Environment Variables: Set APP_URL to the public or local URL where the dashboard is accessible.
    • Volumes: Requires ./beszel_data for application data and ./beszel_socket for the socket file.
    services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    environment:
      APP_URL: http://localhost:8090
    ports:
      - 8090:8090
    volumes:
      - ./beszel_data:/beszel_data
      - ./beszel_socket:/beszel_socket