NetBox Docker-implementatie: Versie 4.6 vastzetten, beveiliging, back-up en upgrades

AI_Manager

NetBox Docker: Door gebruik te maken van het officiële community-containerproject kun je de NetBox-applicatie, worker, PostgreSQL en cache consistent implementeren met Docker Compose. Echter, het direct blootstellen van voorbeeldconfiguraties aan het internet, of het gebruik van de latest-tag, admin/admin-accounts en ALLOWED_HOSTS=*, vermindert de reproduceerbaarheid en beveiliging aanzienlijk.

Deze gids gebruikt de compatibele combinatie van NetBox Docker 5.0.1 en de NetBox 4.6-serie (peildatum juli 2026) als voorbeeld. Voor productie-implementaties moet je zowel de repository-tags als de image-tags vastzetten en zaken als TLS-reverse proxy, secret-beheer, PostgreSQL- en mediaback-ups, hersteltests en stapsgewijze upgrades als één operationele procedure behandelen.

NetBox Docker-componenten en datagrenzen

NetBox Docker is geen officieel installatieprogramma van de NetBox Community zelf, maar een afzonderlijk project dat door de community wordt beheerd. Kies hiervoor alleen als het operationele team de verantwoordelijkheid kan dragen voor Docker, Compose, PostgreSQL-herstel en de release-opmerkingen.

Versiecompatibiliteit en vastzetten van NetBox Docker

De NetBox Docker 5.0.1-release is expliciet compatibel met NetBox 4.6.x en hoger. Omdat de ondersteunende bestanden in de repository en de container-imagetags op elkaar moeten zijn afgestemd, mag u niet alleen de repository bijwerken of de image naar ‘latest’ trekken. Het officiële project raadt ook aan om voor productieomgevingen tags te gebruiken die zowel de NetBox-versie als de versie van de ondersteunende bestanden bevatten.

Versiecontrole van host-tools

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

Vastzetten van de repository-release voor validatie

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

Controleer op het moment van installatie opnieuw de tags en het compatibiliteitsbereik op de officiële releasepagina. Voor langdurig beheer moet u de imagetag of de image-digest, inclusief de geteste NetBox-patchversie, vastzetten en dit vastleggen in de documentatie voor wijzigingsbeheer.

Veiligheidsontwerp vóór implementatie van NetBox Docker

• CentOS 7 heeft het einde van zijn levensduur bereikt en mag niet worden gebruikt als basis voor nieuwe productie-implementaties.
• Publiceer de poorten voor de database en cache niet naar de host of externe netwerken.
• Bind de NetBox-poort in eerste instantie alleen aan 127.0.0.1 en bied deze aan via een HTTPS-proxy.
• Voeg alleen de werkelijke FQDN toe aan ALLOWED_HOSTS en gebruik geen jokerteken (asterisk).
• Maak het beheerdersaccount interactief aan en sla wachtwoorden niet op in het compose-bestand of in Git.
• Maak eerst een runbook voor back-up en herstel waarmee zowel de database als de media naar hetzelfde herstelpunt kunnen worden teruggezet.

Rechten voor de implementatiemap

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 {} \;

Genereren van sterke geheimen

De wachtwoorden voor de database en cache, evenals de SECRET_KEY in de standaardvoorbeelden, zijn openbare waarden. Vervang vóór de eerste start de DB_PASSWORD, SECRET_KEY, API_TOKEN_PEPPER_1, REDIS_PASSWORD en REDIS_CACHE_PASSWORD in env/netbox.env door nieuwe waarden. Zorg dat de POSTGRES_PASSWORD in env/postgres.env overeenkomt met DB_PASSWORD, en dat de REDIS_PASSWORD van env/redis.env en env/redis-cache.env overeenkomen met de wachtwoorden voor de werkrij en cache. Omdat het wijzigen van omgevingsbestanden het database-wachtwoord in bestaande databasevolumes niet verandert, is een afzonderlijke wijzigingsprocedure vereist.

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

Specificeer in het NetBox-omgevingsbestand de ALLOWED_HOSTS=netbox.example.internal localhost 127.0.0.1 en SKIP_SUPERUSER=true op basis van de werkelijke servicenaam. Gebruik de interactieve opdracht hieronder om de beheerder aan te maken.

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

# Sla de uitvoer op in een goedgekeurde geheime opslagplaats of Compose secrets-bestand en
# laat deze niet achter in de shell-geschiedenis, Git of ticket-inhoud.

Controleer in de betreffende releasedocumentatie de variabelenamen en de ondersteuning voor geheimen in het voorbeeld-omgevingsbestand dat door het project wordt geleverd. Gebruik de SECRET_KEY, het PostgreSQL-wachtwoord en het cache-wachtwoord niet opnieuw voor verschillende doeleinden.

NetBox Docker: Compose-override en netwerkblootstelling

Bind bij de initiële validatie de webpoort alleen aan loopback. De onderstaande override is een conceptueel voorbeeld; vergelijk het resultaat met het voorbeeld-bestand in de 5.0.1-repository voordat u het gebruikt. Voeg geen ‘ports’-items toe voor de database en cache.

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

Resultaten van Compose-samenvoeging en image-verificatie

De standaard NetBox-image in de repository is een verplaatsbare tag uit de 4.6-serie. Nadat u de exacte combinatie van patch en ondersteunende bestanden uit het officiële register hebt bevestigd, specificeert u de VERSION in de .env van het project. Dit bestand is een ander Compose-vervangingsbestand dan de env/*.env van elke service.

# Voer in met een tag waarvan het bestaan en de compatibiliteit zijn geverifieerd in het officiële register.
# Bijv.: in de vorm v4.6.<PATCH>-5.0.1; sla <PATCH> niet direct op.
${EDITOR:-vi} .env
# Inhoud van .env: VERSION=<geverifieerde tag voor de NetBox-patch en bijbehorende ondersteuningsbestanden>

docker compose config --images
docker compose pull

Als u opnieuw moet implementeren met exact dezelfde bits, noteer dan na het pullen de RepoDigests van docker image inspect en zet de ‘image’-waarde van elke service vast op de gevalideerde image@sha256:.... Het vastzetten van alleen de repository-tag garandeert niet dat alle image-digests ook vaststaan.

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

# Controleer of de uitvoer geen latest, open 0.0.0.0-poorten of DB/cache-poorten bevat
grep -nE 'latest|0\.0\.0\.0|5432:|6379:' /tmp/netbox-compose.rendered.yml

Het gerenderde Compose-bestand kan geheime waarden bevatten. Maak het controlebestand aan met rechten 0600, verwijder het veilig na verificatie en voeg het niet toe aan CI-logs of issues.

NetBox Docker-image ophalen en eerste uitvoering

Haal eerst de image op en noteer de digest

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

Service starten en statuscontrole

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

Ga er niet vanuit dat de applicatie klaar is alleen omdat de container de status ‘running’ heeft. Controleer of de migratie is voltooid, de PostgreSQL-verbinding tot stand is gebracht, de worker is gestart, er een HTTP-antwoord is en of inloggen en het opvragen van de representatieve API werken.

NetBox Docker: Initiële beheerder en ALLOWED_HOSTS

Als u SUPERUSER_PASSWORD=admin in het omgevingsbestand opslaat zoals in het origineel, kan het wachtwoord worden blootgesteld via containerinspectie, back-ups, Git-geschiedenis en logs. Maak na de eerste uitvoering de beheerder interactief aan met de officiële beheeropdrachten en verwijder onmiddellijk de tijdelijke SUPERUSER_*-variabelen als u deze hebt gebruikt.

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

Specificeer in ALLOWED_HOSTS de werkelijke FQDN van de service en laat deze overeenkomen met de Host-header die door de TLS-reverse proxy wordt doorgegeven. Controleer HTTPS, vertrouwde proxy-headers, toegangscontrole, sessie-cookiebeleid en MFA/SSO voor beheerders voordat u de service extern blootstelt.

NetBox Docker: PostgreSQL en media-back-up

De kernbron van NetBox is PostgreSQL, maar geüploade bestanden bevinden zich in het media-volume. Als u alleen een database-dump hebt, ontbreken de afbeeldingen en bijlagen; als u alleen een volume-snapshot hebt, is de consistentie van PostgreSQL moeilijk te garanderen. Bundel beide assets samen met configuraties en afbeeldingslijsten in hetzelfde wijzigingsvenster en bewaar ze versleuteld.

Logische back-up van PostgreSQL

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

Controleer de werkelijke volumenamen en aankoppelpunten

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

Sla het media-volume op met snapshots die geschikt zijn voor de gebruikte opslagdriver of met goedgekeurde back-uptools. Als u bestanden kopieert, beheer dan wijzigingen tijdens het schrijven en behoud rechten, eigenaarschap en symbolische koppelingen. Verstuur back-ups versleuteld naar een aparte host en leg de checksums vast.

Integriteitsbestand voor back-up aanmaken

cp docker-compose.override.yml "$BACKUP_DIR/"
cp deployed-images.txt "$BACKUP_DIR/"
# Beperk de toegang tot .env en env/ die gevoelige waarden bevatten en neem deze ook op in een afzonderlijke versleutelde back-up.
(
  set -euo pipefail
  cd "$BACKUP_DIR"
  find . -type f ! -name SHA256SUMS -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS
  sha256sum -c SHA256SUMS
)

Een succesvolle back-up wordt niet alleen bewezen door een exit-code 0 van het commando. Herstel de database en media in een geïsoleerd staging Compose-project en verifieer periodiek het inloggen, het aantal objecten, bijlagen en API-query’s.

Veilige upgrade van NetBox Docker

Een upgrade is niet zomaar een git pull en het vervangen van de latest image. Controleer in de release notes de compatibiliteit en tussenliggende versievereisten voor NetBox, NetBox Docker, PostgreSQL en Valkey. Met name NetBox Docker 4.0.0 is een grote wijziging waarbij de applicatieserver is vervangen door Granian en PostgreSQL 18 en Valkey 9 zijn geïntroduceerd; voer bij oude installaties dus geen eenvoudige herstart uit.

1. Noteer de huidige repository-tag, image-digest, NetBox-versie en databaseversie.
2. Maak back-ups van de database, media en configuratie en herstel deze in een geïsoleerde omgeving.
3. Controleer de ondersteunde versiepaden in de release notes van het doel en de officiële update-documentatie.
4. Bereid de doel-repository-tag voor in een nieuwe map en migreer alleen de lokale overrides na controle.
5. Valideer de Compose-merges, images, secrets en poorten, en voer vervolgens de migratie uit in de staging-omgeving.
6. Implementeer tijdens een onderhoudsvenster en controleer de UI, API, worker, logs en gegevens.

Huidige versie en database-record

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();'

Validatie vóór wijzigingen in de nieuwe release

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

Na een schema-migratie is een rollback door alleen terug te keren naar de vorige image mogelijk niet veilig. Als een rollback nodig is, herstel dan de volledige set van database, media en configuratie van vóór de wijziging, tenzij er een gedocumenteerd pad voor terugwaartse compatibiliteit is.

Volgorde voor probleemdiagnose

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

Operationele checklist

• Ik heb de repository-tag en alle image-versies of digests vastgelegd in de documentatie voor wijzigingsbeheer.
• ALLOWED_HOSTS bevat alleen de werkelijke FQDN en de poorten voor de database en cache zijn niet openbaar gemaakt.
• Het beheerderswachtwoord en de SECRET_KEY worden beheerd buiten Git, Compose-renderbestanden en logs.
• Ik beheer een TLS-proxy, toegangscontrole, tijdsynchronisatie en regelmatige beveiligingsupdates.
• Ik maak back-ups van PostgreSQL, media, configuraties en de lijst met images als één herstelset.
• Ik valideer regelmatig het herstel in een geïsoleerde omgeving en controleer de NetBox-login, API en bijlagen.
• Vóór een upgrade controleer ik de release notes, tussenliggende versies en de compatibiliteit van PostgreSQL, Valkey en plug-ins.

Officiële documentatie en gerelateerde artikelen

• Officiële NetBox Docker community repository
• NetBox Docker releases en compatibiliteitsinformatie
• NetBox Docker operationele wiki
• Officiële NetBox upgrade-documentatie
• Officiële Docker Engine installatiedocumentatie
• Gids voor NetBox Podman-bundels in afgesloten netwerken

Conclusie

NetBox Docker: De standaard voor een succesvolle operatie is niet of de container opstart, maar of je dezelfde versie kunt reproduceren en gegevens kunt herstellen. Leg de repository en images vast, pas minimale blootstelling toe, scheid geheimen, maak interactieve beheerders aan, gebruik TLS en integreer back-ups van de database en media. Voer upgrades pas uit nadat hersteltests en compatibiliteitscontroles per release zijn geslaagd.