Beszel mit Docker Compose: Leichtes Monitoring lokal auf Port 8090 starten

Wenn heute kein starkes News-Thema sauber traegt, muss der Ersatz ein reales Problem loesen. Beszel ist dafuer stark genug: kleines Setup, sichtbares Ergebnis und sofort nutzbare Host- und Docker-Metriken im Browser.

Der Stand fuer diesen Artikel ist belastbar. Die offizielle Beszel-Doku fuehrt heute Version 0.18.7, die zugehoerige GitHub-Release wurde am 5. April 2026 veroeffentlicht, die Docker-Tags henrygd/beszel:0.18.7 und henrygd/beszel-agent:0.18.7 sind auf Docker Hub vorhanden, und die Doku-Seiten fuer Hub, Getting Started und Agent-Installation wurden laut Seite zuletzt am 14. April 2026 aktualisiert.

Lokal erzeugtes Artikelbild fuer Beszel mit Docker Compose

Was du am Ende hast

Ein Beszel-Hub unter http://127.0.0.1:8090
Ein lokales Monitoring-Setup fuer einen Linux-Host
Docker-Container-Statistiken direkt im Beszel-Dashboard
Persistente Daten im Projektordner statt fluechtiger Container-Konfiguration

1. Voraussetzungen

Dieses Tutorial ist bewusst fuer einen Linux-Host geschrieben. Der offizielle Docker-Agent nutzt network_mode: host, was in klassischen Linux-Setups sauber funktioniert.

Du brauchst:

Docker mit Compose-Plugin
einen freien Port 8090
Zugriff auf einen Linux-Host, dessen Docker-Container du beobachten willst

Pruefe kurz die Basis:

docker --version
docker compose version

2. Projektordner anlegen

Nicht in irgendeinem bestehenden Verzeichnis arbeiten. Lege zuerst einen eigenen Ordner an:

mkdir beszel-lab
cd beszel-lab

3. Hub zuerst lokal starten

Erstelle jetzt compose.yaml mit einem bewusst kleinen Start: erst der Hub, dann spaeter der Agent. Das entspricht der Beszel-Logik, weil der Hub dir im Dialog den passenden Agent-Block samt Schluessel vorbereitet.

beszel-lab/compose.yaml

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

Jetzt starten:

docker compose up -d
docker compose ps
curl -I http://127.0.0.1:8090

Wenn curl mit einer HTTP-Antwort zurueckkommt, steht der Hub.

Falls nicht:

docker compose logs --tail=100 beszel

4. Ersten Benutzer im Browser anlegen

Oeffne http://127.0.0.1:8090. Beim ersten Aufruf fuehrt dich Beszel durch die Benutzeranlage. Genau das ist der Punkt, an dem das Projekt gegenueber schwereren Monitoring-Stacks angenehm bleibt: kein externer Datenbankzwang, kein Grafana- oder Prometheus-Vorbau fuer den ersten sichtbaren Erfolg.

5. Agent fuer denselben Host vorbereiten

Jetzt kommt der Teil, den viele Blogposts unsauber abkuerzen. Der offizielle Beszel-Flow erzeugt den Agent-Schluessel aus dem Add System-Dialog.

Gehe im Hub so vor:

Klicke oben rechts auf Add System.
Lege einen Namen fuer den Host fest.
Waehle die Agent-Variante fuer einen Docker- oder Linux-Host.
Oeffne im Dialog die Docker-Anweisungen.
Kopiere den dort angezeigten KEY-Wert oder gleich den kompletten Compose-Block.

Wichtig ist die Reihenfolge:

Den Dialog offen lassen
erst danach den Agent lokal starten
Add System erst klicken, wenn der Agent wirklich laeuft

6. Compose-Datei um den Agent erweitern

Ersetze compose.yaml jetzt durch die Hub-plus-Agent-Variante. Die Struktur lehnt sich an das offizielle same-system-Beispiel an, ist aber auf 0.18.7 gepinnt und lokal an 127.0.0.1:8090 gebunden.

Setze bei KEY exakt den Wert ein, den dir Beszel im Dialog gezeigt hat.

beszel-lab/compose.yaml

services:
  beszel:
    image: henrygd/beszel:0.18.7
    container_name: beszel
    restart: unless-stopped
    ports:
      - "127.0.0.1:8090:8090"
    volumes:
      - ./beszel_data:/beszel_data
    extra_hosts:
      - "host.docker.internal:host-gateway"

  beszel-agent:
    image: henrygd/beszel-agent:0.18.7
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      PORT: 45876
      KEY: "PASTE_THE_KEY_FROM_ADD_SYSTEM_HERE"

Danach erneut starten:

docker compose up -d
docker compose ps
docker compose logs --tail=100 beszel-agent

Wenn der Agent sauber laeuft, gehst du zurueck in den noch offenen Add System-Dialog und bestaetigst dort den Host.

7. Ergebnis pruefen

Ein funktionierendes Ergebnis ist hier nicht nur "Container laufen", sondern ein sichtbares Monitoring-UI mit gruener Verbindung.

Pruefe deshalb konkret:

docker compose ps
curl -I http://127.0.0.1:8090
docker compose logs --tail=50 beszel
docker compose logs --tail=50 beszel-agent

Im Browser solltest du danach sehen:

der neue Host erscheint in der Uebersicht
der Status springt auf gruen
CPU, RAM und Speicherwerte laufen ein
Docker-Container werden nach kurzer Zeit in den Metriken sichtbar

Wenn der Host rot bleibt, stimmt fast immer entweder der KEY nicht exakt, der Agent laeuft noch nicht, oder der Dialog wurde geschlossen und mit veralteten Werten erneut befuellt.

8. Updates spaeter sauber fahren

Das Projekt lebt davon, dass es klein bleibt. Halte deshalb auch den Update-Weg klein und reproduzierbar:

docker compose pull
docker compose up -d
docker compose ps

Genau hier hilft das Pinning auf 0.18.7: Du weisst, worauf sich dieses Tutorial bezieht. Wenn du spaeter auf eine neuere Beszel-Version gehst, vergleichst du gezielt Release Notes und Compose-Beispiel statt blind latest mitzunehmen.

Warum Beszel als Fallback heute stark genug ist

Viele Self-Hosting-Anleitungen enden bei "Container ist gestartet". Das reicht nicht. Beszel liefert schon nach wenigen Minuten einen sichtbaren Nutzen:

eine echte Weboberflaeche statt nur eines API-Endpunkts
Docker-Statistiken ohne zusaetzlichen Grafana-Ballast
einen klaren Hub-Agent-Aufbau, der spaeter auf weitere Systeme erweitert werden kann

Gerade am 14. April 2026 ist das ein sauberer Fallback: kein duennes News-Recycling, sondern ein aktuelles Docker-Projekt mit nachvollziehbarem Ergebnis und sauber verifizierter Versionsbasis.

User Dashboard