NetBox mit Docker: Version 4.6 festlegen, absichern, sichern und aktualisieren

EdwardMoon

Mit dem offiziellen Community-Containerprojekt NetBox Docker lassen sich NetBox-Anwendung, Worker, PostgreSQL und Cache einheitlich über Docker Compose bereitstellen. Wer die Beispielkonfiguration unverändert ins Internet stellt oder latest-Tags, admin/admin und ALLOWED_HOSTS=* verwendet, schwächt jedoch Reproduzierbarkeit und Sicherheit erheblich.

Dieser Leitfaden verwendet als Beispiel die im Juli 2026 kompatible Kombination aus NetBox Docker 5.0.1 und NetBox 4.6. In der Produktion geprüfte Repository- und Image-Tags gemeinsam festlegen. TLS-Reverse-Proxy, Geheimnisverwaltung, PostgreSQL- und Mediensicherung, Wiederherstellungstests und schrittweise Upgrades gehören in ein zusammenhängendes Betriebsverfahren.

Komponenten und Datenbereiche von NetBox Docker

Kompatible Versionen auswählen und festlegen

Die Versionshinweise zu NetBox Docker 5.0.1 nennen Kompatibilität mit NetBox 4.6.x und höher. Die Unterstützungsdateien aus dem Repository müssen zum Container-Image passen. Deshalb weder nur das Repository aktualisieren noch das Image ungeprüft über latest beziehen. Auch das offizielle Projekt empfiehlt für den Betrieb Tags, die NetBox-Version und Version der Unterstützungsdateien gemeinsam enthalten.

Versionen der Host-Werkzeuge prüfen

docker --version
docker compose version
git --version
openssl version

Repository-Release für die Prüfung festlegen

sudo install -d -o "$USER" -g "$USER" -m 0750 /opt/netbox
cd /opt/netbox
git clone --branch 5.0.1 --depth 1   https://github.com/netbox-community/netbox-docker.git netbox-docker-5.0.1
cd netbox-docker-5.0.1
git describe --tags --always
git status --short

Zum Installationszeitpunkt Tags und Kompatibilitätsbereich nochmals auf der offiziellen Release-Seite kontrollieren. Für den längerfristigen Betrieb einen Image-Tag einschließlich getesteter NetBox-Patchversion oder einen Image-Digest festlegen und in der Änderungsdokumentation erfassen.

Sicherheitsplanung vor der Bereitstellung

• CentOS 7 hat sein Supportende erreicht und wird nicht als Basis neuer Produktionsinstallationen verwendet.
• Datenbank- und Cache-Ports weder auf dem Host noch im externen Netz veröffentlichen.
• Den NetBox-Port zunächst nur an 127.0.0.1 binden und über einen HTTPS-Proxy anbieten.
• In ALLOWED_HOSTS nur tatsächliche FQDNs eintragen und keinen Stern als Platzhalter verwenden.
• Das Administratorkonto interaktiv erstellen und sein Passwort weder in Compose-Dateien noch in Git ablegen.
• Zuerst eine Sicherungs- und Wiederherstellungsanweisung erstellen, die Datenbank und Medien auf denselben Stand zurücksetzen kann.

Rechte des Bereitstellungsverzeichnisses

cd /opt/netbox/netbox-docker-5.0.1
umask 077
cp docker-compose.override.yml.example docker-compose.override.yml
chmod 0600 docker-compose.override.yml
find env -type f -exec chmod 0600 {} \;

Starke Geheimnisse erzeugen

Die Datenbank- und Cache-Passwörter sowie SECRET_KEY aus den Beispielen sind öffentlich bekannt. Vor dem ersten Start in env/netbox.env die Werte für DB_PASSWORD, SECRET_KEY, API_TOKEN_PEPPER_1, REDIS_PASSWORD und REDIS_CACHE_PASSWORD ersetzen. In env/postgres.env muss POSTGRES_PASSWORD DB_PASSWORD entsprechen; REDIS_PASSWORD in env/redis.env und env/redis-cache.env muss jeweils zum Passwort von Aufgabenwarteschlange und Cache passen. Bei einem vorhandenen Datenbank-Volume ändert eine bearbeitete Umgebungsdatei das Datenbankpasswort nicht automatisch; dafür ist ein eigenes Verfahren erforderlich.

chmod 0700 env
${EDITOR:-vi} env/netbox.env env/postgres.env env/redis.env env/redis-cache.env

In der NetBox-Umgebungsdatei ALLOWED_HOSTS=netbox.example.internal localhost 127.0.0.1 passend zum tatsächlichen Dienstnamen sowie SKIP_SUPERUSER=true setzen. Das Administratorkonto anschließend mit dem unten gezeigten interaktiven Befehl erstellen.

umask 077
openssl rand -base64 48
openssl rand -base64 32

# Ausgaben in einem freigegebenen Secret Store oder einer Compose-Secrets-Datei speichern
# Nicht in Shell-Verlauf, Git oder Tickets übernehmen.

Variablennamen der Beispiel-Umgebungsdateien und die Secrets-Unterstützung anhand der Dokumentation des jeweiligen Releases prüfen. Für SECRET_KEY, PostgreSQL und Cache jeweils eigene Geheimnisse verwenden.

Compose-Override und Netzwerkfreigaben

Bei der ersten Prüfung den Webport nur an Loopback binden. Der folgende Override veranschaulicht das Prinzip; vor der Verwendung mit den Beispieldateien des Repository-Releases 5.0.1 und dem zusammengeführten Ergebnis vergleichen. Datenbank und Cache erhalten keine ports-Einträge.

services:
  netbox:
    ports:
      - "127.0.0.1:8000:8080"
    restart: unless-stopped

Zusammengeführte Compose-Konfiguration und Images prüfen

Das voreingestellte NetBox-Image des Repositorys verwendet einen veränderlichen Tag der 4.6-Reihe. In der offiziellen Registry die genaue Kombination aus Patchversion und Unterstützungsdateien prüfen und danach in der projektbezogenen .env den Wert für VERSION festlegen. Diese Datei dient der Compose-Variablenersetzung und unterscheidet sich von den dienstbezogenen Dateien env/*.env.

# Einen in der offiziellen Registry auf Existenz und Kompatibilität geprüften Tag einsetzen.
# Beispiel: v4.6.<PATCH>-5.0.1; <PATCH> muss durch die tatsächliche Version ersetzt werden.
${EDITOR:-vi} .env
# Inhalt von .env: VERSION=<geprüfter Tag aus NetBox-Patch- und Supportdateiversion>

docker compose config --images
docker compose pull

Für eine bitgenau identische erneute Bereitstellung nach dem Pull die RepoDigests aus docker image inspect dokumentieren und den image-Wert jedes Dienstes auf das geprüfte image@sha256:... setzen. Ein festgelegter Repository-Tag fixiert nicht automatisch alle Image-Digests.

docker compose config --quiet
docker compose config --images
docker compose config > /tmp/netbox-compose.rendered.yml

# Ausgabe auf latest, an 0.0.0.0 veröffentlichte Ports sowie Datenbank- und Cache-Ports prüfen
grep -nE 'latest|0\.0\.0\.0|5432:|6379:' /tmp/netbox-compose.rendered.yml

Images beziehen und erstmals starten

Images vorab laden und Digests dokumentieren

docker compose pull
docker compose images
docker image ls --digests | grep -E 'netbox|postgres|valkey'
docker compose config --images > deployed-images.txt
chmod 0600 deployed-images.txt

Dienste starten und Zustand prüfen

docker compose up -d
docker compose ps
docker compose logs --tail=200 netbox
docker compose logs --tail=100 netbox-worker
curl -fsS http://127.0.0.1:8000/ >/dev/null

Ein Containerstatus running bedeutet noch nicht, dass die Anwendung bereit ist. Abgeschlossene Migrationen, PostgreSQL-Verbindung, Worker-Start, HTTP-Antworten, Anmeldung und typische API-Abfragen gemeinsam prüfen.

Erstes Administratorkonto und ALLOWED_HOSTS

Wird wie im früheren Beispiel SUPERUSER_PASSWORD=admin in einer Umgebungsdatei gespeichert, kann das Passwort über Container-Inspektion, Sicherungen, Git-Verlauf oder Logs sichtbar werden. Nach dem ersten Start das Konto interaktiv mit dem offiziellen Verwaltungsbefehl anlegen und vorübergehend verwendete SUPERUSER_*-Variablen sofort entfernen.

docker compose exec netbox   /opt/netbox/netbox/manage.py createsuperuser

In ALLOWED_HOSTS den tatsächlichen Dienst-FQDN angeben, passend zum Host-Header des TLS-Reverse-Proxys. Vor der externen Freigabe HTTPS, vertrauenswürdige Proxy-Header, Zugriffskontrollen, Sitzungscookie-Richtlinien und MFA beziehungsweise SSO für die Administration prüfen.

PostgreSQL und Medien sichern

PostgreSQL enthält den maßgeblichen NetBox-Datenbestand, hochgeladene Dateien liegen jedoch im Media-Volume. Ein reiner Datenbank-Dump lässt Bilder und Anhänge aus; ein bloßer Volume-Snapshot gewährleistet die PostgreSQL-Konsistenz nicht ohne Weiteres. Beide Bestände zusammen mit Konfiguration und Image-Liste im selben Änderungsfenster erfassen und verschlüsselt aufbewahren.

Logische PostgreSQL-Sicherung

BACKUP_DIR="/var/backups/netbox/$(date +%F-%H%M%S)"
sudo install -d -m 0700 "$BACKUP_DIR"
sudo chown "$USER":"$USER" "$BACKUP_DIR"

docker compose exec -T postgres   pg_dump -U netbox -d netbox -Fc   > "$BACKUP_DIR/netbox.pgdump"

docker compose exec -T postgres pg_restore --list < "$BACKUP_DIR/netbox.pgdump" | head

Tatsächliche Volume-Namen und Einhängepunkte prüfen

docker compose config --volumes
docker volume ls
docker inspect "$(docker compose ps -q netbox)"   --format '{{json .Mounts}}' | jq .

Das Media-Volume mit einem zum Speichertreiber passenden Snapshot oder einem freigegebenen Sicherungswerkzeug sichern. Beim Kopieren von Dateien laufende Änderungen kontrollieren und Rechte, Eigentümer sowie symbolische Links erhalten. Sicherungen verschlüsselt auf einen anderen Host übertragen und Prüfsummen dokumentieren.

Datei zur Integritätsprüfung der Sicherung erstellen

cp docker-compose.override.yml "$BACKUP_DIR/"
cp deployed-images.txt "$BACKUP_DIR/"
# Zugriff auf .env und env/ mit Geheimnissen beschränken und separat verschlüsselt sichern.
(
  set -euo pipefail
  cd "$BACKUP_DIR"
  find . -type f ! -name SHA256SUMS -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS
  sha256sum -c SHA256SUMS
)

NetBox Docker sicher aktualisieren

Ein Upgrade umfasst mehr als git pull und den Austausch eines latest-Images. In den Versionshinweisen die Kompatibilität von NetBox, NetBox Docker, PostgreSQL und Valkey sowie erforderliche Zwischenversionen prüfen. Insbesondere NetBox Docker 4.0.0 brachte mit Granian als Anwendungsserver, PostgreSQL 18 und Valkey 9 größere Änderungen. Eine ältere Installation darf deshalb nicht einfach mit den neuen Komponenten neu gestartet werden.

1. Aktuellen Repository-Tag, Image-Digests, NetBox- und Datenbankversion dokumentieren.
2. Datenbank, Medien und Konfiguration sichern und in einer isolierten Umgebung wiederherstellen.
3. Unterstützten Versionspfad in den Ziel-Versionshinweisen und der offiziellen Upgrade-Dokumentation prüfen.
4. Ziel-Repository-Tag in einem neuen Verzeichnis vorbereiten und lokale Overrides nach Prüfung übernehmen.
5. Compose-Zusammenführung, Images, Geheimnisse und Ports prüfen und die Migration in Staging ausführen.
6. Im produktiven Änderungsfenster bereitstellen und Oberfläche, API, Worker, Logs und Daten prüfen.

Aktuelle Versionen und Datenbank erfassen

git describe --tags --always
docker compose images
docker compose exec -T netbox   /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py version
docker compose exec -T postgres psql -U netbox -d netbox   -Atc 'select version();'

Neues Release vor der Umstellung prüfen

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --since=10m | grep -Ei 'error|traceback|failed'

Fehlerdiagnose

docker compose ps --all
docker compose logs --tail=300
docker compose config --images
docker compose exec -T netbox   /opt/netbox/netbox/manage.py check
docker stats --no-stream

Checkliste für den Betrieb

• Repository-Tag und sämtliche Image-Versionen oder Digests sind in der Änderungsdokumentation festgelegt.
• ALLOWED_HOSTS enthält nur die vorgesehenen tatsächlichen FQDNs; Datenbank- und Cache-Ports sind nicht veröffentlicht.
• Administrationspasswort und SECRET_KEY werden außerhalb von Git, aufgelösten Compose-Dateien und Logs verwaltet.
• TLS-Proxy, Zugriffskontrolle, Zeitsynchronisierung und regelmäßige Sicherheitsupdates sind eingerichtet.
• PostgreSQL, Medien, Konfiguration und Image-Liste werden als zusammengehöriger Wiederherstellungssatz gesichert.
• Wiederherstellung, NetBox-Anmeldung, API und Anhänge werden regelmäßig in einer isolierten Umgebung geprüft.
• Vor Upgrades werden Versionshinweise, Zwischenversionen sowie PostgreSQL-, Valkey- und Plugin-Kompatibilität geprüft.

Offizielle Dokumentation und weiterführende Artikel

• Offizielles NetBox-Docker-Community-Repository
• NetBox-Docker-Releases und Kompatibilität
• NetBox-Docker-Betriebswiki
• Offizielle NetBox-Upgrade-Dokumentation
• Offizielle Docker-Engine-Installationsanleitung
• NetBox-Podman-Bundle für abgeschottete Netze

Zusammenfassung

Ein verlässlicher NetBox-Docker-Betrieb muss dieselben Versionen reproduzieren und Daten wiederherstellen können. Repository und Images gemeinsam festlegen, Netzwerkfreigaben minimieren, Geheimnisse getrennt verwalten, Administratoren interaktiv anlegen und TLS sowie gemeinsame Datenbank- und Mediensicherungen einsetzen. Upgrades erst nach erfolgreichen Wiederherstellungstests und Kompatibilitätsprüfungen der jeweiligen Releases durchführen.