Skip to content

How to setup beszel (with Docker & Caddy)

Ready to use

Description

Beszel is a lightweight server monitoring tool that consists of a hub (web interface) and agents (for monitoring servers).
The setup provides a clean monitoring solution with Docker container stats, system metrics, and a web-based dashboard for managing multiple servers.

Create a DNS record (optional)

Warning

Remember!
Whenever you expose your services to the outside world, you open up the possiblity of an attack by hackers.
Only expose to the outside world the services you actually need to access when you're away from home.

You probably won't need to access Beszel from outside the network too often.
So you probably shouldn't make it available outside of your network.

But if you do, then go to cPanel and add a new record (e.g. beszel.akdscloud.eu).

Caddy

beszel.akdscloud.eu:443 {
    header Strict-Transport-Security max-age=31536000;
    reverse_proxy localhost:6767
}

Folders

Create the folder structure.

cd ~/services
mkdir -p beszel/config

Docker

  1. Add the beszel section to your docker-compose.yml file:

      beszel:
    image: henrygd/beszel:latest
    container_name: beszel-hub
    restart: unless-stopped
    ports:
      - "8090:8090"
    volumes:
      - ./beszel/beszel_data:/beszel_data
      - ./beszel/beszel_socket:/beszel_socket
    environment:
      - TZ=Europe/Bucharest
      # Optional: Disable user registration after first user
      # - DISABLE_REGISTRATION=true

  2. Start the beszel service:

    docker compose up -d beszel

  3. Access the web interface

    See if you can access the beszel web interface at http://localhost:8090.

    If you can't check out the logs:

    docker compose logs -f beszel

    See if there are any errors and fix them.

  4. Admin account

    Create an admin account from the web interface (first user becomes admin).

  5. Add the local Beszel agent

    • In the Beszel web interface, go to "Systems" and click "Add System"
    • Give it a name (e.g. System)
    • Click on Copy docker-compose
    • Add system

    Don't worry!

    Beszel will probably not show anything at this point.
    This is ok!
    We haven't set up the monitoring agent yet.

  6. Add the agent to docker-compose.yml

    Edit your docker-compose.yml and add another service after beszel by simply pasting (what you copied from the Add system dialog)

    It should look like this: 

      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
      # monitor other disks / partitions by mounting a folder in /extra-filesystems
      # - /mnt/disk/.beszel:/extra-filesystems/sda1:ro
    environment:
      LISTEN: 45876
      KEY: "ssh-ed25519alotofrandomletters"

  7. Start the agent: 

    docker compose up -d beszel-agent

  8. Check if everything is working

    Now go back to the web interface and refresh the page.
    It should work now.
    If not, restart both docker services.

Troubleshooting

If it still doesn't work, see the troubleshooting guide.

Configuration

Disable registration

If you want to prevent new user registrations, go to the docker-compose.yml file and uncomment the DISABLE_REGISTRATION line.

After that, 

docker compose down beszel
docker compose up -d beszel

Security Notes

  • Make sure to secure your hub with proper authentication
  • Consider using a reverse proxy with SSL for production deployments
  • The agent needs network access to communicate with the hub

Official site

Github page