NetBox auf dem Synology NAS installieren: IPAM und Netzwerkdokumentation

Wer im KMU die Netzwerkdokumentation noch in Excel-Tabellen oder einem Wiki führt, kennt das Problem: Einträge veralten, Subnetze überschneiden sich, und niemand weiß mehr, welche IP-Adresse wofür reserviert ist. NetBox löst dieses Problem mit einer strukturierten, durchsuchbaren Datenbank für IP-Adressen, Subnetze (Prefixes), VLANs, Geräte, Racks und Verbindungen – komplett mit REST-API und GraphQL. Da das offizielle Projekt einen Docker-Compose-Stack mitliefert, lässt er sich auf einem Synology NAS als Container-Manager-Projekt betreiben, ohne dass ein dedizierter Linux-Server nötig wäre. Diese Anleitung führt dich Schritt für Schritt durch die Installation des offiziellen netboxcommunity/netbox-Images – nicht des häufig zitierten LinuxServer.io-Drittanbieter-Images –, erklärt die Unterschiede und stellt sicher, dass du nach jedem Schritt weißt, ob alles funktioniert.

Voraussetzungen

• Synology NAS mit x86_64-CPU (Intel Celeron/Core, AMD Ryzen) und mindestens 4 GB RAM (empfohlen: 8 GB)
• DSM 7.2 oder höher mit installiertem Container Manager (Paketcenter)
• Mindestens 5 GB freier Speicherplatz für Images und Daten (empfohlen: 20 GB für Wachstum)
• SSH-Zugang zum NAS (für Verzeichnis-Erstellung und optionale manage.py-Befehle)
• Fester LAN-Port oder DDNS-Hostname für stabilen Zugriff
• Grundkenntnisse in Docker Compose und Umgebungsvariablen

Schritt 1: Verzeichnisstruktur anlegen

Der Stack verwendet Bind-Mounts unter /volume1/docker/netbox/, damit du Daten direkt über die File Station sichern kannst. Verbinde dich per SSH mit dem NAS und lege die vier Unterverzeichnisse an:

mkdir -p /volume1/docker/netbox/media
mkdir -p /volume1/docker/netbox/postgres
mkdir -p /volume1/docker/netbox/redis
mkdir -p /volume1/docker/netbox/redis-cache
mkdir -p /volume1/docker/netbox/env

Verifizieren: Prüfe, ob alle Verzeichnisse korrekt angelegt wurden:

ls /volume1/docker/netbox/
# Erwartete Ausgabe:
# env  media  postgres  redis  redis-cache

Schritt 2: Umgebungsvariablen-Dateien erstellen

Der offizielle Stack trennt die Konfiguration sauber in vier Env-Dateien. Du legst sie unter /volume1/docker/netbox/env/ ab. Wichtig: Ersetze alle Platzhalter durch echte, zufällige Passwörter, bevor der Stack startet.

Erzeuge zunächst einen sicheren SECRET_KEY (mindestens 50 Zeichen):

python3 -c 'import secrets; print(secrets.token_urlsafe(50))'

Erstelle /volume1/docker/netbox/env/netbox.env (Passwörter und Key ersetzen!):

DB_HOST=postgres
DB_NAME=netbox
DB_USER=netbox
DB_PASSWORD=SICHERES_DB_PASSWORT
DB_PORT=5432
REDIS_HOST=redis
REDIS_PASSWORD=SICHERES_REDIS_PASSWORT
REDIS_DATABASE=0
REDIS_CACHE_HOST=redis-cache
REDIS_CACHE_PASSWORD=SICHERES_CACHE_PASSWORT
REDIS_CACHE_DATABASE=1
SECRET_KEY=DEIN_GENERIERTER_SECRET_KEY_HIER
SKIP_SUPERUSER=false
SUPERUSER_NAME=admin
SUPERUSER_EMAIL=admin@example.com
SUPERUSER_PASSWORD=SICHERES_ADMIN_PASSWORT
SUPERUSER_API_TOKEN=0123456789abcdef0123456789abcdef01234567
ALLOWED_HOSTS=*
TZ=Europe/Berlin

Erstelle /volume1/docker/netbox/env/postgres.env:

POSTGRES_DB=netbox
POSTGRES_USER=netbox
POSTGRES_PASSWORD=SICHERES_DB_PASSWORT

Erstelle /volume1/docker/netbox/env/redis.env:

REDIS_PASSWORD=SICHERES_REDIS_PASSWORT

Erstelle /volume1/docker/netbox/env/redis-cache.env:

REDIS_CACHE_PASSWORD=SICHERES_CACHE_PASSWORT

Verifizieren: Prüfe, ob alle vier Dateien vorhanden sind. DB_PASSWORD in netbox.env muss mit POSTGRES_PASSWORD in postgres.env identisch sein – abweichende Werte führen beim Start zu Authentifizierungsfehlern:

ls /volume1/docker/netbox/env/
# Erwartete Ausgabe:
# netbox.env  postgres.env  redis-cache.env  redis.env

Schritt 3: Stack-Eckdaten und compose.yaml vorbereiten

Bevor du die compose.yaml erstellst, hier eine Übersicht der wichtigsten Stack-Parameter:

Parameter	Wert	Hinweis
NetBox-Image	netboxcommunity/netbox:v4.6-5.0.1	Offizielles Community-Image, Stand Juni 2026
PostgreSQL-Image	postgres:18-alpine	Alpine-Variante für kleineren Footprint
Cache/Queue-Image	valkey/valkey:9.0-alpine	Redis-Fork, offiziell seit netbox-docker v2.x
Externer Port	8000	Mapping 8000:8080 (intern läuft NetBox auf 8080!)
Interner Port	8080	Healthcheck prüft http://localhost:8080/login/
Architektur	amd64, arm64	Alle Synology x86_64-Modelle kompatibel

Volume	Bind-Mount-Pfad	Inhalt
netbox-media-files	/volume1/docker/netbox/media	Uploads, Bilder, Mediendateien
netbox-postgres-data	/volume1/docker/netbox/postgres	PostgreSQL-Datenbankdateien (kritisch!)
netbox-redis-data	/volume1/docker/netbox/redis	Valkey Queue (AOF-Persistenz aktiviert)
netbox-redis-cache-data	/volume1/docker/netbox/redis-cache	Valkey Cache (kann verloren gehen)

Erstelle jetzt /volume1/docker/netbox/compose.yaml mit folgendem Inhalt:

services:
  netbox: &netbox
    image: docker.io/netboxcommunity/netbox:v4.6-5.0.1
    depends_on:
      - postgres
      - redis
      - redis-cache
    env_file:
      - env/netbox.env
    user: "unit:root"
    healthcheck:
      test: curl -f http://localhost:8080/login/ || exit 1
      start_period: 90s
      timeout: 3s
      interval: 15s
    volumes:
      - netbox-media-files:/opt/netbox/netbox/media
    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:
      - netbox-postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: pg_isready -q -t 2 -d $${POSTGRES_DB} -U $${POSTGRES_USER}
      start_period: 20s
      timeout: 3s
      interval: 15s
    restart: unless-stopped

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

  redis-cache:
    image: docker.io/valkey/valkey:9.0-alpine
    command:
      - sh
      - -c
      - valkey-server --requirepass $${REDIS_CACHE_PASSWORD}
    env_file:
      - env/redis-cache.env
    volumes:
      - netbox-redis-cache-data:/data
    healthcheck:
      test: "[ $$(valkey-cli --pass \"$${REDIS_CACHE_PASSWORD}\" ping) = 'PONG' ]"
      start_period: 5s
      timeout: 3s
      interval: 15s
    restart: unless-stopped

volumes:
  netbox-media-files:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /volume1/docker/netbox/media
  netbox-postgres-data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /volume1/docker/netbox/postgres
  netbox-redis-data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /volume1/docker/netbox/redis
  netbox-redis-cache-data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /volume1/docker/netbox/redis-cache

Verifizieren: Prüfe, ob die Datei vollständig geschrieben wurde:

ls -lh /volume1/docker/netbox/compose.yaml
# Erwartete Ausgabe: Datei vorhanden, Größe ca. 2-3 KB

Schritt 4: Projekt im Container Manager importieren und starten

Öffne im DSM den Container Manager und wechsle zum Bereich Projekt. Klicke auf Erstellen und wähle den Pfad /volume1/docker/netbox als Projektordner. Der Container Manager erkennt die compose.yaml automatisch. Vergib den Projektnamen netbox und starte das Projekt.

Beim allerersten Start lädt DSM zunächst alle Images herunter (ca. 1–2 GB je nach Verbindung). Danach führt der netbox-Container Datenbankmigrationen durch – dieser Vorgang dauert typischerweise zwei bis fünf Minuten. Der Healthcheck hat einen start_period von 90 Sekunden, sodass der Container während der Migrationen nicht als „unhealthy“ markiert wird.

Du kannst den Fortschritt per SSH beobachten:

docker compose -f /volume1/docker/netbox/compose.yaml logs -f netbox

Warte, bis in den Logs eine Zeile ähnlich der folgenden erscheint:

Started NetBox (as a uWSGI/unit process)

Verifizieren: Prüfe im Container Manager unter Projekt > netbox, ob alle fünf Services den Status „Wird ausgeführt“ zeigen. Alternativ per SSH:

docker compose -f /volume1/docker/netbox/compose.yaml ps
# Alle 5 Services sollten Status "running" und Health "healthy" zeigen

Schritt 5: DSM-Firewall für Port 8000 öffnen

Die DSM-Firewall blockiert neue Ports standardmäßig. Navigiere in DSM zu Systemsteuerung > Sicherheit > Firewall und füge eine neue Regel für eingehenden TCP-Verkehr auf Port 8000 hinzu. Beschränke die Quelle auf dein lokales Subnetz (z. B. 192.168.1.0/24), wenn NetBox nur intern erreichbar sein soll.

Verifizieren: Öffne im Browser http://SYNOLOGY-IP:8000. Du solltest die NetBox-Anmeldeseite sehen. Falls die Seite noch nicht lädt, warte weitere zwei Minuten – die DB-Migrationen können je nach NAS-Leistung länger dauern.

Schritt 6: Superuser erstellen und ersten Login durchführen

Da du in Schritt 2 SKIP_SUPERUSER=false gesetzt hast, hat NetBox beim ersten Start automatisch den Benutzer admin mit dem konfigurierten Passwort und API-Token angelegt. Melde dich unter http://SYNOLOGY-IP:8000 mit den Zugangsdaten aus netbox.env an.

Alternativ kannst du den Superuser manuell anlegen, falls du SKIP_SUPERUSER=true gesetzt hast:

docker exec -it netbox-netbox-1 /opt/netbox/venv/bin/python \
  /opt/netbox/netbox/manage.py createsuperuser

Verifizieren: Nach dem Login solltest du das NetBox-Dashboard sehen. Navigiere zu Admin (oben rechts) > Users und bestätige, dass der Benutzer admin mit Superuser-Rechten existiert.

Schritt 7: Erstes Prefix anlegen und IPAM in Betrieb nehmen

Jetzt kommt der entscheidende Schritt – der Wechsel von der Excel-Liste zum gelebten IPAM. Navigiere in NetBox zu IPAM > Prefixes > Hinzufügen und lege dein erstes Subnetz an, beispielsweise 192.168.1.0/24 mit der Beschreibung „Büro LAN“. Vergib einen Status (Active), wähle eine Rolle (z. B. „User Network“) und weise das Prefix einer Site zu.

Wenn du mehr über Subnetz-Planung und CIDR-Notation erfahren möchtest, empfehle ich die Grundlagen-Anleitung Subnetting und CIDR verständlich erklärt – ideal als Ergänzung zu dieser Installation.

Verifizieren: Das Prefix erscheint in der Liste unter IPAM > Prefixes mit Status „Active“ und dem korrekten Präfix-Wert. Klicke darauf und prüfe, ob die Detailansicht lädt und die IP-Range korrekt berechnet wird.

Schritt 8: API-Token testen

NetBox bietet eine vollständige REST-API – einer der wichtigsten Unterschiede zu einer Excel-Tabelle. Den API-Token hast du in Schritt 2 als SUPERUSER_API_TOKEN festgelegt. Teste ihn jetzt:

curl -s -H "Authorization: Token 0123456789abcdef0123456789abcdef01234567" \
  http://SYNOLOGY-IP:8000/api/ | python3 -m json.tool

Ersetze den Token-Wert durch deinen echten Token aus netbox.env. Du kannst den Token auch im Web-UI einsehen: Admin (oben rechts) > API Tokens.

Verifizieren: Die Ausgabe sollte ein JSON-Objekt mit allen verfügbaren API-Endpunkten sein:

{
    "circuits": "http://SYNOLOGY-IP:8000/api/circuits/",
    "dcim": "http://SYNOLOGY-IP:8000/api/dcim/",
    "ipam": "http://SYNOLOGY-IP:8000/api/ipam/",
    ...
}

Eine valide JSON-Antwort bestätigt, dass NetBox korrekt läuft, die Authentifizierung funktioniert und die API erreichbar ist. Damit ist der Stack vollständig in Betrieb.

Troubleshooting / Typische Fehler

• Web-UI nicht erreichbar nach dem Start: Der Healthcheck hat einen start_period von 90 Sekunden, aber DB-Migrationen können bis zu fünf Minuten dauern. Warte ab und beobachte die Logs mit docker compose logs -f netbox. Erwartet: Zeile „Started NetBox“.
• Connection Refused auf Port 8000: Häufigste Ursache ist ein falsches Port-Mapping. Das offizielle Image exponiert intern 8080, nicht 8000. Prüfe in der compose.yaml, ob ports: - "8000:8080" korrekt eingetragen ist. Ein Mapping 8000:8000 führt zu „Connection Refused“.
• Authentication failed beim PostgreSQL-Start: DB_PASSWORD in netbox.env und POSTGRES_PASSWORD in postgres.env müssen identisch sein. Prüfe beide Dateien und starte den Stack neu.
• Webhooks und Custom Scripts funktionieren nicht: Der netbox-worker-Service fehlt oder läuft nicht. Ohne den Worker bleiben Tasks in der Queue hängen – ohne Fehlermeldung in der UI. Prüfe mit docker compose ps netbox-worker, ob der Service „healthy“ ist.
• SECRET_KEY wurde nicht geändert: Ein unveränderter Standard-SECRET_KEY ist ein Sicherheitsrisiko. Generiere einen neuen Key mit python3 -c 'import secrets; print(secrets.token_urlsafe(50))', trage ihn in netbox.env ein und starte NetBox neu. Achtung: Alle aktiven Sessions werden damit ungültig.
• Falsches Redis-Image verwendet: Wer aus älteren Anleitungen redis:latest übernimmt, kann auf Kompatibilitätsprobleme stoßen. Der offizielle netbox-docker-Stack nutzt seit der Redis-Lizenzänderung ausschließlich valkey/valkey:9.0-alpine.
• DSM-Firewall blockiert Port 8000: Auch wenn alle Container laufen, ist die Web-UI nicht erreichbar, solange keine Firewall-Regel existiert. Navigiere zu Systemsteuerung > Sicherheit > Firewall und füge die Regel hinzu.
• Volume-Pfade nicht angelegt: Wenn die Bind-Mount-Verzeichnisse unter /volume1/docker/netbox/ nicht existieren, startet der Stack mit Volume-Fehlern. Erstelle alle vier Unterverzeichnisse vor dem ersten Start (Schritt 1).

Häufige Fragen

Muss ich wirklich alle fünf Services betreiben?

Für den Produktivbetrieb: Ja. Die vier Services netbox, postgres, redis und redis-cache sind technisch Pflicht – ohne sie startet die Applikation nicht. Der netbox-worker ist technisch optional, aber ohne ihn funktionieren Webhooks, Custom Scripts und alle hinterlegten Automatisierungen nicht. Tasks bleiben still in der Queue hängen, ohne dass die UI einen Fehler anzeigt.

Wie erstelle ich den Admin-Benutzer, wenn ich SKIP_SUPERUSER=true gesetzt habe?

Verbinde dich per SSH mit dem NAS und führe folgenden Befehl aus (Container-Name ggf. mit docker ps ermitteln):

docker exec -it netbox-netbox-1 /opt/netbox/venv/bin/python \
  /opt/netbox/netbox/manage.py createsuperuser

Welche Synology-Modelle sind kompatibel?

Alle Synology-NAS mit x86_64-CPU (Intel Celeron/Core, AMD Ryzen) und DSM 7.2+. Das offizielle Image unterstützt sowohl amd64 als auch arm64 – der komplette Stack mit fünf Services benötigt jedoch mindestens 4 GB RAM, empfohlen sind 8 GB.

Wie aktualisiere ich NetBox auf eine neue Version?

Ändere in der compose.yaml den Image-Tag auf den neuen Wert (Format: vX.Y-A.B.C), erstelle vorher ein Datenbank-Backup und prüfe die Release Notes. Überspringe keine Major-Versionen – NetBox hat ein striktes Update-Pfad-Konzept. Verwende niemals :latest im Produktivbetrieb.

docker compose -f /volume1/docker/netbox/compose.yaml pull
docker compose -f /volume1/docker/netbox/compose.yaml up -d

Was ist der Unterschied zum LinuxServer.io-Image?

Manche Anleitungen verwenden ghcr.io/linuxserver/netbox:latest. Das ist ein Drittanbieter-Image mit dem PUID/PGID-Konzept und eigenem Konfigurationsansatz. Das offizielle Community-Image docker.io/netboxcommunity/netbox läuft als unit:root, kennt keine PUID/PGID-Variablen und ist das von der netbox-community gewartete Standard-Image. Für diese Anleitung gilt ausschließlich das offizielle Image.

Fazit

NetBox auf dem Synology NAS ist kein Hexenwerk – der offizielle Docker-Compose-Stack macht die Installation reproduzierbar und wartbar. Drei Env-Dateien, vier Verzeichnisse und eine sorgfältig geprüfte compose.yaml genügen, um eine vollwertige IPAM/DCIM-Plattform in Betrieb zu nehmen. Der wichtigste Aspekt ist dabei nicht die Technik, sondern die Disziplin: NetBox entfaltet seinen Mehrwert erst, wenn du konsequent alle IP-Adressen, Subnetze und Geräte einpflegst. Fange mit deinem wichtigsten Subnetz an, teste die API-Integration und baue die Dokumentation schrittweise aus. Im Zusammenspiel mit einem GLPI für Helpdesk und IT-Asset-Management entsteht auf dem NAS eine vollständige IT-Verwaltungsplattform ohne zusätzliche Server-Hardware. Wer parallel die Gerätedokumentation strukturieren will, findet im Batch-Geschwister Snipe-IT für IT-Inventarisierung eine sinnvolle Ergänzung.

Weiterführende Anleitungen und Quellen

• Netzwerkdokumentation und IP-Adressplan (IPAM) erstellen – konzeptionelle Grundlagen, bevor du NetBox befüllst
• Subnetting und CIDR verständlich erklärt – Prefix-Planung ohne Kopfrechnen
• GLPI auf dem Synology NAS: Helpdesk und IT-Asset-Management – sinnvolle Ergänzung im gleichen Cluster
• Snipe-IT auf dem Synology NAS: IT-Inventarisierung mit System – Hardware-Inventar als Pendant zu NetBox
• Nginx Proxy Manager auf der Synology: Reverse Proxy und SSL – für HTTPS-Zugriff auf NetBox

Offizielle Quellen: netbox-community/netbox-docker auf GitHub (README, compose.yaml, env-Dateien) · netboxcommunity/netbox auf Docker Hub (Tags, Architektur)