Guide de déploiement

NetBox sur VPS : IPAM et inventaire réseau auto-hébergés

Déployer sur un VPS Cloud →

Tutoriel

Self-hosting

NetBox sur VPS : IPAM et inventaire réseau auto-hébergés

Le tableur des adresses IP a toujours une ligne fausse : une adresse attribuée deux fois, un serveur retiré mais jamais effacé, un VLAN que personne ne sait plus expliquer. NetBox remplace ce fichier par une source de vérité : chaque préfixe, chaque adresse, chaque baie et chaque câble est un objet relié aux autres, consultable dans le navigateur et pilotable par API. Ce guide l'installe sur un VPS avec Docker Compose, le ferme aux visiteurs anonymes, le publie en HTTPS derrière nginx et le branche sur vos scripts et sur Ansible.

6 min de lecture3 étapes
Sommaire· Ce que fait NetBox1/11
  1. 01Ce que fait NetBox
  2. 02Ce que NetBox vous donne
  3. 03Tableur ou NetBox sur votre VPS
  4. 04Avant de commencer
  5. 05Installer NetBox avec Docker Compose
  6. 06Ne changez jamais les deux secrets après coup
  7. 07Publier NetBox en HTTPS derrière nginx
  8. 08Premiers pas : site, préfixes et adresses
  9. 09Automatiser avec l'API et Ansible
  10. 10Sauvegarder et mettre à jour
  11. 11NetBox en un clic sur ServOrbit

Ce que fait NetBox

NetBox documente un réseau et l'infrastructure qui le porte. Côté IPAM, il gère les préfixes hiérarchiques, les plages et les adresses IP, les VLAN et les VRF, et calcule l'espace libre de chaque réseau. Côté DCIM, il décrit les sites, les baies et leur élévation, les équipements, leurs interfaces, les câbles et l'alimentation. Les deux se rejoignent : une adresse IP appartient à l'interface d'un équipement, installé dans une baie d'un site.

Le projet est publié sous licence Apache-2.0. La pile Docker officielle, netbox-docker, s'appuie sur PostgreSQL et sur Valkey (ou Redis) pour le cache et la file des tâches de fond. Sur un VPS, l'application et son processus de tâches occupent moins de 1 Go de mémoire au repos.

Ce que NetBox vous donne

  • Une source de vérité unique — l'état attendu du réseau, au lieu de dix fichiers qui se contredisent.
  • Un IPAM qui calcule — espace libre par préfixe, prochaine adresse disponible, détection des doublons.
  • Le plan de vos baies — chaque équipement à sa place, avec ses ports et ses câbles.
  • Une API pour chaque objet — REST et GraphQL, documentation OpenAPI servie par l'instance.
  • Un journal des modifications — qui a changé quoi, quand, avec l'état avant et après.
  • De l'automatisation — webhooks, scripts personnalisés, inventaire dynamique Ansible.

Tableur ou NetBox sur votre VPS

Faites défiler le tableau

Tableur partagéNetBox sur votre VPS
Adresse attribuée deux foisRien ne l'empêcheSignalée à la saisie
Espace libre d'un réseauÀ recompter à la mainCalculé pour chaque préfixe
Lien adresse, équipement, baieColonnes recopiéesObjets reliés entre eux
Historique des modificationsVersions du fichierJournal objet par objet
Lecture par vos scriptsExport CSVAPI REST et GraphQL

Avant de commencer

Prévoyez un VPS Ubuntu 24.04 avec 2 Go de RAM au minimum, 4 Go pour une équipe, 2 vCPU et 20 Go de disque, avec Docker et le plugin Compose installés. Il vous faut aussi un nom d'hôte qui pointe vers le VPS, par exemple netbox.example.com : NetBox n'accepte les formulaires, connexion comprise, que depuis l'origine déclarée dans CSRF_TRUSTED_ORIGINS, et il sera servi en HTTPS.

Installer NetBox avec Docker Compose

  1. Préparer le dossier et le fichier .env

    Le fichier porte les secrets de l'instance. SECRET_KEY et API_TOKEN_PEPPER_1 doivent faire au moins 50 caractères : le premier signe les sessions, le second sert au hachage des jetons d'API.

    mkdir -p /opt/netbox && cd /opt/netbox
    cat > .env <<EOF
    DB_PASSWORD=$(openssl rand -hex 16)
    REDIS_PASSWORD=$(openssl rand -hex 16)
    SECRET_KEY=$(openssl rand -hex 32)
    API_TOKEN_PEPPER_1=$(openssl rand -hex 32)
    SUPERUSER_PASSWORD=$(openssl rand -hex 16)
    DOMAIN=netbox.example.com
    EOF
    chmod 600 .env
  2. Écrire le fichier docker-compose.yml

    Quatre services : PostgreSQL, Valkey protégé par mot de passe, NetBox et son processus de tâches de fond. Le port n'est publié que sur la boucle locale : seul nginx sera exposé à Internet.

    x-netbox: &netbox
      image: netboxcommunity/netbox:v4.7.5-5.1.2
      restart: unless-stopped
      user: "netbox:root"
      environment: &netbox-env
        DB_HOST: postgres
        DB_NAME: netbox
        DB_USER: netbox
        DB_PASSWORD: "${DB_PASSWORD}"
        REDIS_HOST: redis
        REDIS_PASSWORD: "${REDIS_PASSWORD}"
        REDIS_CACHE_HOST: redis
        REDIS_CACHE_PASSWORD: "${REDIS_PASSWORD}"
        REDIS_CACHE_DATABASE: "1"
        SECRET_KEY: "${SECRET_KEY}"
        API_TOKEN_PEPPER_1: "${API_TOKEN_PEPPER_1}"
        SKIP_SUPERUSER: "false"
        SUPERUSER_NAME: admin
        SUPERUSER_PASSWORD: "${SUPERUSER_PASSWORD}"
        LOGIN_REQUIRED: "true"
        CSRF_TRUSTED_ORIGINS: "https://${DOMAIN}"
      volumes:
        - netbox-media:/opt/netbox/netbox/media
    
    services:
      postgres:
        image: postgres:18.7-alpine
        restart: unless-stopped
        environment:
          POSTGRES_DB: netbox
          POSTGRES_USER: netbox
          POSTGRES_PASSWORD: "${DB_PASSWORD}"
        volumes:
          - netbox-postgres:/var/lib/postgresql
    
      redis:
        image: valkey/valkey:9.1.3-alpine
        restart: unless-stopped
        command: ["valkey-server", "--appendonly", "yes", "--requirepass", "${REDIS_PASSWORD}"]
        volumes:
          - netbox-redis:/data
    
      netbox:
        <<: *netbox
        depends_on: [postgres, redis]
        ports:
          - "127.0.0.1:8080:8080"
    
      netbox-worker:
        <<: *netbox
        depends_on: [netbox]
        command: ["/opt/netbox/venv/bin/python", "/opt/netbox/netbox/manage.py", "rqworker"]
    
    volumes:
      netbox-postgres: {}
      netbox-redis: {}
      netbox-media: {}
  3. Démarrer et vérifier

    Le premier démarrage applique toutes les migrations de la base et crée le compte admin : comptez cinq à dix minutes sur un petit VPS. La page de connexion doit répondre 200, et la dernière commande affiche le mot de passe administrateur.

    docker compose up -d
    docker compose logs -f netbox    # attendre « Initialisation is done »
    curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/login/
    grep SUPERUSER_PASSWORD .env

Ne changez jamais les deux secrets après coup

Une nouvelle SECRET_KEY déconnecte tout le monde ; un nouveau API_TOKEN_PEPPER_1 rend invalides tous les jetons d'API déjà émis, et vos scripts tombent en même temps. Sauvegardez le fichier .env avec la base. De même, SUPERUSER_PASSWORD ne sert qu'au premier démarrage : changez ensuite le mot de passe depuis votre profil.

Publier NetBox en HTTPS derrière nginx

NetBox écoute en HTTP sur 127.0.0.1:8080 ; nginx termine le TLS et lui transmet les requêtes. Gardez X-Forwarded-Proto pour que l'application sache qu'elle est servie en HTTPS, et un client_max_body_size suffisant pour les pièces jointes et les imports.

server {
    listen 443 ssl;
    server_name netbox.example.com;
    ssl_certificate     /etc/letsencrypt/live/netbox.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/netbox.example.com/privkey.pem;
    client_max_body_size 25m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Si l'origine ne correspond pas à CSRF_TRUSTED_ORIGINS, la connexion échoue avec une erreur 403 « CSRF verification failed » : vérifiez le schéma https:// et le nom exact.

Premiers pas : site, préfixes et adresses

Connectez-vous sur https://netbox.example.com/login/ avec admin. Commencez par créer un site, puis les préfixes que vous utilisez (IPAM, Préfixes) : NetBox les range automatiquement en hiérarchie et affiche le taux d'occupation de chacun. Ajoutez ensuite les équipements (Appareils), leurs interfaces et leurs adresses IP.

Pour reprendre un tableur existant, chaque liste propose un import CSV ou YAML : collez les lignes, NetBox valide chaque champ et refuse l'import entier si une ligne est fausse, ce qui évite les reprises à moitié faites.

Automatiser avec l'API et Ansible

Créez un jeton depuis votre profil, menu Jetons d'API. Il s'utilise dans l'en-tête Authorization: Bearer, et la documentation interactive est servie sur /api/schema/swagger-ui/.

export NETBOX_TOKEN='nbt_xxxxxxxx.yyyyyyyyyyyyyyyy'
curl -s -H "Authorization: Bearer $NETBOX_TOKEN" -H "Accept: application/json" \
  "https://netbox.example.com/api/ipam/prefixes/?status=active"

# La prochaine adresse libre d'un préfixe (id 1), réservée en une requête
curl -s -X POST -H "Authorization: Bearer $NETBOX_TOKEN" -H "Content-Type: application/json" \
  -d '{"description": "web-01"}' \
  "https://netbox.example.com/api/ipam/prefixes/1/available-ips/"

Côté Ansible, la collection netbox.netbox fournit un inventaire dynamique : vos hôtes et leurs groupes viennent de NetBox, plus d'un fichier tenu à la main. Le jeton se passe dans la variable d'environnement NETBOX_TOKEN.

# netbox_inventory.yml — ansible-galaxy collection install netbox.netbox
plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.example.com
validate_certs: true
group_by: [sites, device_roles]

Sauvegarder et mettre à jour

Deux choses à sauvegarder : la base PostgreSQL et le volume des fichiers joints, sans oublier le fichier .env.

cd /opt/netbox
docker compose exec -T postgres pg_dump -U netbox netbox | gzip > netbox-$(date +%F).sql.gz
docker run --rm -v netbox_netbox-media:/media -v "$PWD":/backup alpine \
  tar czf /backup/netbox-media-$(date +%F).tar.gz -C /media .

Pour mettre à jour, changez le tag de l'image dans docker-compose.yml, puis lancez docker compose pull et docker compose up -d : les migrations sont appliquées au démarrage. Lisez les notes de version avant de changer de version majeure, et faites une sauvegarde juste avant.

NetBox en un clic sur ServOrbit

Le Marketplace ServOrbit installe exactement cette pile : image officielle netbox-docker, PostgreSQL, Valkey et processus de tâches, port publié sur 127.0.0.1 uniquement, secrets générés, compte admin créé, connexion exigée et HTTPS configuré sur votre domaine ou sur le sous-domaine gratuit du VPS. Le mot de passe administrateur s'affiche dans votre espace client.

Partager cet articleservorbit.com/ma-fr/blog/self-host-netbox-vps