NetBox avec Docker : fixer la version 4.6, sécuriser, sauvegarder et mettre à niveau

EdwardMoon

Le projet de conteneurs de la communauté NetBox déploie de manière cohérente l'application, le worker, PostgreSQL et le cache avec Docker Compose. Exposer directement l'exemple sur Internet, utiliser des tags latest ou des identifiants admin/admin, ou définir ALLOWED_HOSTS=* compromet la sécurité et la reproductibilité.

Ce guide utilise une combinaison compatible NetBox Docker 5.0.1 et NetBox 4.6 en juillet 2026. En production, fixez le tag validé du dépôt et ceux des images. Traitez le proxy inverse TLS, les secrets, les sauvegardes PostgreSQL et médias, les tests de restauration et les mises à niveau en préproduction comme une seule procédure d'exploitation.

Composants et frontières des données

Compatibilité et fixation des versions

NetBox Docker 5.0.1 annonce une compatibilité avec NetBox 4.6.x et versions ultérieures. Les fichiers de support du dépôt et les tags d'images doivent correspondre : mettre à jour le dépôt seul ou télécharger indépendamment latest ne suffit pas. Le projet recommande en production des tags contenant les versions NetBox et des fichiers de support.

Vérifier les versions des outils hôtes

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

Fixer la version du dépôt à valider

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

Revérifiez le tag et la plage de compatibilité sur la page officielle au moment de l'installation. Pour une exploitation durable, fixez un tag contenant le correctif NetBox testé ou utilisez une empreinte d'image, puis consignez-le dans la gestion des changements.

Concevoir la sécurité avant le déploiement

• Ne fondez pas une nouvelle production sur CentOS 7, en fin de vie.
• Ne publiez pas les ports de base ou cache sur l'hôte ou le réseau externe.
• Faites d'abord écouter NetBox uniquement sur 127.0.0.1, derrière un proxy HTTPS.
• Utilisez les véritables FQDN dans ALLOWED_HOSTS, sans caractère générique.
• Créez les administrateurs interactivement et excluez les mots de passe des fichiers Compose et de Git.
• Préparez une procédure restaurant la base et les médias au même point dans le temps.

Permissions du répertoire de déploiement

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

Générer des secrets robustes

Les mots de passe de base/cache et SECRET_KEY des exemples sont publics. Avant le premier démarrage, remplacez DB_PASSWORD, SECRET_KEY, API_TOKEN_PEPPER_1, REDIS_PASSWORD et REDIS_CACHE_PASSWORD dans env/netbox.env. Faites correspondre POSTGRES_PASSWORD dans env/postgres.env à DB_PASSWORD. Faites correspondre REDIS_PASSWORD de env/redis.env et env/redis-cache.env aux mots de passe des tâches et du cache. Modifier l'environnement ne change pas le mot de passe d'une base déjà créée : une procédure distincte est nécessaire.

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

Définissez ALLOWED_HOSTS=netbox.example.internal localhost 127.0.0.1 et SKIP_SUPERUSER=true dans l'environnement NetBox en adaptant le nom du service. Créez ensuite l'administrateur avec la commande interactive.

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

# Stocker les valeurs générées dans un gestionnaire approuvé ou un fichier Compose secrets
# sans les laisser dans l'historique du shell, Git ou les tickets.

Consultez la documentation de la version retenue pour les noms de variables et mécanismes de secrets pris en charge. N'utilisez pas la même valeur pour SECRET_KEY, PostgreSQL et les caches.

Surcharges Compose et exposition réseau

Lors de la validation initiale, liez le port web au bouclage. La surcharge ci-dessous est un exemple de principe : comparez-la au fichier d'exemple du dépôt 5.0.1 et examinez la configuration fusionnée avant utilisation. N'ajoutez pas de ports aux services de base ou cache.

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

Examiner la configuration Compose fusionnée et les images

L'image NetBox par défaut du dépôt utilise un tag mobile de la série 4.6. Vérifiez une combinaison exacte correctif/fichiers de support dans le registre officiel, puis définissez VERSION dans .env du projet. Ce fichier d'interpolation Compose est distinct des env/*.env propres aux services.

# Indiquer un tag dont l'existence et la compatibilité ont été vérifiées dans le registre officiel.
# Format : v4.6.<PATCH>-5.0.1 ; ne pas conserver le paramètre fictif <PATCH>.
${EDITOR:-vi} .env
# Contenu de .env : VERSION=<tag vérifié du correctif NetBox et des fichiers de support>

docker compose config --images
docker compose pull

Pour des redéploiements identiques octet pour octet, consignez RepoDigests depuis docker image inspect après téléchargement et fixez chaque image à une valeur vérifiée image@sha256:.... Fixer le tag du dépôt ne fixe pas toutes les empreintes d'images.

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

# Vérifier l'absence de tags latest et de ports publiés sur 0.0.0.0, pour la base ou les caches
grep -nE 'latest|0\.0\.0\.0|5432:|6379:' /tmp/netbox-compose.rendered.yml

Télécharger les images et démarrer NetBox

Télécharger d'abord et consigner les empreintes

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

Démarrer les services et vérifier leur santé

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

Un conteneur running ne signifie pas que l'application est prête. Vérifiez la fin des migrations, les connexions PostgreSQL, le worker, les réponses HTTP, la connexion utilisateur et une requête API représentative.

Premier administrateur et ALLOWED_HOSTS

Stocker SUPERUSER_PASSWORD=admin dans un fichier d'environnement, comme l'ancien article, peut exposer le secret via l'inspection des conteneurs, les sauvegardes, Git ou les journaux. Après le premier démarrage, créez l'administrateur interactivement avec la commande officielle, puis retirez immédiatement les variables SUPERUSER_* temporaires.

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

Indiquez le véritable FQDN du service dans ALLOWED_HOSTS et faites-le correspondre à l'en-tête Host transmis par le proxy TLS. Avant exposition externe, examinez HTTPS, les en-têtes de proxy de confiance, les contrôles d'accès, les cookies de session et MFA/SSO administrateur.

Sauvegarder PostgreSQL et les médias

PostgreSQL contient les données de référence NetBox, et les fichiers téléversés résident dans le volume media. Un dump seul omet images et pièces jointes ; un snapshot de volume seul ne garantit pas nécessairement la cohérence PostgreSQL. Capturez les deux pendant la même maintenance, avec la configuration et l'inventaire des images, puis chiffrez l'ensemble.

Créer une sauvegarde logique 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

Trouver les véritables noms de volumes et points de montage

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

Sauvegardez les médias avec des snapshots adaptés au pilote de stockage ou un outil approuvé. Pour les copies de fichiers, maîtrisez les écritures concurrentes et préservez permissions, propriétaires et liens symboliques. Transférez les sauvegardes chiffrées sur un autre hôte et consignez leurs sommes de contrôle.

Générer les sommes de contrôle des sauvegardes

cp docker-compose.override.yml "$BACKUP_DIR/"
cp deployed-images.txt "$BACKUP_DIR/"
# Restreindre l'accès à .env et env/ contenant des secrets et les sauvegarder séparément avec chiffrement.
(
  set -euo pipefail
  cd "$BACKUP_DIR"
  find . -type f ! -name SHA256SUMS -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS
  sha256sum -c SHA256SUMS
)

Mettre NetBox à niveau en sécurité

Une mise à niveau dépasse git pull et le remplacement des images par latest. Consultez les notes de version pour la compatibilité NetBox, NetBox Docker, PostgreSQL et Valkey, y compris les versions intermédiaires requises. NetBox Docker 4.0.0 a notamment introduit Granian, PostgreSQL 18 et Valkey 9 : un ancien déploiement ne peut pas les adopter en sécurité par un simple redémarrage.

1. Consigner le tag actuel du dépôt, les empreintes, la version NetBox et celle de la base.
2. Sauvegarder base, médias et configuration, puis les restaurer en environnement isolé.
3. Vérifier le chemin de mise à niveau dans les notes de version cibles et la documentation officielle.
4. Préparer le tag cible dans un nouveau répertoire et examiner les surcharges locales avant de les reporter.
5. Valider Compose fusionné, images, secrets et ports, puis exécuter les migrations en préproduction.
6. Déployer pendant une maintenance et vérifier interface, API, workers, journaux et données.

Consigner les versions actuelles de l'application et de la base

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

Valider la nouvelle version avant de modifier la production

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

Démarche de diagnostic

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

Points à vérifier en exploitation

• Fixer le tag du dépôt et chaque version ou empreinte d'image dans la gestion des changements.
• Utiliser le véritable FQDN dans ALLOWED_HOSTS et ne pas publier les ports de base/cache.
• Exclure mots de passe administrateur et SECRET_KEY de Git, des fichiers Compose générés et des journaux.
• Maintenir le proxy TLS, les accès, la synchronisation horaire et les correctifs réguliers.
• Sauvegarder PostgreSQL, médias, configuration et inventaires d'images comme un même ensemble de récupération.
• Restaurer régulièrement en isolation et tester connexion NetBox, API et pièces jointes.
• Avant mise à niveau, examiner notes, versions intermédiaires et compatibilité PostgreSQL, Valkey et plugins.

Documentation officielle et articles associés

• Dépôt communautaire officiel NetBox Docker
• Versions et compatibilité NetBox Docker
• Wiki d'exploitation NetBox Docker
• Documentation officielle de mise à niveau NetBox
• Installation officielle de Docker Engine
• Préparer NetBox hors ligne avec Podman

Conclusion

Un déploiement NetBox Docker réussi sait reproduire ses versions et restaurer ses données, au-delà du démarrage des conteneurs. Fixez ensemble dépôt et images, réduisez l'exposition, séparez les secrets, créez les administrateurs interactivement, utilisez TLS et sauvegardez base et médias conjointement. Ne mettez à niveau qu'après test de restauration et validation de la compatibilité propre à la version.