NetBox : Déploiement via Docker sur Ubuntu/Debian
Déployer NetBox Community via Docker Compose sur Ubuntu/Debian pour gérer, documenter et automatiser son infrastructure réseau et datacenter.
NetBox est la référence open-source pour la documentation d’infrastructure IT. L’IPAM centralise la gestion des adresses IP et des préfixes réseau pour éviter les conflits et garder une vue claire des plages utilisées. Le DCIM inventorie les équipements physiques, leurs emplacements en baie, leurs interfaces et leur câblage. Les modules VLANs et Virtualisation permettent de documenter la segmentation réseau et de rattacher chaque VM à son hôte et à son segment. Conçu pour les équipes réseau et infrastructure, du homelab à l’opérateur télécoms.
Objectif
Déployer NetBox Community via Docker Compose sur Ubuntu/Debian.
Systèmes cibles : Ubuntu 22.04+, Debian 11+
Niveau requis : Administrateur système (sudo)
Prérequis
Caractéristiques minimales du serveur
| Ressource | Minimum |
|---|---|
| CPU | 2 vCPU |
| RAM | 4 Go |
| Disque OS | 20 Go |
| Disque données | 10 Go |
Vérifications logicielles
| Prérequis | Commande de vérification |
|---|---|
| Accès sudo ou root | sudo -v |
| Connexion Internet active | ping -c 2 google.com |
| Docker installé et actif | docker --version |
| Docker Compose installé | docker compose version |
| Git installé | git --version |
| Port 8000 disponible | ss -tlnp | grep 8000 |
Installation de Docker
Docker et Docker Compose sont requis avant de commencer. La procédure d’installation officielle est disponible à l’adresse suivante, choisir sa distribution et suivre les instructions :
docs.docker.com/engine/install
Docker Compose est inclus dans les versions récentes de Docker Engine, aucune installation séparée n’est nécessaire.
Vérifier que l’installation est opérationnelle :
docker --version
docker compose version
Cloner le dépôt NetBox Docker
Le projet netbox-docker est le dépôt officiel maintenu par la communauté NetBox pour le déploiement via conteneurs.
Cloner la branche release — toujours stable et recommandée en production :
sudo git clone -b release https://github.com/netbox-community/netbox-docker.git
ls
cd netbox-docker/
ls
Ne pas modifier docker-compose.yml directement. On utilisera un fichier d’override à l’étape suivante.
Configurer le port d’écoute
NetBox nécessite un fichier de surcharge nommé obligatoirement docker-compose.override.yml : Docker Compose le détecte et le fusionne automatiquement avec le fichier principal.
sudo nano docker-compose.override.yml
Attention à l’indentation (2 espaces, pas de tabulations) :
services:
netbox:
ports:
- 8000:8080
Sauvegarder : Ctrl+X, Y, Entrée.
Le port 8080 est le port interne du conteneur. On l’expose sur 8000 de la machine hôte. NetBox sera accessible via http://IP_SERVEUR:8000.
Télécharger les images Docker
sudo docker compose pull
Vérifier les images téléchargées :
sudo docker images
Démarrer les conteneurs
sudo docker compose up -d
L’erreur netbox-docker-netbox-1 is unhealthy au premier démarrage est normale et attendue. NetBox initialise la base PostgreSQL, applique les migrations Django et prépare les fichiers statiques. Cette opération prend entre 2 et 5 minutes. Docker considère le conteneur comme “unhealthy” pendant cette phase car le healthcheck échoue avant que l’application soit opérationnelle.
Attendre quelques minutes avant de continuer.
Vérifier l’état après quelques minutes :
sudo docker compose ps
Tous les conteneurs doivent afficher healthy avant de continuer. Si netbox-1 reste en erreur après 5 minutes, consulter la section Dépannage.
Créer le compte administrateur
sudo docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser
NetBox impose un mot de passe d’au moins 12 caractères contenant au moins un chiffre. Un mot de passe trop simple retourne :
This password is too short. It must contain at least 12 characters.
Accéder à l’interface web
http://IP_SERVEUR:8000
Se connecter avec les identifiants créés à l’étape précédente. Le tableau de bord NetBox s’affiche avec les modules disponibles : Organisation, IPAM, DCIM, VPN, Virtualisation, Circuits.
Dépannage
netbox-1 reste en erreur après 5 min : Consulter les logs avec sudo docker compose logs netbox.
Interface inaccessible sur le port 8000 : Vérifier le firewall avec sudo ufw status et ouvrir si nécessaire avec sudo ufw allow 8000.
Erreur port is already allocated : Un service utilise déjà le port 8000, changer dans docker-compose.override.yml ex : 8001:8080.
Mot de passe refusé : Utiliser au moins 12 caractères avec un chiffre.
Conteneur PostgreSQL en erreur : Vérifier l’espace disque avec df -h.
Erreur de permission sur les volumes : Relancer avec sudo docker compose down -v && sudo docker compose up -d (supprime les données).