NetBox 4.7 auf dem Synology NAS installieren: IPAM und Netzwerkdokumentation

NetBox ist eine Datenbank für die Netzwerkdokumentation: IP-Adressen, Subnetze (Prefixes), VLANs, Geräte, Racks und Kabel, jeweils mit REST-API und GraphQL. Damit ersetzen Sie gewachsene Excel-Listen durch eine durchsuchbare, verknüpfte Quelle. Das Projekt netbox-community stellt mit netbox-docker einen offiziellen Compose-Stack bereit, den Sie auf einem Synology NAS als Projekt im Container Manager betreiben. Die Grundlagen zum IP-Adressplan finden Sie in Netzwerkdokumentation und IP-Adressplan (IPAM) erstellen.

Voraussetzungen

• Synology NAS mit DSM 7.2 oder neuer und installiertem Container Manager. Das Image netboxcommunity/netbox gibt es für amd64 und arm64.
• 4 GB RAM als Untergrenze für die fünf Dienste, 8 GB, wenn weitere Container laufen.
• Mindestens 5 GB frei für Images und Daten, mehr bei umfangreicher Dokumentation.
• File Station und das Paket Text-Editor für Ordner und Dateien.
• SSH nur für Logs, Backup und den API-Test (SSH auf dem Synology NAS aktivieren). Die Zufallswerte können Sie auch mit Ihrem Passwortmanager erzeugen.

Eckdaten auf einen Blick

Parameter	Wert
NetBox-Image	netboxcommunity/netbox:v4.7-5.1.1 (NetBox 4.7.x, netbox-docker 5.1.1)
Datenbank	postgres:18-alpine (NetBox 4.7 verlangt PostgreSQL 15 oder neuer)
Queue und Cache	valkey/valkey:9.1-alpine (NetBox 4.7 verlangt Redis 6 oder neuer)
Port	8000 außen, 8080 im Container
Medien	/volume1/docker/netbox/media
Datenbankdateien	/volume1/docker/netbox/postgres
Valkey	/volume1/docker/netbox/redis und redis-cache

Das Tag-Schema lautet vNetBox-Version-netbox-docker-Version. v4.7-5.1.1 liefert die jeweils neueste NetBox 4.7.x mit den Hilfsdateien von netbox-docker 5.1.1; am 14.10.2026 ist das NetBox 4.7.3.

Schritt 1: Verzeichnisstruktur anlegen

Legen Sie in der File Station im Ordner docker den Ordner netbox an und darin die Unterordner env, media, postgres, redis und redis-cache. Bind-Mounts müssen vor dem ersten Start existieren, sonst bricht der Container Manager mit einem Mount-Fehler ab.

NetBox läuft im Container laut Dockerfile als Benutzer netbox (UID 999, Gruppe 0). Damit Uploads funktionieren, braucht der Ordner media Schreibrechte für diesen Benutzer. Wie Sie Rechte für Container-Ordner setzen, zeigt Docker-Ordner und Berechtigungen auf dem Synology NAS.

Verifizieren: /volume1/docker/netbox zeigt in der File Station die fünf Unterordner env, media, postgres, redis und redis-cache.

Schritt 2: Umgebungsvariablen-Dateien erstellen

netbox-docker liest seine Konfiguration aus Env-Dateien. Die Vorlagen im Repository enthalten Beispielpasswörter und einen Beispiel-SECRET_KEY; übernehmen Sie davon keinen Wert. Erzeugen Sie zufällige Werte, etwa per SSH:

python3 -c 'import secrets; print(secrets.token_urlsafe(50))'
python3 -c 'import secrets,string; a=string.ascii_letters+string.digits; print("".join(secrets.choice(a) for _ in range(12)))'
python3 -c 'import secrets,string; a=string.ascii_letters+string.digits; print("".join(secrets.choice(a) for _ in range(40)))'

Die erste Zeile führen Sie zweimal aus (für SECRET_KEY und API_TOKEN_PEPPER_1), die zweite liefert den 12-stelligen Schlüssel, die dritte den 40-stelligen Token des Superusers. Legen Sie mit dem Text-Editor env/netbox.env an:

DB_HOST=postgres
DB_NAME=netbox
DB_USER=netbox
DB_PASSWORD=IHR_DB_PASSWORT
REDIS_HOST=redis
REDIS_PASSWORD=IHR_REDIS_PASSWORT
REDIS_DATABASE=0
REDIS_CACHE_HOST=redis-cache
REDIS_CACHE_PASSWORD=IHR_CACHE_PASSWORT
REDIS_CACHE_DATABASE=1
SECRET_KEY=IHR_SECRET_KEY
API_TOKEN_PEPPER_1=IHR_PEPPER
MEDIA_ROOT=/opt/netbox/netbox/media
SKIP_SUPERUSER=false
SUPERUSER_NAME=admin
SUPERUSER_EMAIL=admin@example.com
SUPERUSER_PASSWORD=IHR_ADMIN_PASSWORT
SUPERUSER_API_KEY=IHR_12_ZEICHEN_KEY
SUPERUSER_API_TOKEN=IHR_40_ZEICHEN_TOKEN
TZ=Europe/Berlin

Dazu drei kurze Dateien. env/postgres.env:

POSTGRES_DB=netbox
POSTGRES_USER=netbox
POSTGRES_PASSWORD=IHR_DB_PASSWORT

env/redis.env mit der Zeile REDIS_PASSWORD=IHR_REDIS_PASSWORT und env/redis-cache.env mit REDIS_PASSWORD=IHR_CACHE_PASSWORT. Beide Valkey-Dienste lesen laut offizieller Compose-Datei die Variable REDIS_PASSWORD, jeweils mit eigenem Wert.

Der Pepper ist für v2-API-Tokens nötig: Ohne API_TOKEN_PEPPER_1 legt das Superuser-Skript des Images keinen Token an. Ändern Sie den Pepper später nicht, sonst werden bestehende v2-Tokens ungültig.

Verifizieren: Im Ordner env liegen netbox.env, postgres.env, redis.env und redis-cache.env. DB_PASSWORD gleicht POSTGRES_PASSWORD, REDIS_PASSWORD und REDIS_CACHE_PASSWORD aus netbox.env gleichen den Werten in redis.env bzw. redis-cache.env, und kein Platzhalter ist übrig.

Schritt 3: Compose-Datei vorbereiten

Die folgende Datei folgt der offiziellen docker-compose.yml von netbox-docker 5.1.1. Abweichungen: Bind-Mounts statt benannter Volumes, damit die Daten in der File Station sichtbar sind, die Portfreigabe aus der Beispieldatei docker-compose.override.yml.example und restart: unless-stopped.

services:
  netbox: &netbox
    image: docker.io/netboxcommunity/netbox:v4.7-5.1.1
    depends_on:
      - postgres
      - redis
      - redis-cache
    env_file: env/netbox.env
    user: "netbox:root"
    healthcheck:
      test: /opt/netbox/health.sh
      start_period: 90s
      timeout: 3s
      interval: 15s
    volumes:
      - /volume1/docker/netbox/media:/opt/netbox/netbox/media:rw
    ports:
      - "8000:8080"
    restart: unless-stopped

  netbox-worker:
    <<: *netbox
    depends_on:
      netbox:
        condition: service_healthy
    command:
      - /opt/netbox/venv/bin/python
      - /opt/netbox/netbox/manage.py
      - rqworker
    healthcheck:
      test: ps -aux | grep -v grep | grep -q rqworker || exit 1
      start_period: 20s
      timeout: 3s
      interval: 15s
    ports: []

  postgres:
    image: docker.io/postgres:18-alpine
    env_file: env/postgres.env
    volumes:
      - /volume1/docker/netbox/postgres:/var/lib/postgresql
    healthcheck:
      test: pg_isready -q -t 2 -d $$POSTGRES_DB -U $$POSTGRES_USER
      start_period: 20s
      timeout: 30s
      interval: 10s
      retries: 5
    restart: unless-stopped

  redis:
    image: docker.io/valkey/valkey:9.1-alpine
    command:
      - sh
      - -c
      - valkey-server --appendonly yes --requirepass $$REDIS_PASSWORD
    env_file: env/redis.env
    volumes:
      - /volume1/docker/netbox/redis:/data
    healthcheck: &redis-healthcheck
      test: '[ $$(valkey-cli --pass "$${REDIS_PASSWORD}" ping) = ''PONG'' ]'
      start_period: 5s
      timeout: 3s
      interval: 1s
      retries: 5
    restart: unless-stopped

  redis-cache:
    image: docker.io/valkey/valkey:9.1-alpine
    command:
      - sh
      - -c
      - valkey-server --requirepass $$REDIS_PASSWORD
    env_file: env/redis-cache.env
    volumes:
      - /volume1/docker/netbox/redis-cache:/data
    healthcheck: *redis-healthcheck
    restart: unless-stopped

Zwei Punkte entscheiden über den Start: Intern lauscht NetBox (Applikationsserver Granian) auf Port 8080, die Freigabe lautet deshalb 8000:8080. Und das Image postgres:18 erwartet das Volume unter /var/lib/postgresql, nicht mehr unter /var/lib/postgresql/data.

Verifizieren: Der Text enthält die Image-Tags v4.7-5.1.1, 18-alpine und 9.1-alpine, die Zeile "8000:8080" und vier Bind-Mounts unter /volume1/docker/netbox.

Schritt 4: Projekt im Container Manager erstellen und starten

Öffnen Sie den Container Manager und wählen Sie Projekt > Erstellen. Projektname netbox, Pfad /volume1/docker/netbox, als Quelle „docker-compose.yml erstellen“; fügen Sie den Inhalt aus Schritt 3 ein. Bestätigen Sie die Zusammenfassung und lassen Sie das Projekt nach dem Assistenten starten.

Beim ersten Start lädt DSM die Images, und NetBox legt alle Tabellen an. Das Einstiegsskript des Images wartet auf die Datenbank, wendet die Migrationen an, legt den Superuser an und meldet dann Initialisation is done.. Der Worker startet erst, wenn NetBox als gesund gilt. Die Beispieldatei von netbox-docker weist darauf hin, dass der erste Start länger dauert als spätere und der start_period von 90 Sekunden dafür höher liegen sollte, je nach Leistung der Datenbank.

Den Fortschritt sehen Sie im Container Manager im Protokoll des Containers netbox-netbox-1 oder per SSH:

cd /volume1/docker/netbox
sudo docker compose logs -f netbox

Verifizieren: Das Protokoll zeigt Initialisation is done., und unter Projekt > netbox laufen alle fünf Container. Per SSH zeigt sudo docker compose ps für alle Dienste den Zustand healthy.

Schritt 5: Zugriff über die DSM-Firewall erlauben

Ist die DSM-Firewall aktiv, ergänzen Sie unter Systemsteuerung > Sicherheit > Firewall im aktiven Profil eine Regel, die TCP-Port 8000 nur aus Ihrem lokalen Subnetz (zum Beispiel 192.168.1.0/24) zulässt. Eine Freigabe ins Internet ist für eine Dokumentationsdatenbank nicht nötig; für HTTPS im LAN eignet sich Nginx Proxy Manager auf der Synology.

Verifizieren: Von einem Rechner im LAN öffnet http://NAS-IP:8000 die NetBox-Anmeldeseite, von außerhalb des freigegebenen Subnetzes nicht.

Schritt 6: Anmelden und Superuser prüfen

Mit SKIP_SUPERUSER=false legt das Image beim ersten Start den Benutzer aus SUPERUSER_NAME mit dem Passwort aus SUPERUSER_PASSWORD an. Melden Sie sich damit an. Haben Sie SKIP_SUPERUSER=true gesetzt, wie es die Vorlage vorgibt, legen Sie den Benutzer nach der README von netbox-docker per SSH an:

cd /volume1/docker/netbox
sudo docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser

Entfernen Sie nach der ersten Anmeldung SUPERUSER_PASSWORD aus netbox.env oder ändern Sie das Passwort in der Oberfläche, damit kein gültiges Kennwort im Klartext auf dem NAS liegt.

Verifizieren: Nach der Anmeldung sehen Sie das Dashboard, und in der Benutzerverwaltung unter Admin steht Ihr Konto mit Superuser-Status.

Schritt 7: Erstes Prefix anlegen

Legen Sie unter Organization > Sites zuerst einen Standort an (zum Beispiel „Büro“). Anschließend öffnen Sie IPAM > Prefixes, klicken auf Add und tragen Ihr erstes Subnetz ein, etwa 192.168.1.0/24 mit Status „Active“, Beschreibung „Büro-LAN“ und dem Standort als Geltungsbereich. Bei deutscher Oberfläche heißen die Menüs entsprechend übersetzt. Beginnen Sie mit dem Netz, über das Sie am häufigsten Auskunft geben müssen, und tragen Sie danach feste Adressen von Servern, Druckern und Netzwerkgeräten ein. Hilfe zur Netzplanung bietet Subnetting und CIDR verständlich erklärt.

Verifizieren: Das Prefix erscheint in der Prefix-Liste mit Status „Active“, und die Detailansicht zeigt die Auslastung und die verfügbaren IP-Adressen.

Schritt 8: API-Token testen

NetBox empfiehlt ausschließlich v2-Tokens; v1-Tokens gelten seit NetBox 4.6 als veraltet und entfallen mit NetBox 5.0. Ein v2-Token wird im Header als Bearer nbt_SCHLÜSSEL.TOKEN übergeben. Den Superuser-Token haben Sie in Schritt 2 aus SUPERUSER_API_KEY und SUPERUSER_API_TOKEN festgelegt:

curl -s -H "Authorization: Bearer nbt_IHR_12_ZEICHEN_KEY.IHR_40_ZEICHEN_TOKEN" \
  -H "Accept: application/json" http://NAS-IP:8000/api/status/

Den Klartext eines Tokens zeigt NetBox laut Doku nur beim Anlegen; geht er verloren, legen Sie in der Oberfläche unter den API-Tokens einen neuen an. Entfernen Sie SUPERUSER_API_TOKEN danach ebenfalls aus der Env-Datei.

Verifizieren: Die Antwort ist ein JSON-Objekt, dessen Feld netbox-version eine Version 4.7.x nennt.

Schritt 9: Sichern und aktualisieren

Sichern Sie vor jedem Update Datenbank und Medien. Legen Sie dafür den Ordner backup an:

cd /volume1/docker/netbox
sudo docker compose exec -T postgres pg_dump -U netbox -Fc netbox > backup/netbox_$(date +%Y%m%d).dump

Hyper Backup sichert anschließend backup, media und env auf ein externes Ziel. Die Valkey-Daten sind Queue und Cache. Laut Release Notes 4.7.1 fehlten bei der Wiederherstellung eines Dumps aus 4.7.0 Trigger für hierarchische Objekte; erstellen Sie Dumps deshalb mit 4.7.1 oder neuer.

Für ein Update ändern Sie den Tag nach den Release Notes von netbox-docker, übernehmen dabei auch dessen Änderungen an Compose- und Env-Dateien und erstellen das Projekt im Container Manager neu, damit das neue Image geladen wird. Der Container führt die Migrationen beim Start selbst aus. Ein Wechsel auf eine neue Hauptversion (5.0) ist laut NetBox-Doku nur von der jeweils letzten Minor-Version aus möglich.

Wer von 4.6 kommt, beachtet die Release Notes 4.7: PostgreSQL 15 und Redis 6 sind Pflicht, hierarchische Objekte wandern auf die PostgreSQL-Erweiterung ltree, und diese Migration sperrt die betroffenen Tabellen, auf großen Installationen mehrere Minuten lang. Planen Sie ein Wartungsfenster ein und lassen Sie laufende Hintergrundaufgaben vorher abarbeiten. Einen bisher funktionierenden PostgreSQL-Mount ändern Sie bei einer laufenden Installation nicht.

Verifizieren: Die Dump-Datei ist größer als 0 Byte. Nach einem Update zeigt /api/status/ die neue Version, alle fünf Container sind healthy, und Prefixes, Standorte und Geräte sind vollständig.

Troubleshooting / Typische Fehler

• Worker startet beim ersten Mal nicht („dependency failed to start“): Die Migrationen dauern länger, als der Healthcheck erlaubt. Projekt erneut starten oder start_period beim Dienst netbox erhöhen.
• „Connection refused“ auf Port 8000: Die Portfreigabe lautet nicht 8000:8080, oder die DSM-Firewall blockiert.
• PostgreSQL 18 startet nicht und verweist auf das Datenverzeichnis: Das Volume ist unter /var/lib/postgresql/data eingebunden statt unter /var/lib/postgresql.
• „password authentication failed“: DB_PASSWORD und POSTGRES_PASSWORD weichen ab. Das Postgres-Image übernimmt das Passwort nur beim ersten Start mit leerem Datenordner.
• NetBox wartet dauerhaft auf Valkey: REDIS_PASSWORD bzw. REDIS_CACHE_PASSWORD in netbox.env passt nicht zur jeweiligen Valkey-Env-Datei.
• Kein API-Token für den Superuser: Im Log steht No API token was created as API_TOKEN_PEPPERS is not set. Pepper setzen und den Token in der Oberfläche anlegen.
• Webhooks und Skripte bleiben hängen: Der Dienst netbox-worker läuft nicht.
• Uploads schlagen fehl: Der Ordner media ist für UID 999 nicht beschreibbar.

Häufige Fragen

Brauchen Sie alle fünf Dienste?

NetBox, PostgreSQL und beide Valkey-Instanzen sind für den Betrieb nötig. Der Worker verarbeitet Hintergrundaufgaben wie Webhooks und Skripte; ohne ihn bleiben diese in der Warteschlange.

Welche Synology-Modelle eignen sich?

Modelle mit Container Manager (DSM 7.2 oder neuer) und x86_64- oder ARM64-CPU, da die Images für amd64 und arm64 vorliegen. Entscheidend ist der Arbeitsspeicher, siehe Voraussetzungen.

Warum nicht einfach latest?

netbox-docker bindet seine Hilfsdateien an eine NetBox-Version. Mit festem Tag entscheiden Sie selbst, wann Sie Release Notes lesen, sichern und Compose-Änderungen übernehmen.

Was unterscheidet das Image von LinuxServer.io?

Das Image netboxcommunity/netbox stammt vom NetBox-Projekt selbst und wird über Env-Dateien konfiguriert. Das LinuxServer.io-Image ist ein Drittanbieter-Image mit eigenem Konfigurationskonzept; diese Anleitung gilt nur für das offizielle Image.

Fazit

Mit dem offiziellen netbox-docker-Stack läuft NetBox 4.7 auf einem Synology NAS reproduzierbar und lässt sich über feste Tags kontrolliert aktualisieren. Wichtig sind eigene Zufallswerte statt der Vorlagen, der richtige Port und PostgreSQL-Pfad sowie ein Dump vor jedem Update. Den Nutzen bringt erst die Pflege: Beginnen Sie mit einem Subnetz und erweitern Sie die Dokumentation schrittweise. Für Helpdesk und Inventar ergänzen GLPI und Snipe-IT auf demselben NAS.

Weiterführende Anleitungen und Quellen

• Netzwerkdokumentation und IP-Adressplan (IPAM) erstellen
• Subnetting und CIDR verständlich erklärt
• GLPI auf dem Synology NAS: Helpdesk und IT-Asset-Management
• Snipe-IT auf dem Synology NAS: IT-Inventarisierung
• Nginx Proxy Manager auf der Synology: Reverse Proxy und SSL
• netbox-community/netbox-docker (README, docker-compose.yml, env-Vorlagen)
• netbox-docker Releases
• NetBox 4.7 Release Notes
• Synology Knowledge Center: Container Manager, Projekt