Wer in einem kleinen Unternehmen Geräte verwaltet, kennt das Muster: Die Seriennummer steht in einer Tabelle, der Kaufbeleg liegt im Mailpostfach, das Garantiedatum kennt niemand, und beim Ausfall des Notebooks beginnt die Suche. Homebox ist ein schlankes, selbst gehostetes Inventarsystem, das genau diese Lücke schließt, ohne dass Sie ein ausgewachsenes ITSM-Produkt betreiben müssen. Ein Container, eine Datenbank, eine Weboberfläche.

Diese Anleitung zeigt eine vollständige Installation mit Docker Compose samt PostgreSQL, echten Betriebsdaten, Backup und Wiederherstellung, Absicherung hinter einem Reverse Proxy sowie den typischen Fehlern. Der Stack wurde am 22. September 2026 auf einem Linux-Host mit Docker Compose real installiert und geprüft. Alle Ausgaben in dieser Anleitung stammen aus diesem Test, sofern nicht ausdrücklich anders gekennzeichnet.

Nutzen und Grenzen

Homebox ist laut Repository-Beschreibung die Fortführung des ursprünglichen HomeBox-Projekts von hay-kot, gepflegt unter sysadminsmedia/homebox. Die Zahlen laut GitHub-API, abgerufen am 22. September 2026: 7350 Sterne, letzter Push am 18. September 2026, nicht archiviert, Lizenz AGPL-3.0. Das aktuellste Release laut API-Endpunkt releases/latest ist v0.26.2 vom 14. Juni 2026. Die Weboberfläche des getesteten Containers meldete unter /api/v1/status ebenfalls "version":"v0.26.2", Image-Tag und Release stimmen hier also überein.

Wofür Homebox in einer kleinen IT gut funktioniert:

Geräte, Zubehör und Verbrauchsmaterial mit Hersteller, Modellnummer und Seriennummer erfassen
Kaufdatum, Kaufpreis, Händler und Garantieablauf pro Gerät hinterlegen
Standorte hierarchisch abbilden, etwa Standort, Raum, Rack, Schublade
Belege, Rechnungen, Handbücher und Fotos als Anhang direkt am Gerät speichern
Etiketten mit QR-Code erzeugen und Geräte durch Scannen sofort wiederfinden
Eigene Felder für Dinge, die das Datenmodell nicht kennt, etwa Kostenstelle oder Inventarnummer aus der Buchhaltung
Vollständiger CSV-Export für die Weitergabe an Steuerberatung oder Versicherung

Und jetzt ehrlich zu den Grenzen. Homebox ist ausdrücklich für den Heimanwender gebaut und trägt das auch im eigenen README. Es ist keine CMDB und keine ITSM-Lösung. Konkret fehlt:

Keine automatische Netzwerk- oder Geräteerkennung. Es gibt keinen Agenten, keinen SNMP-Scan, keine Active-Directory-Inventarisierung. Jedes Gerät landet per Hand, per CSV-Import oder per API im System.
Keine Beziehungen im CMDB-Sinn. Sie können Objekte verschachteln, aber nicht modellieren, dass ein Dienst von einem Server abhängt, der wiederum an einer USV hängt.
Kein Vertrags- und Lizenzmanagement im ITIL-Sinn. Software-Lizenzen lassen sich als Objekte mit Ablaufdatum anlegen, es gibt aber keine Zuweisungslogik mit freien und belegten Plätzen, keine Compliance-Auswertung.
Kein Ticketsystem, kein Helpdesk, keine Workflows und keine Genehmigungsprozesse.
Die Rechteverwaltung ist einfach gehalten. Daten gehören einer Gruppe, in die man über einen Einladungslink kommt. Feingranulare Rollen pro Objektklasse gibt es nicht.

Zur fairen Abgrenzung: Wenn Sie Lizenzplätze zählen, Geräte an Personen ausgeben und wieder einziehen und einen Audit-Trail brauchen, ist Snipe-IT die passendere Wahl, dazu haben wir eine eigene Anleitung. Wenn Sie zusätzlich Helpdesk, Ticketing und automatische Inventarisierung per Agent brauchen, führt der Weg zu GLPI. Homebox gewinnt dort, wo diese beiden zu schwer sind: sehr geringer Ressourcenbedarf, Installation in Minuten, eine Oberfläche, die auch nicht-technische Kollegen ohne Schulung bedienen. Im Test lag der Speicherverbrauch des Homebox-Containers im Leerlauf bei 14,14 MiB, gemessen mit docker stats --no-stream.

Voraussetzungen und Ressourcen

Sie brauchen einen Linux-Host mit Docker Engine und dem Compose-Plugin (Version 2). Der Ressourcenbedarf ist gering. Das offizielle README nennt für den Container im Leerlauf unter 50 MB Speicher, der Test bestätigte das mit deutlichem Abstand. Der PostgreSQL-Container belegte im Test 45,48 MiB.

Ressource	Empfehlung	Im Test beobachtet
CPU	1 vCPU reicht für kleine Bestände	0,41 Prozent im Leerlauf
Arbeitsspeicher	512 MB für beide Container plus Puffer	14,14 MiB App, 45,48 MiB Datenbank
Speicherplatz	2 GB plus Platz für Fotos und Belege	Image 198 MB laut `docker images`
Ports	Ein freier Host-Port, im Container immer 7745	Test lief auf 127.0.0.1:37450

Unterstützte Plattformen: Die offizielle Compose-Datei im Repository baut laut x-bake-Block für linux/amd64, linux/arm64 und linux/arm. Der Test lief auf amd64. Die Dokumentation stellt außerdem Binaries für Windows, macOS, Linux und experimentell RISC-V bereit, empfiehlt aber ausdrücklich Docker für den produktiven Einsatz und bezeichnet Windows nicht als primäre Plattform. Für RISC-V rät das Projekt vom Produktivbetrieb ab.

Bei den Images gibt es drei Varianten, jeweils als eigener Tag:

Tag	Eigenschaft	Hinweis der Dokumentation
`latest` bzw. `0.26.2`	Standardimage mit Shell	Für den Test verwendet
`latest-rootless`	Läuft als Benutzer `homebox`, UID 65532	Bind-Mount vorher auf 65532 chownen
`latest-hardened`	Distroless, ohne Shell und Werkzeuge	Enthält keinen MQTT-Client

Eine Falle beim Versionstag, die im Test tatsächlich zugeschlagen hat: Das GitHub-Release heißt v0.26.2, der passende Container-Tag in der GitHub Container Registry heißt aber 0.26.2 ohne führendes v. Der erste Startversuch endete deshalb mit dieser realen Fehlermeldung:

Error response from daemon: failed to resolve reference
"ghcr.io/sysadminsmedia/homebox:v0.26.2":
ghcr.io/sysadminsmedia/homebox:v0.26.2: not found

Compose-Stack anlegen

Legen Sie ein Verzeichnis für den Stack an und erzeugen Sie zuerst die Geheimnisse. Der Pepper ist bei Homebox Pflicht, der Dienst startet ohne ihn nicht.

# Verzeichnis fuer den Stack anlegen
sudo mkdir -p /opt/homebox
cd /opt/homebox
# Datenbankpasswort und API-Key-Pepper erzeugen
{
  echo "POSTGRES_PASSWORD=$(openssl rand -base64 24 | tr -d '/+=' | head -c 24)"
  echo "HBOX_AUTH_API_KEY_PEPPER=$(openssl rand -base64 48 | tr -d '\n')"
} > .env
# Datei nur fuer den Eigentuemer lesbar machen
chmod 600 .env

Die .env sieht danach strukturell so aus. Setzen Sie hier niemals die Beispielwerte ein, sondern die selbst erzeugten:

# Beispielwerte, NICHT uebernehmen
POSTGRES_PASSWORD=bitte-hier-eigenes-passwort-einsetzen
HBOX_AUTH_API_KEY_PEPPER=bitte-hier-eigenen-48-byte-wert-einsetzen

Nun die vollständige compose.yaml. Sie entspricht dem Stack, der im Test gelaufen ist, angereichert um Healthchecks und eine Startreihenfolge:

name: homebox

services:
  homebox-db:
    image: postgres:17-alpine
    container_name: homebox-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: homebox
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: homebox
    volumes:
      - homebox-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U homebox -d homebox"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 20s

  homebox:
    image: ghcr.io/sysadminsmedia/homebox:0.26.2
    container_name: homebox
    restart: unless-stopped
    depends_on:
      homebox-db:
        condition: service_healthy
    environment:
      HBOX_MODE: production
      HBOX_LOG_LEVEL: info
      HBOX_LOG_FORMAT: text
      HBOX_WEB_MAX_UPLOAD_SIZE: 25
      HBOX_OPTIONS_ALLOW_ANALYTICS: "false"
      HBOX_OPTIONS_GITHUB_RELEASE_CHECK: "false"
      HBOX_OPTIONS_ALLOW_REGISTRATION: "true"
      HBOX_OPTIONS_AUTO_INCREMENT_ASSET_ID: "true"
      HBOX_AUTH_API_KEY_PEPPER: ${HBOX_AUTH_API_KEY_PEPPER}
      HBOX_DATABASE_DRIVER: postgres
      HBOX_DATABASE_HOST: homebox-db
      HBOX_DATABASE_PORT: 5432
      HBOX_DATABASE_USERNAME: homebox
      HBOX_DATABASE_PASSWORD: ${POSTGRES_PASSWORD}
      HBOX_DATABASE_DATABASE: homebox
      HBOX_DATABASE_SSL_MODE: disable
      TZ: Europe/Berlin
    volumes:
      - homebox-data:/data
    ports:
      - "127.0.0.1:7745:7745"

volumes:
  homebox-db:
  homebox-data:

Parameter und Pfade im Detail

Alle Einstellungen werden bei Homebox über Umgebungsvariablen mit dem Präfix HBOX_ gesetzt. Die folgende Tabelle erklärt die im Stack verwendeten Werte, geprüft an der Konfigurationsseite der offiziellen Dokumentation:

Variable	Standard	Bedeutung und warum wir sie setzen
`HBOX_MODE`	`development`	Laufzeitverhalten. Für den Betrieb zwingend auf `production` setzen, sonst laufen Sie dauerhaft im Entwicklungsmodus.
`HBOX_WEB_PORT`	`7745`	Port im Container. Die Dokumentation sagt ausdrücklich, dass man diesen unter Docker nicht ändern soll. Die Abbildung nach außen erledigt der `ports`-Eintrag.
`HBOX_WEB_MAX_UPLOAD_SIZE`	`10`	Maximale Uploadgröße in MB. 10 MB sind für Handyfotos von Typenschildern schnell zu wenig, deshalb 25.
`HBOX_AUTH_API_KEY_PEPPER`	leer	Pflichtfeld. Serverseitiges Geheimnis, das in die Hashes der API-Schlüssel einfließt. Mindestens 32 Byte. Ein Wechsel entwertet alle ausgegebenen API-Schlüssel.
`HBOX_DATABASE_DRIVER`	`sqlite3`	Auf `postgres` umstellen, wenn Sie die Datenbank getrennt betreiben wollen.
`HBOX_DATABASE_SSL_MODE`	`require`	Im internen Compose-Netz ohne TLS auf `disable`. Bei einer externen Datenbank über das Netzwerk unbedingt auf `require` oder strenger lassen.
`HBOX_OPTIONS_ALLOW_REGISTRATION`	`true`	Selbstregistrierung. Für die Ersteinrichtung nötig, danach abschalten.
`HBOX_OPTIONS_TRUST_PROXY`	`false`	Muss hinter einem Reverse Proxy auf `true`. Ohne diesen Schalter funktionieren laut Dokumentation Etiketten und weitere Funktionen nicht korrekt.
`HBOX_OPTIONS_AUTO_INCREMENT_ASSET_ID`	`true`	Vergibt automatisch fortlaufende Inventarnummern wie `000-001`.
`HBOX_OPTIONS_GITHUB_RELEASE_CHECK`	`true`	Prüft beim Start auf neue Releases. In abgeschotteten Netzen abschalten, sonst steht ein Verbindungsfehler im Log.
`HBOX_STORAGE_CONN_STRING`	`file:///./`	Speicherort für Anhänge. Unter Docker nicht ändern, alternativ S3-kompatibel oder Google Cloud Storage möglich.
`HBOX_AUTH_RATE_LIMIT_MAX_ATTEMPTS`	`5`	Fehlversuche bis zur Drosselung der Anmeldung, Standardfenster eine Minute, Backoff bis maximal fünf Minuten.

Wichtige Pfade:

/data im Container ist das Datenverzeichnis für Anhänge und Vorschaubilder. Im Stack liegt darauf das benannte Volume homebox-data.
/var/lib/postgresql/data im Datenbankcontainer, hier liegt das Volume homebox-db.
Bei SQLite statt PostgreSQL landet die Datenbank unter ./.data/homebox.db relativ zum Datenverzeichnis, konfigurierbar über HBOX_DATABASE_SQLITE_PATH.

Zu Bind-Mounts ein Hinweis aus der Dokumentation, der im Test nicht angefasst wurde: Wer das rootless- oder hardened-Image mit einem Bind-Mount statt einem Volume betreibt, muss das Zielverzeichnis vorher mit chown 65532:65532 -R auf die Container-UID umstellen, sonst kann der Dienst nicht schreiben.

Installation und erster Start

Vor dem Start lohnt ein Blick auf belegte Ports und eine Syntaxprüfung der Compose-Datei:

# Belegte Ports pruefen
ss -tlnp
# Compose-Datei auf Syntaxfehler pruefen, gibt bei Erfolg nichts aus
docker compose config -q
# Stack im Hintergrund starten
docker compose up -d

Der erste Start zieht die Images und legt das Datenbankschema an. Die Migration lief im Test in wenigen Sekunden durch und endete mit diesen realen Logzeilen:

2026/09/22 00:11:51 OK   20260512130001_add_exports.sql (57.42ms)
2026/09/22 00:11:51 goose: successfully migrated database to version: 20260512130001
12:11AM INF ../go/src/app/app/api/handlers/v1/v1_ctrl_auth.go:100 > registering auth provider name=local
12:11AM INF ../go/src/app/app/api/main.go:275 > Server is running on :7745

Der Zustand des Stacks danach, real beobachtet mit docker compose ps (Namen und Port stammen aus der Testumgebung):

NAME         IMAGE                                   STATUS                    PORTS
hbtest-app   ghcr.io/sysadminsmedia/homebox:0.26.2   Up About a minute (healthy)   127.0.0.1:37450->7745/tcp
hbtest-db    postgres:17-alpine                      Up About a minute (healthy)   5432/tcp

Funktions- und Healthcheck

Das Image bringt einen eigenen Healthcheck mit. Ausgelesen mit docker inspect ergab sich im Test:

{"Test":["CMD","wget","--no-verbose","--tries=1","-O","-",
"http://localhost:7745/api/v1/status"],
"Interval":30000000000,"Timeout":5000000000,
"StartPeriod":5000000000,"Retries":3}

Denselben Endpunkt können Sie für eine externe Überwachung nutzen. Ein echter Aufruf aus dem Test:

# Startseite pruefen
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:7745/
# Statusendpunkt abfragen
curl -s http://127.0.0.1:7745/api/v1/status

Antwort im Test, gekürzt auf die relevanten Felder:

200
{"health":true,"title":"Homebox",
"build":{"version":"v0.26.2","commit":"e01dd737238a3fa7e1a6454b37de6c6fc88c86e4"},
"demo":false,"allowRegistration":true,"oidc":{"enabled":false},
"telemetry":{"enabled":false}}

Für eine Monitoring-Prüfung genügt die Bedingung, dass health auf true steht. Der Endpunkt benötigt keine Anmeldung, liefert aber auch keine sensiblen Daten, und er ist der Weg, wie sich der Container selbst überwacht.

Erstkonfiguration und Inventar aufbauen

Rufen Sie die Oberfläche im Browser auf und legen Sie das erste Konto an. Danach sollten Sie die Selbstregistrierung schließen. Weitere Kollegen kommen über einen Einladungslink in Ihre Gruppe, den Sie im Profilbereich erzeugen. Ohne diesen Link sieht ein neu registrierter Benutzer laut Dokumentation nur seine eigenen Objekte, nicht Ihr gemeinsames Inventar.

Setzen Sie nach der Einrichtung des ersten Kontos in der compose.yaml:

      HBOX_OPTIONS_ALLOW_REGISTRATION: "false"

und starten Sie den Dienst mit docker compose up -d neu.

Ab Version 0.26 hat Homebox sein Datenmodell umgebaut. Objekte und Standorte sind nun beides Entitäten, unterschieden durch einen Entitätstyp. Das ist mehr als Kosmetik, denn es erlaubt eigene Typen wie IT-Asset, Lizenz oder Ersatzteil. Im Test war nach der Installation genau ein Typ vorhanden, nämlich Location mit isLocation: true. Ein eigener Typ für Geräte ließ sich anlegen und danach verwenden.

Eine sinnvolle Struktur für eine kleine IT sieht so aus:

Standorte als Baum: Firmensitz, darin Büro 1 bis 4, Serverraum, Lager. Im Serverraum die einzelnen Racks als Unterstandorte.
Entitätstypen: IT-Asset für Hardware, Lizenz für Softwareverträge, Verbrauchsmaterial für Toner und Kabel.
Tags: Abteilung, Leasing oder Eigentum, Ausmusterungsjahr.
Eigene Felder: Kostenstelle, Buchhaltungs-Inventarnummer, MAC-Adresse.

Die Pflichtfelder eines Geräts füllen Sie einmal sauber aus: Name, Hersteller, Modellnummer, Seriennummer, Kaufdatum, Händler, Kaufpreis und Garantieablauf. Genau dieser Satz Felder wurde im Test über die API an einem Beispielgerät gesetzt und anschließend wieder ausgelesen:

{'assetId': '000-002', 'serialNumber': 'PF-3XK91A',
 'manufacturer': 'Lenovo', 'warrantyExpires': '2029-02-10',
 'purchasePrice': 1249}

Die Inventarnummer 000-002 hat Homebox dabei selbst vergeben, weil HBOX_OPTIONS_AUTO_INCREMENT_ASSET_ID aktiv war. Die Suche nach dem Gerätenamen lieferte im Test genau einen Treffer.

Belege und Fotos hängen Sie direkt an das Gerät. Im Test wurde eine Belegdatei über den Anhang-Endpunkt hochgeladen, die API antwortete mit HTTP 201 und verzeichnete den Anhang danach am Objekt mit erkanntem MIME-Typ. Physisch landete die Datei im Volume unter einem gruppenspezifischen Pfad:

/data/a885875e-f46c-459a-8f9f-d8828a00ed6c/documents/ac251c31360f2112842fb3ac51de26583f44a6d107e4cfe68f78887a81261a8a

Beachten Sie die Konsequenz: Die Dateinamen im Volume sind Hashes, nicht Klarnamen. Ein Backup des Volumes ohne die dazugehörige Datenbank ist praktisch wertlos, weil die Zuordnung ausschließlich in der Datenbank steht.

Etiketten und QR-Codes

Der eigentliche Alltagsnutzen entsteht durch Etiketten. Homebox erzeugt zu jedem Objekt ein druckfertiges Etikett mit QR-Code, das beim Scannen direkt auf den Datensatz führt. Im Test lieferte der Etikettenendpunkt ein PNG:

label HTTP 200 type=image/png size=11283
label.png: PNG image data, 526 x 242, 8-bit/color RGB, non-interlaced

Die Maße stammen aus den Standardwerten HBOX_LABEL_MAKER_WIDTH (526) und HBOX_LABEL_MAKER_HEIGHT (200), wobei HBOX_LABEL_MAKER_DYNAMIC_LENGTH standardmäßig aktiv ist und die Höhe bei längeren Texten vergrößert. Über HBOX_LABEL_MAKER_ADDITIONAL_INFORMATION lässt sich eine feste Zusatzzeile auf jedes Etikett drucken, etwa der Firmenname oder eine Rückgabe-Telefonnummer. Direktes Drucken aus der Anwendung heraus ist laut Dokumentation nur aktiv, wenn HBOX_LABEL_MAKER_PRINT_COMMAND gesetzt ist. Das war im Test nicht der Fall, der Statusendpunkt meldete korrekt "labelPrinting":false. Die Druckanbindung an einen Etikettendrucker ist also laut offizieller Dokumentation vorgesehen, wurde hier aber nicht selbst getestet.

Ablaufdaten im Blick behalten

Garantien laufen unbemerkt ab, das ist der häufigste Grund, warum ein Inventar seinen Wert verliert. Homebox bietet dafür zwei Wege. Erstens Benachrichtigungen über konfigurierbare Notifier, die laut Dokumentation gegen allgemeine Endpunkte sprechen und über HBOX_NOTIFIER_ALLOW_NETS bzw. HBOX_NOTIFIER_BLOCK_NETS auf erlaubte Netze eingeschränkt werden. Standardmäßig sind Cloud-Metadaten-Adressen und Bogon-Netze blockiert, was eine sinnvolle Absicherung gegen Server-Side Request Forgery ist. Zweitens der CSV-Export, den Sie regelmäßig ziehen und auswerten können.

Der Export funktionierte im Test und lieferte eine Kopfzeile mit allen relevanten Spalten:

HB.import_ref,HB.parent_import_ref,HB.location,HB.tags,HB.asset_id,
HB.archived,HB.url,HB.name,HB.quantity,HB.description,HB.insured,
HB.notes,HB.purchase_price,HB.purchase_from,HB.purchase_date,
HB.manufacturer,HB.model_number,HB.serial_number,HB.lifetime_warranty,
HB.warranty_expires,HB.warranty_details,HB.sold_to,HB.sold_price,
HB.sold_date,HB.sold_notes

Derselbe Spaltensatz dient auch dem Import. Wer ein bestehendes Inventar aus einer Tabelle übernimmt, baut die Kalkulation auf genau diese Spaltennamen um und spart sich damit die Handarbeit. Die Felder HB.import_ref und HB.parent_import_ref bilden dabei die Hierarchie ab.

Sichere Netzwerkfreigabe und Reverse Proxy

In der obigen compose.yaml ist der Port bewusst als 127.0.0.1:7745:7745 gebunden. Damit ist der Dienst nur lokal erreichbar und nicht versehentlich aus dem ganzen Netz. Genau diese Bindung lief im Test. Der Zugriff von außen gehört hinter einen Reverse Proxy mit TLS.

Entscheidend, und in der Dokumentation als Warnung hervorgehoben: Sobald ein Reverse Proxy davor steht, muss HBOX_OPTIONS_TRUST_PROXY auf true stehen. Ohne diesen Schalter wertet Homebox die weitergeleiteten Header nicht aus, erkennt HTTPS nicht und Etiketten sowie weitere Funktionen arbeiten laut Dokumentation nicht korrekt.

Der zweite Punkt sind WebSockets. Homebox nutzt den Endpunkt /api/v1/ws/events für Live-Aktualisierungen. Im Test antwortete dieser ohne Anmeldung erwartungsgemäß mit HTTP 401, existiert also und ist nicht offen. Nginx und Apache brauchen dafür explizite Upgrade-Header, Traefik und Caddy erledigen das laut Dokumentation automatisch.

Die offizielle Nginx-Konfiguration für den HTTPS-Fall sieht so aus:

server {
    listen 443 ssl http2;
    server_name inventar.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:7745;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
    }
}

Wer Traefik einsetzt, arbeitet mit Labels am Dienst. Der entscheidende Wert ist der interne Port 7745:

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.homebox.rule=Host(`inventar.example.com`)"
      - "traefik.http.routers.homebox.entrypoints=websecure"
      - "traefik.http.routers.homebox.tls.certresolver=letsencrypt"
      - "traefik.http.services.homebox.loadbalancer.server.port=7745"

Diese Proxy-Konfigurationen stammen aus der offiziellen Dokumentation und wurden im Rahmen dieser Anleitung nicht selbst getestet. Getestet wurde ausschließlich der direkte Zugriff über die lokale Portbindung.

Drei weitere Absicherungen, die Sie nicht vergessen sollten:

Selbstregistrierung nach der Einrichtung abschalten, sonst kann jeder mit Zugriff auf die URL ein Konto anlegen.
Die Anmelde-Drosselung ist standardmäßig aktiv, fünf Fehlversuche pro Minute mit ansteigendem Backoff bis fünf Minuten. Wer sie über HBOX_AUTH_RATE_LIMIT_ENABLED abschaltet, öffnet das Login für Rateversuche.
HBOX_DEBUG_ENABLED im Betrieb auf dem Standard false lassen. Der Debug-Listener bindet laut Dokumentation zwar nur auf 127.0.0.1, gibt aber pprof- und expvar-Daten preis.

Backup und Wiederherstellung

Ein Backup braucht bei diesem Stack zwei Teile: die PostgreSQL-Datenbank mit allen Metadaten und das Datenvolume mit Anhängen und Vorschaubildern. Nur beides zusammen ergibt einen wiederherstellbaren Zustand. Beide Schritte wurden im Test durchgeführt.

# Datenbank im eigenen Format sichern
docker compose exec -T homebox-db pg_dump -U homebox -d homebox -Fc > homebox.dump
# Anhaenge aus dem Volume sichern
docker run --rm -v homebox_homebox-data:/data:ro -v "$PWD":/backup alpine \
  tar czf /backup/homebox-data.tar.gz -C /data .

Beide Befehle liefen im Test erfolgreich. Der Dump umfasste 47856 Byte, das Datenarchiv 468 Byte, was bei einem einzelnen Testanhang plausibel ist.

Ein Backup ohne geprüfte Wiederherstellung ist wertlos. Der Test hat den Weg deshalb vollständig durchgespielt: Anwendung stoppen, Datenbank verwerfen, neu anlegen, Dump einspielen, Datensatz zurücklesen. Der Stopp der Anwendung ist zwingend, sonst blockieren offene Verbindungen das Löschen der Datenbank.

# Anwendung stoppen, Datenbank laeuft weiter
docker compose stop homebox
# Datenbank verwerfen und leer neu anlegen
docker compose exec -T homebox-db psql -U homebox -d postgres \
  -c "DROP DATABASE homebox;" -c "CREATE DATABASE homebox OWNER homebox;"
# Dump einspielen, bei jedem Fehler abbrechen
docker compose exec -T homebox-db pg_restore -U homebox -d homebox --exit-on-error < homebox.dump
# Gegenprobe direkt in der Datenbank
docker compose exec -T homebox-db psql -U homebox -d homebox -Atc \
  "SELECT name, serial_number, warranty_expires FROM entities WHERE name='ThinkPad T14 Gen 4';"
# Anwendung wieder starten
docker compose start homebox

Die Gegenprobe lieferte im Test genau den vorher angelegten Datensatz zurück:

DROP DATABASE
CREATE DATABASE
ThinkPad T14 Gen 4|PF-3XK91A|2029-02-10 00:00:00+00

Nach dem Neustart antwortete die Oberfläche wieder mit HTTP 200. Damit ist der Rückweg belegt und nicht nur behauptet. Wenn Sie sich tiefer mit den Dump-Formaten und den Fallstricken bei Rollen und Rechten befassen wollen, haben wir dazu eine eigene Anleitung zu pg_dump und pg_restore.

Für den regelmäßigen Betrieb: Legen Sie den Dump auf ein Medium außerhalb des Hosts und prüfen Sie die Wiederherstellung mindestens einmal pro Quartal auf einem Testsystem. Ein Dump, der nie eingespielt wurde, ist eine Vermutung.

Updates und Rollback

Der Update-Ablauf ist unspektakulär, solange Sie vorher sichern:

# Zuerst sichern, siehe vorheriger Abschnitt
docker compose exec -T homebox-db pg_dump -U homebox -d homebox -Fc > homebox-vor-update.dump
# Neue Images holen
docker compose pull
# Stack mit neuen Images neu erzeugen
docker compose up -d
# Logs auf Migrationsfehler pruefen
docker compose logs homebox --tail 50

Setzen Sie im produktiven Betrieb einen festen Versionstag statt latest, so wie in der obigen compose.yaml. Nur dann wissen Sie hinterher, worauf Sie zurückrollen. Denken Sie an die Tag-Schreibweise ohne v.

Die harte Grenze beim Rollback sind Datenbankmigrationen. Homebox nutzt goose und spielt beim Start alle ausstehenden Migrationen ein, im Test waren das über zwanzig Schritte bis zur Version 20260512130001. Ein Rückschritt auf ein älteres Image findet dann ein Schema vor, das neuer ist als der Code. Ein Rollback bedeutet deshalb praktisch immer: altes Image starten und den Dump von vor dem Update einspielen. Nur das Image zurückzusetzen genügt nicht.

Ein Sonderfall verdient Aufmerksamkeit: Der Umbau von Objekten und Standorten zu Entitäten hat die REST-Schnittstelle grundlegend verändert. Die Endpunkte /v1/items/* und /v1/locations/* wurden laut der Migrationsanleitung im Repository entfernt und durch /v1/entities/* ersetzt. Das war im Test unmittelbar spürbar: Ein Aufruf des alten Endpunkts /api/v1/locations antwortete mit 404 page not found. Wer eigene Skripte oder Integrationen gegen die API gebaut hat, muss diese vor dem Update anpassen.

Typische Fehler mit Diagnose und Lösung

Alle folgenden Fehlermeldungen wurden im Test absichtlich provoziert und stammen wörtlich aus der Konsole.

Fehlerbild	Ursache	Lösung
`failed to resolve reference "ghcr.io/...homebox:v0.26.2": not found`	Container-Tag mit führendem `v` geschrieben	Tag ohne `v` verwenden, also `0.26.2`. Verfügbare Tags notfalls über die Registry-API prüfen.
`panic: auth.api_key_pepper must be set to at least 32 bytes`	`HBOX_AUTH_API_KEY_PEPPER` fehlt oder ist zu kurz	Wert mit `openssl rand -base64 48` erzeugen und in die `.env` eintragen. Die Meldung erscheint bei leerem und bei zu kurzem Wert gleichermaßen.
`Bind for 127.0.0.1:7745 failed: port is already allocated`	Der Host-Port ist belegt	Mit `ss -tlnp` prüfen und links im `ports`-Eintrag einen freien Port wählen. Die rechte Seite bleibt 7745.
`dial tcp 127.0.0.1:5432: connect: connection refused` gefolgt von `panic`	`HBOX_DATABASE_HOST` steht auf `localhost`	Der Datenbankhost ist aus Sicht des Containers der Dienstname, hier `homebox-db`. `localhost` zeigt auf den Container selbst.
Leerer Wert bei `assetId` nach einem `PUT`	Ein vollständiges Update ohne `assetId` im Rumpf leert das Feld	Bei Schreibzugriffen über die API die Inventarnummer mitsenden oder nur teilweise per `PATCH` aktualisieren. Im Test wurde die automatisch vergebene Nummer `000-002` auf diesem Weg versehentlich geleert.
`404 page not found` bei `/api/v1/locations`	Endpunkt wurde durch die Entitäts-API ersetzt	`/api/v1/entities` verwenden, für Standorte mit dem Parameter `?isLocation=true`.
Container startet, Weboberfläche zeigt falsche Protokolle oder Etiketten scheitern	Reverse Proxy ohne `HBOX_OPTIONS_TRUST_PROXY`	Variable auf `true` setzen und sicherstellen, dass der Proxy `X-Forwarded-For` und `X-Forwarded-Proto` sendet. Laut Dokumentation, im Test nicht reproduziert.
Im Log steht `failed to get latest github release`	Host hat keinen Internetzugang	Harmlos. `HBOX_OPTIONS_GITHUB_RELEASE_CHECK` auf `false` setzen, dann verschwindet die Meldung.

Für die Diagnose generell hilfreich: docker compose logs homebox --tail 50 zeigt die Startphase inklusive Migrationen, docker compose ps verrät, ob der Healthcheck greift, und curl -s http://127.0.0.1:7745/api/v1/status beantwortet innerhalb einer Sekunde, ob die Anwendung wirklich arbeitsfähig ist.

Saubere Deinstallation

Ein deutlicher Hinweis vorweg: Der folgende Ablauf löscht Ihr komplettes Inventar samt aller hochgeladenen Belege und Fotos unwiderruflich. Ziehen Sie vorher ein Backup, wenn auch nur der Hauch einer Chance besteht, dass Sie die Daten noch brauchen.

# Nur Container und Netzwerk entfernen, Daten bleiben erhalten
docker compose down
# Alles entfernen, einschliesslich der benannten Volumes mit allen Daten
docker compose down -v --remove-orphans
# Images gezielt entfernen
docker rmi ghcr.io/sysadminsmedia/homebox:0.26.2 postgres:17-alpine
# Kontrolle, dass keine Volumes zurueckbleiben
docker volume ls

Dieser Ablauf wurde nach dem Test genau so ausgeführt. docker compose down -v --remove-orphans entfernte beide Container, beide Volumes und das Netzwerk, danach meldete docker volume ls keine verbliebenen Volumes mehr. Das Stack-Verzeichnis mit compose.yaml und .env müssen Sie anschließend selbst löschen.

Passende Anleitungen auf S-EDV

Snipe-IT für die IT-Inventarisierung ist die richtige Wahl, wenn Sie Lizenzplätze zählen, Geräte an Mitarbeitende ausgeben und einen Audit-Trail brauchen.
GLPI als Helpdesk und IT-Asset-Management geht einen Schritt weiter und verbindet Inventar mit Ticketsystem und agentenbasierter Erfassung.
Docker Compose absichern mit Secrets, Healthchecks und Non-Root zeigt, wie Sie die hier verwendete .env durch echte Docker-Secrets ersetzen.
PostgreSQL sichern und wiederherstellen mit pg_dump und pg_restore vertieft den Backup-Abschnitt dieser Anleitung.
Traefik als Reverse Proxy mit HTTPS einrichten liefert die fehlende TLS-Schicht vor Homebox.

Fazit

Homebox ist kein Ersatz für eine CMDB, und es versucht auch gar nicht, einer zu sein. Genau darin liegt sein Wert für kleine Unternehmen: Das System ist in einer Viertelstunde installiert, braucht kaum Ressourcen und ist so einfach, dass Kollegen ohne IT-Hintergrund es tatsächlich pflegen. Ein Inventar, das gepflegt wird, schlägt jedes ausgefeilte System, das nach drei Monaten veraltet ist.

Die Empfehlung für den Einstieg: mit PostgreSQL starten statt mit SQLite, den Versionstag festnageln, Selbstregistrierung nach der Einrichtung schließen, den Dienst nur über einen Reverse Proxy mit TLS erreichbar machen und das Backup einmal komplett durchspielen, bevor echte Daten darin liegen. Wenn Ihr Bedarf später über Seriennummern und Garantiedaten hinauswächst, ist der CSV-Export der Weg zu einem größeren System.

Quellen

GitHub: sysadminsmedia/homebox, Repository und README, Kennzahlen über die GitHub-API abgerufen am 22. September 2026
GitHub Releases: Homebox v0.26.2, veröffentlicht am 14. Juni 2026, abgerufen am 22. September 2026
Offizielle Dokumentation: Installation mit Docker und Docker Compose
Offizielle Dokumentation: Umgebungsvariablen und Konfiguration
Offizielle Dokumentation: PostgreSQL als Datenbank
Offizielle Dokumentation: Reverse Proxy mit Nginx, Traefik und Caddy
Offizielle Dokumentation: API-Migration durch die Zusammenführung von Objekten und Standorten