Homelable Docker: Homelab-Netzwerkplan mit Live-Status

Welche IP-Adresse hat eigentlich der Raspberry Pi, auf dem Pi-hole läuft? Und der zweite, der seit dem Umzug im Keller hängt und von dem du nur noch weißt, dass er irgendetwas Wichtiges tut? Wer ein Homelab ein paar Monate betreibt, hat die Antwort meistens an drei Orten: im Kopf, in einer Tabelle, die seit dem Frühjahr niemand mehr geöffnet hat, und in der Geräteliste des Routers, die alles kennt und nichts erklärt.

Homelable setzt genau da an. Es zeichnet dein Netz als Karte, mit einem Kästchen pro Gerät und Linien dazwischen, findet die Geräte per Scan selbst und markiert jedes Kästchen grün oder rot, je nachdem, ob es gerade antwortet. Das Projekt ist gut sieben Monate alt, steht bei 4.505 Sternen auf GitHub und war in der Self-Host Weekly vom 16-10-2026 das vorgestellte Projekt. Hier steht, was es kann, wo es noch jung ist, und wie es in einer halben Stunde bei dir läuft.

Was Homelable ist und welches Problem es löst

Im Kern ist Homelable eine Zeichenfläche im Browser, auf der jedes Gerät deines Netzes ein Knoten ist: Router, Switch, Proxmox-Host, die VMs darin, das NAS, die Kamera im Flur. Die Linien dazwischen ziehst du selbst oder lässt sie von der automatischen Anordnung setzen. Das allein könnte jedes Zeichenprogramm. Der Unterschied: Homelable befüllt die Kästchen selbst und fühlt ihnen regelmäßig den Puls.

Befüllt wird die Karte über nmap, den Klassiker unter den Netzwerk-Scannern. nmap klopft an jede Adresse in deinem Netz und notiert, wer antwortet und welche Dienste hinter welchen Ports lauschen, ungefähr so, als würde jemand in einem Mehrfamilienhaus an jeder Tür klingeln und die Namen auf den Klingelschildern abschreiben. Homelable ruft es laut README mit nmap -sV --open auf und legt alles Gefundene in eine Warteschlange. Auf die Karte kommt nur, was du freigibst. Das halte ich für die richtige Entscheidung: Ein Scan findet auch den Fernseher und das Handy deines Besuchs, und die gehören nicht automatisch in die Dokumentation deines Homelabs.

Danach prüft Homelable jeden Knoten, ab Werk alle 60 Sekunden. Der Punkt am Kästchen ist grün für online, rot für offline und schwarz für unbekannt. Wie geprüft wird, legst du pro Knoten fest, zur Wahl stehen ping, http, https, tcp, ssh, prometheus und health. Dazu kommen Importe aus Proxmox, Zigbee2MQTT und Z-Wave JS UI, seit Version 3.5.0 auch aus UniFi, ein Planer für Serverschränke und ein Bereich für Markdown-Dokumentation mit eigener Seite pro Gerät. Neben das Kästchen des NAS passt also gleich die Notiz, welche Platten darin stecken.

Warum gerade alle über Homelable reden

Das Repository wurde am 06-03-2026 angelegt. Heute zählt es 4.505 Sterne, 204 Forks und gut tausend Commits, und es steht unter MIT-Lizenz, darf also frei genutzt und verändert werden. Zwischen Anfang September und Anfang Oktober sind sechs Versionen erschienen, von 3.4.0 bis 3.6.0. Die Self-Host Weekly hat Homelable am 16-10-2026 in ihrer Rubrik „Content Spotlight“ vorgestellt, und bei den Proxmox Community Scripts gibt es inzwischen ein fertiges Skript, das es in einen eigenen LXC-Container setzt. So sieht ein Projekt aus, das gerade aus der Bastelecke in viele Homelabs wandert.

Tempo hat einen Preis, und der steht in Issue #347. Am 15-08-2026 meldete ein Nutzer, dass nach dem Update auf 3.3.0 alle seine Daten verschwunden waren. Schuld war eine Datenbank-Umstellung beim Start, die an Zeitstempeln scheiterte. Der Maintainer hat in den Tagen danach mehrere Korrekturversionen nachgelegt, und mit 3.3.4 meldete derselbe Nutzer, dass seine Karte wieder vollständig war. Verloren war am Ende nichts: Einer kam über den Rückweg auf 3.2.0 an seine Daten, ein anderer über eine ältere Kopie der Datenbank.

Für mich ist das eine ehrliche Auskunft über den Reifegrad, und sie hat eine klare Folge: Wer Homelable betreibt, nagelt die Version fest und sichert vor jedem Update den Datenordner. Beides ist in dieser Anleitung schon eingebaut.

Was du brauchst

• Einen Linux-Server mit Docker und Compose. Prüfen mit docker compose version; die Antwort beginnt mit Docker Compose version v2 oder einer höheren Version. Die Images gibt es für amd64 und arm64, ein Raspberry Pi mit 64-Bit-System geht also auch.
• Port 3000 frei. Prüfen mit ss -tlnp | grep ':3000 ' || echo "Port frei".
• Die Adresse deines Heimnetzes. Prüfen mit ip -4 -brief addr. In der Zeile deiner Netzwerkkarte steht die Adresse des Servers mit Schrägstrich, etwa 192.168.178.50/24. Steht dahinter /24, ersetzt du den letzten Zahlenblock durch eine 0 und hast dein Netz: 192.168.178.0/24, also alle Adressen von .1 bis .254. Hinter einer FritzBox ist das der Normalfall.

Schritt 1: Ordner anlegen und zwei Geheimnisse erzeugen

Der Schnellstart der Doku beginnt mit einem Installationsskript und der Anmeldung admin/admin; das Passwort tauschst du dort hinterher. Ich drehe die Reihenfolge um. Homelable braucht zwei Werte, bevor es überhaupt startet, und wenn du sie gleich am Anfang setzt, gibt es keine einzige Minute mit Standardpasswort in deinem Netz.

• SECRET_KEY: Mit diesem Schlüssel unterschreibt Homelable jede Anmeldung. Wer ihn kennt, kann sich Anmeldungen selbst ausstellen, deshalb muss er lang und zufällig sein. Einen Standardwert hat der Code nicht; fehlt der Schlüssel, startet das Backend gar nicht erst.
• Der Passwort-Hash: Homelable speichert von deinem Passwort nur einen bcrypt-Hash, eine Art Fingerabdruck. Mit ihm lässt sich prüfen, ob ein eingegebenes Passwort stimmt, aber aus dem Fingerabdruck lässt sich das Passwort nicht zurückrechnen.

Zuerst der Ordner und der Schlüssel:

mkdir -p ~/homelable && cd ~/homelable
docker run --rm ghcr.io/pouzor/homelable-backend:3.6 python -c "import secrets; print(secrets.token_hex(32))"

Beim ersten Aufruf lädt Docker das Image herunter, das dauert einen Moment. Danach erscheint eine Zeile aus 64 Zeichen, nur Ziffern und die Buchstaben a bis f. Kopier sie in eine Notiz, du brauchst sie in Schritt 2. Das --rm sorgt dafür, dass der Container nach dem Befehl sofort wieder verschwindet: Er leiht sich nur kurz das Python aus dem Homelable-Image und räumt dann auf.

Jetzt der Hash. Den Befehl dafür liefert die Doku, sie führt ihn im laufenden Container aus. Weil bei uns noch nichts läuft, nehmen wir wieder den Einweg-Container. Ersetz DEIN-PASSWORT durch dein Passwort und nimm dafür nur Buchstaben, Ziffern und Bindestriche, dafür reichlich davon. Umlaute beantwortet Python an dieser Stelle mit SyntaxError: bytes can only contain ASCII literal characters, und Anführungszeichen im Passwort zerlegen den Befehl. Setz außerdem ein Leerzeichen vor den Befehl, wenn du ihn einfügst: Dann merkt sich die Shell bei Debian und Ubuntu den Befehl nicht, und dein Passwort steht hinterher nicht im Klartext in ~/.bash_history.

docker run --rm ghcr.io/pouzor/homelable-backend:3.6 python -c 'import bcrypt; print(bcrypt.hashpw(b"DEIN-PASSWORT", bcrypt.gensalt()).decode().replace("$", "$$"))'

Die Ausgabe ist eine lange Zeichenkette, die mit $$2b$$12$$ beginnt. Auch die kommt in die Notiz. Die doppelten Dollarzeichen sind Absicht. Docker Compose liest ein einzelnes $ als Beginn einer Variablen und würde den Hash beim Einlesen zerpflücken; $$ heißt für Compose „hier steht wirklich ein Dollarzeichen“, und im Container kommt dann der richtige Hash mit einfachen Dollarzeichen an. Das .replace("$", "$$") am Ende hat die Doku genau dafür in den Befehl geschrieben.

Schritt 2: Die Compose-Datei anlegen und starten

Die offizielle Compose-Datei startet drei Dienste. Ich nehme zwei davon: das Backend, das scannt, prüft und die Datenbank führt, und das Frontend, die Weboberfläche. Den dritten, einen MCP-Server, lasse ich weg. MCP ist eine Schnittstelle, über die KI-Assistenten deine Karte lesen und bearbeiten können. Im Original lauscht er auf Port 8001, und die Beispielkonfiguration bringt dafür den Schlüssel mcp_sk_changeme mit. Wer das nicht nutzt, braucht den Port auch nicht offen.

cd ~/homelable
nano docker-compose.yml

Diesen Inhalt einfügen. Dann mit den Pfeiltasten zu den beiden Platzhaltern HIER_DEIN_SECRET_KEY und HIER_DEIN_PASSWORT_HASH gehen, jeweils den Platzhalter löschen und den Wert aus deiner Notiz einfügen; im Terminal klappt das Einfügen meist mit Strg+Umschalt+V oder einem Rechtsklick. Die einfachen Anführungszeichen drumherum bleiben stehen. Speichern mit Strg+O, Enter, schließen mit Strg+X:

services:
  backend:
    image: ghcr.io/pouzor/homelable-backend:3.6
    restart: unless-stopped
    cap_add:
      - NET_RAW
    volumes:
      - ./data:/app/data
    environment:
      SQLITE_PATH: /app/data/homelab.db
      CORS_ORIGINS: '["http://192.168.178.50:3000"]'
      SECRET_KEY: 'HIER_DEIN_SECRET_KEY'
      AUTH_MODE: local
      AUTH_USERNAME: admin
      AUTH_PASSWORD_HASH: 'HIER_DEIN_PASSWORT_HASH'
      SCANNER_RANGES: '["192.168.178.0/24"]'
      STATUS_CHECKER_INTERVAL: 60

  frontend:
    image: ghcr.io/pouzor/homelable-frontend:3.6
    restart: unless-stopped
    ports:
      - "3000:80"
    depends_on:
      - backend

Fünf Stellen verdienen einen Blick:

• image: …:3.6: Die Doku nimmt latest. Das Tag 3.6 bekommt die Fehlerkorrekturen der 3.6-Reihe, springt aber nie ohne dein Zutun auf 3.7. Nach Issue #347 ist mir das bei diesem Projekt den einen Handgriff beim Update wert.
• cap_add: NET_RAW: erlaubt dem Container, Netzwerkpakete selbst zusammenzubauen. Das brauchen ping und die gründlicheren nmap-Scans. Die Zeile steht genauso in der offiziellen Datei.
• ./data:/app/data: Hier liegt alles, was Homelable sich merkt, die Datenbank homelab.db und hochgeladene Bilder. Die offizielle Datei nimmt ein von Docker verwaltetes Volume. Ich nehme einen Ordner neben der Compose-Datei, weil du ihn sehen und mit einem Befehl sichern kannst; da das Backend im Container als root läuft, gibt es dabei keinen Ärger mit Dateirechten.
• CORS_ORIGINS: die Adresse, unter der du Homelable im Browser öffnest, genau so, wie sie in der Adresszeile steht, mit http:// und Port. Die offizielle Datei trägt hier nur localhost ein. In Issue #186 scheiterte genau daran das Speichern der Karte mit dem Fehler 401, und die Lösung des Maintainers war diese eine Zeile.
• SCANNER_RANGES: das Netz, das der Scan absucht, im Format aus „Was du brauchst“. Mehrere Netze stehen mit Komma in derselben Liste: '["192.168.178.0/24","192.168.10.0/24"]'.

Ob die Datei formal stimmt, sagt dir Compose selbst:

docker compose config --quiet && echo "Datei ok"

Datei ok

Dann starten und nachsehen, ob beide Container laufen:

docker compose up -d
docker compose ps --format "{{.Service}}: {{.State}}"

backend: running
frontend: running

Stehen beide auf running, läuft der Laden. Steht das Backend auf restarting, stürzt es beim Start ab, und docker compose logs backend nennt den Grund; ein SECRET_KEY, der beim Einfügen verloren ging, ist einer davon. Danach im Browser auf dem Laptop öffnen: http://192.168.178.50:3000.

Geklappt hat es, wenn du eine leere Arbeitsfläche mit einer Seitenleiste daneben siehst. Leer ist hier richtig.

Schritt 3: Das Netz scannen und Geräte übernehmen

Ein ganzes Heimnetz kann ein paar Minuten dauern, weil nmap bei jedem Gerät auch nachsieht, welche Dienste dahinter laufen. Danach geht es ans Sortieren:

Das Speichern ist kein Detail. Laut Doku speichert Homelable die Karte nur, wenn du es sagst; wer Knoten verschiebt und dann den Tab schließt, schiebt beim nächsten Mal von vorn. Ausgeblendete Geräte sind nicht weg, sie stehen unter Hidden Devices in der Seitenleiste und lassen sich dort zurückholen. Die Spalte für die MAC-Adresse bleibt in diesem Aufbau übrigens leer; warum, steht weiter unten bei den Stolpersteinen.

Der Test: Seite neu laden. Die Knoten stehen noch da und tragen nach spätestens einer Minute einen farbigen Punkt. Freigegebene Geräte prüft Homelable zunächst per ping. Wenn der Router als Erster grün wird, darfst du dich kurz freuen: Das ist der Moment, in dem aus einem Haufen Adressen ein Bild wird.

Was am Ende eingestellt ist

• Eigenes Passwort, eigener Schlüssel. Erledigt in Schritt 1, und es ist der wichtigste Punkt dieser Liste. Ein neues Passwort bekommst du auf demselben Weg: Hash mit dem Befehl aus Schritt 1 neu erzeugen, in die Compose-Datei eintragen, docker compose up -d. Compose merkt die Änderung und baut das Backend mit dem neuen Wert neu auf. Eine Anmeldung gilt 24 Stunden.
• Die passende Prüfmethode pro Gerät. ping sagt nur, ob ein Gerät am Netz hängt. Ein Server antwortet auch dann noch brav auf Ping, wenn die Nextcloud darauf längst steht. Für Knoten mit Webdienst stellst du beim Bearbeiten des Knotens die Methode auf http oder https, dann ruft Homelable die Seite tatsächlich ab, statt nur anzuklopfen. Für Dienste mit festem Port ohne Weboberfläche gibt es tcp.
• Nur im Heimnetz. Port 3000 spricht unverschlüsselt, und die Dokumentation der Programmierschnittstelle ist laut README ohne Anmeldung erreichbar. Sie verrät, wie die Schnittstelle aufgebaut ist, nicht deine Daten, und die README sagt trotzdem klar: im LAN lassen. Von unterwegs gehört ein VPN ins Heimnetz davor, keine Portfreigabe. Die Live View, eine schreibgeschützte Ansicht der Karte ohne Anmeldung, ist ab Werk aus, und so darf sie bleiben, bis du sie brauchst.
• Ein Backup vor jedem Update. Alles liegt in ~/homelable/data. Drei Befehle sichern es: Backend anhalten, damit die Datenbank nicht mitten im Schreiben kopiert wird, Ordner packen, Backend wieder starten.

cd ~/homelable
docker compose stop backend
sudo tar czf homelable-backup-$(date +%F).tgz data
docker compose start backend

Ob es geklappt hat, zeigt ls ~/homelable: Neben data und docker-compose.yml liegt jetzt eine Datei homelable-backup-<datum>.tgz. Regelmäßig, verschlüsselt und auf einem zweiten Gerät wird daraus ein echtes Backup mit Kopia. Ja, ich weiß, ich sage das in jeder Anleitung. Issue #347 ist der Grund, warum es hier zweimal dasteht.

• Updates von Hand. Erst die Release Notes auf GitHub lesen, dann das Backup von oben, dann in der Compose-Datei bei beiden Images 3.6 durch die neue Version ersetzen und docker compose pull && docker compose up -d aufrufen. Backend und Frontend tragen immer dieselbe Version. Korrekturen innerhalb der 3.6-Reihe holt derselbe Befehl auch ohne Änderung an der Datei.

Wo es klemmt

Keine MAC-Adressen, doppelte Geräte. Die Doku sagt es offen: Im normalen Docker-Netz sitzt der Container hinter einer Art eigenem kleinen Router, und MAC-Adressen sieht man nur innerhalb desselben Netzabschnitts. Das NET_RAW aus der Compose-Datei ändert daran nichts, auch das steht ausdrücklich dort. Homelable erkennt Geräte zuerst an der MAC-Adresse und erst dann an der IP. Bekommt ein Gerät vom Router eine neue IP, taucht es deshalb beim nächsten Scan als neues Gerät auf. Die Doku beschreibt als Ausweg den Host-Modus, bei dem das Backend direkt im Netz des Servers hängt: nur unter Linux, mit network_mode: host beim Backend sowie BACKEND_UPSTREAM und extra_hosts beim Frontend, Details in der INSTALLATION.md. Das Backend belegt dann Port 8000 direkt auf dem Server. Der einfachere Weg führt über den Router: Gib deinen Homelab-Geräten dort feste Adressen, bei der FritzBox heißt die Option „Diesem Netzwerkgerät immer die gleiche IPv4-Adresse zuweisen“. Ändert sich die IP nie, reicht der Abgleich über die IP.

Die Anmeldung scheitert. Bei einer frischen Installation ist der Hash der erste Verdächtige. In Issue #21 lief die Anmeldung auf einen Serverfehler, weil der Hash beschädigt im Backend ankam. Der Maintainer tippte auf verschluckte Dollarzeichen, beim Melder war es am Ende eine Konfiguration, die nie auf dem Server gelandet war. Seitdem warnt das Backend beim Start, wenn der Hash nicht wie ein bcrypt-Hash aussieht. Nachsehen kannst du so:

cd ~/homelable
docker compose logs backend

Steht dort eine Warnung zum Passwort-Hash, erzeugst du ihn mit dem Befehl aus Schritt 1 neu, trägst ihn mit den doppelten Dollarzeichen ein und rufst docker compose up -d auf.

Speichern schlägt mit 401 fehl. Dann fehlt die Adresse aus der Adresszeile in CORS_ORIGINS. Öffnest du Homelable mal über die IP und mal über einen Namen wie http://homelab.fritz.box:3000, gehören beide in die Liste, durch Komma getrennt. Danach wieder docker compose up -d.

Für wen sich Homelable lohnt

Für alle, deren Homelab über drei Geräte hinausgewachsen ist und die beim Gedanken an die IP-Tabelle ein schlechtes Gewissen bekommen. Für Proxmox-Nutzer, weil der Import Hosts, VMs und LXC-Container samt Verschachtelung auf die Karte holt und auf Wunsch aktuell hält. Und für alle, die ihr Netz einem anderen Menschen erklären müssen: der Familie, dem Nachfolger im Verein, oder dir selbst in einem Jahr, wenn du vergessen hast, warum der zweite Switch im Flur hängt.

Wer vor allem eine Nachricht aufs Handy will, sobald etwas ausfällt, ist mit Uptime Kuma besser bedient; Benachrichtigungen sind dort die Kernaufgabe, bei Homelable ist es die Karte. Beides verträgt sich. Seit 3.6.0 gibt es sogar den Schalter STATUS_CHECKER_ENABLED, mit dem du die Prüfungen in Homelable abschaltest, wenn ein anderes Werkzeug sie übernimmt.

Und der Reifegrad, ehrlich: gut sieben Monate alt, Version 3.6, sechs Versionen in einem Monat, und im August eine Umstellung, nach der Daten zeitweise nicht mehr zu sehen waren. Für ein Werkzeug, das dein Netz beschreibt und nicht steuert, ist das Risiko überschaubar. Geht etwas schief, verlierst du Zeichenarbeit, kein laufendes System. Mit fester Version und Backup würde ich Homelable heute einsetzen.

Wie dokumentierst du dein Netz bis jetzt: im Kopf, in einer Tabelle, auf Papier, oder ehrlich gesagt gar nicht? Ab damit in die Kommentare.

Und falls der erste Scan Geräte mit offenem SSH-Port zeigt, bei denen du nicht mehr weißt, wer sie eingerichtet hat: Wie du die Tür ordentlich zumachst, steht in SSH absichern auf Debian und Ubuntu.

Quellen

• Homelable auf GitHub (README, Funktionen, Prüfmethoden, Lizenz)
• Homelable: INSTALLATION.md (Docker, Passwort-Hash, Netzwerk-Scans, Host-Modus)
• Homelable: FEATURES.md (Scan, Device Inventory, Speichern, Status)
• Homelable: offizielle Compose-Datei mit fertigen Images
• Homelable: .env.example (Umgebungsvariablen)
• Homelable: Backend-Konfiguration (Standardwerte)
• Homelable: Dockerfile des Backends
• Homelable 3.6.0 Release Notes
• Homelable Changelog
• Homelable: Container-Images und Tags auf GHCR
• Issue #347: Daten nach Update auf 3.3.0 verschwunden
• Issue #186: Speichern scheitert mit 401 (CORS_ORIGINS)
• Issue #21: Anmeldung scheitert am Passwort-Hash
• Self-Host Weekly vom 16-10-2026 (Content Spotlight)