Как развернуть NetBox 4.7.5 на чистом сервере Linux в Docker: пошаговое руководство

Зачем нужен NetBox и почему Docker

NetBox — открытая система описания сети (Source of Truth): она объединяет DCIM и IPAM в одной базе. В ней хранятся площадки, локации, стойки, устройства и их компоненты, кабельные соединения, VLAN, префиксы, IP-адреса, виртуальные машины, каналы связи и электропитание. В отличие от вики или таблицы, NetBox держит связи между объектами: префикс знает свою площадку и VLAN, IP-адрес — интерфейс и устройство, устройство — стойку, юнит и роль. Поверх этого работают REST API и GraphQL, поэтому из NetBox получаются конфиги, инвентаризация и отчёты без ручного копирования.

Ручная установка — это виртуальное окружение Python, PostgreSQL, Redis, gunicorn, systemd-юниты и nginx, а потом отдельная процедура обновления на каждый релиз. Официальный проект netbox-docker упаковывает всё в Docker Compose: веб-приложение, обработчик очереди задач, PostgreSQL и два экземпляра Redis (очередь задач и кэш; в свежих выпусках вместо Redis взят совместимый Valkey). Обновление сводится к смене тега образа и перезапуску — миграции базы приложение применяет само.

В статье — развёртывание NetBox 4.7.5 (последний стабильный выпуск, опубликован 10 ноября 2026 года) с netbox-docker 5.1.1 на чистом сервере Debian 12 или Ubuntu 24.04. Скриншоты интерфейса сняты на тестовом стенде той же версии — на них видно, что должно получиться в итоге.

Что понадобится

Сервер с Debian 12 (bookworm) или Ubuntu 24.04 LTS, root или sudo;
2 vCPU и 4 ГБ ОЗУ — комфортный минимум для нескольких тысяч объектов, при десятках тысяч устройств лучше 8 ГБ;
20 ГБ диска, желательно SSD: база, медиафайлы и образы контейнеров;
Docker Engine 27 и новее с плагином Compose v2;
свободный порт 8000 (наружу его лучше не публиковать, а поставить перед NetBox reverse proxy с HTTPS).

Шаг 1. Готовим чистый сервер

Обновляем пакеты, ставим базовые утилиты и приводим часовой пояс к московскому: NetBox хранит время в UTC, но в интерфейсе и отчётах используется локальная зона.

apt update && apt full-upgrade -y
apt install -y ca-certificates curl gnupg git ufw
timedatectl set-timezone Europe/Moscow
hostnamectl set-hostname netbox

Закрываем всё лишнее файрволом. SSH оставляем, порт 8000 открываем только на время первичной настройки — потом его закроет reverse proxy.

ufw allow OpenSSH
ufw allow 8000/tcp
ufw --force enable
ufw status

Шаг 2. Ставим Docker Engine и Compose

Ставим Docker из официального репозитория, а не из пакетов дистрибутива: в Debian и Ubuntu версии сильно отстают от актуальных, а netbox-docker требует свежий Compose v2.

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
  | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Для Ubuntu в двух строках выше меняем linux/debian на linux/ubuntu — путь к ключу и имя репозитория. Проверяем результат:

docker --version
docker compose version
systemctl is-enabled docker

Шаг 3. Забираем netbox-docker

Клонируем официальный репозиторий в ветке release — это стабильная ветка, а не разработка:

mkdir -p /opt/netbox && cd /opt/netbox
git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
git tag --sort=-v:refname | head -5

Важно понимать схему тегов проекта. Тег вида v4.7.5-5.1.1 означает NetBox 4.7.5 и файлы сопровождения netbox-docker 5.1.1 — их совместимость гарантирована. В docker-compose.yml версия образа вынесена в переменную VERSION со значением по умолчанию v4.7-5.1.1; для продакшена версию лучше закрепить точно, а не плыть по тегу latest.

Шаг 4. Настраиваем окружение

Создаём файл переопределения — в нём задаются порты и прочие настройки поверх базового compose-файла:

cp docker-compose.override.yml.example docker-compose.override.yml

В примере уже проброшен порт 8000:8080 (внутри контейнера NetBox слушает 8080). Если 8000 занят, правим левую часть на свободный порт.

Теперь настройки приложения. Все они лежат в файлах каталога env/. Пароли и ключи генерируем заново — значения из примеров использовать нельзя, они опубликованы в открытом репозитории:

openssl rand -base64 60 | tr -d '\n'   # SECRET_KEY, не короче 50 символов
openssl rand -hex 24                     # пароль PostgreSQL
openssl rand -hex 24                     # пароль Redis
openssl rand -hex 24                     # пароль Redis-кэша

Правим env/netbox.env:

SECRET_KEY='сгенерированное-значение'
DB_PASSWORD='пароль-postgres'
REDIS_PASSWORD='пароль-redis'
REDIS_CACHE_PASSWORD='пароль-redis-cache'
ALLOWED_HOSTS=netbox.example.com
TIME_ZONE=Europe/Moscow
SUPERUSER_NAME=admin
SUPERUSER_EMAIL=admin@example.com
SUPERUSER_PASSWORD='сложный-пароль'
SKIP_SUPERUSER=false

Три момента, на которых чаще всего спотыкаются:

SECRET_KEY короче 50 символов — контейнер не стартует, в логах ошибка проверки настроек;
пароль из DB_PASSWORD в env/netbox.env должен совпадать с POSTGRES_PASSWORD в env/postgres.env, а пароли Redis — с содержимым env/redis.env и env/redis-cache.env;
значение ALLOWED_HOSTS — это доменные имена или IP без кавычек и скобок, несколько значений разделяются пробелом, а не запятой. Если записать туда ["*"], NetBox воспримет строку буквально и начнёт отвечать ошибкой 400 на всех страницах.

Отправку почты (уведомления об ошибках и сброс пароля) настраивают переменными EMAIL_SERVER, EMAIL_PORT, EMAIL_USERNAME, EMAIL_PASSWORD, EMAIL_USE_TLS или EMAIL_USE_SSL — они взаимоисключающие.

Шаг 5. Запускаем

docker compose pull
docker compose up -d
docker compose ps

Первый запуск — самый долгий: создаются таблицы базы, применяются миграции, наполняются справочники. Две-пять минут контейнер netbox будет в состоянии health: starting, это нормально. Статус виден в docker compose ps, подробности — в логах:

docker compose logs -f netbox

Признак готовности — строка о запуске gunicorn и ответ 200 на /login/. Контейнер netbox-worker стартует вторым: он ждёт, пока основной сервис станет healthy, иначе обработчик очереди бессмысленно поднимать раньше базы.

Шаг 6. Первый вход

Открываем в браузере http://адрес-сервера:8000/. Должна появиться страница входа:

Страница входа в NetBox 4.7.5 — Страница входа NetBox 4.7.5 — адрес, логин и пароль задаются в env/netbox.env

Входим под учётной записью из SUPERUSER_NAME и SUPERUSER_PASSWORD. Если в env/netbox.env оставлено SKIP_SUPERUSER=true, суперпользователя создают вручную:

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

После входа открывается дашборд со сводкой по объектам: площадки, стойки, устройства, префиксы, адреса, виртуальные машины.

Дашборд NetBox с виджетами по объектам — Дашборд: счётчики DCIM, IPAM и виртуализации. Виджеты переставляются и отключаются мышью

Интерфейс переведён на русский: язык задаётся переменной DEFAULT_LANGUAGE=ru-ru в env/netbox.env. Часть подписей остаётся английской — перевод неполный, и это не ошибка установки.

Шаг 7. Наполняем базу

Порядок заполнения важен: сначала справочники, потом объекты, которые на них ссылаются. Для сети из одного-двух ЦОД маршрут такой:

Организация — площадки (Site), локации внутри площадки, стойки с высотой в юнитах;
Устройства — производитель, тип устройства, роль, платформа, затем само устройство с привязкой к стойке и юниту;
Компоненты — интерфейсы устройства, кабели между ними;
IPAM — VLAN, префиксы (с привязкой к площадке), IP-адреса на интерфейсах.

Список устройств показывает сразу всё, что нужно администратору: площадку, стойку, роль, модель и основной адрес.

Список устройств в NetBox — Список устройств: площадка, локация, стойка, роль, производитель, тип и основной IP-адрес

Карточка устройства собирает паспорт оборудования и его место в инфраструктуре — серийный и инвентарный номера, роль, платформу, основной адрес, тип и высоту в стойке.

Карточка коммутатора в NetBox — Карточка устройства: статус, роль, платформа, основной IPv4 и тип оборудования

На вкладке «Интерфейсы» видны порты, их режим, описание и закреплённые адреса — именно эти данные потом уходят в шаблоны конфигураций.

Интерфейсы устройства с IP-адресом — Интерфейсы устройства: имя, тип, описание, IP-адрес и состояние линка

У стойки есть схема размещения: NetBox рисует элевацию по юнитам и подсвечивает устройства ролями. Так сразу видно свободные юниты и плотность размещения.

Элевация стойки в NetBox — Элевация стойки: занятые юниты, роли устройств и процент заполнения

В IPAM заводят префиксы с привязкой к площадке и VLAN. Колонка «Использование» считается автоматически по дочерним префиксам и занятым адресам.

Список префиксов в NetBox — Префиксы: область применения, VLAN, процент использования и описание

Адреса привязываются к интерфейсам устройств и виртуальных машин, с DNS-именем и статусом. Один из адресов устройства назначают основным — он и попадает в карточку.

Список IP-адресов в NetBox — IP-адреса: статус, назначение на интерфейс, DNS-имя и описание

Шаг 8. Резервное копирование

Резервировать нужно две вещи: базу PostgreSQL и медиафайлы (загруженные изображения, отчёты, скрипты).

mkdir -p /var/backups/netbox
docker compose exec -T postgres pg_dump -U netbox netbox | gzip > /var/backups/netbox/db-$(date +%F).sql.gz
docker run --rm -v netbox-docker_netbox-media-files:/data:ro -v /var/backups/netbox:/backup \
  alpine tar czf /backup/media-$(date +%F).tar.gz -C /data .

Имя тома зависит от каталога проекта: Compose подставляет его как префикс. Проверить точное имя — docker volume ls. Восстановление: развернуть пустой стенд, залить дамп через psql и распаковать архив медиа в тот же том.

Шаг 9. Обновление

Свежий дамп базы — обязательное условие, дальше обновление занимает пару минут:

cd /opt/netbox/netbox-docker
git fetch --tags
git checkout v5.1.1          # тег нужной версии netbox-docker
docker compose pull
docker compose up -d
docker compose logs -f netbox

Миграции применяются автоматически при старте контейнера, отдельная команда не нужна. Если мажорный релиз NetBox требует промежуточной версии, это указано в примечаниях к выпуску — пропускать такие шаги нельзя, база останется в несовместимом состоянии.

Шаг 10. HTTPS и домен

Сам контейнер HTTPS не умеет: он слушает 8080 и ожидает, что шифрованием занимается прокси. Ставим nginx или Caddy на хост, а порт 8000 закрываем файрволом.

server {
    listen 443 ssl http2;
    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:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

В env/netbox.env после этого указываем домен и доверенный источник для CSRF, иначе формы будут отклоняться:

ALLOWED_HOSTS=netbox.example.com
CSRF_TRUSTED_ORIGINS=https://netbox.example.com

С Caddy тот же результат короче — netbox.example.com { reverse_proxy 127.0.0.1:8000 }, сертификат Caddy получит сам.

Типичные проблемы

Ошибка 400 на всех страницах. Почти всегда ALLOWED_HOSTS: не совпадает имя из адресной строки или значение записано как список в кавычках.
Долгий health: starting. Первый старт с миграциями. Если через 10 минут не поднялся — смотреть docker compose logs netbox, чаще всего неверный пароль базы.
Задачи не выполняются, отчёты не считаются. Не запущен netbox-worker. Он поднимается только после healthy-состояния основного контейнера — проверяйте docker compose ps.
502 от прокси. NetBox ещё не готов или слушает не тот порт: внутри контейнера всегда 8080, наружу пробрасывается в override-файле.
Поправили env, а поведение не изменилось. Файлы env/* читаются при создании контейнера: docker restart их не перечитывает. Нужен docker compose up -d — Compose пересоздаст контейнер с новыми переменными.
Порт 8000 занят. Меняем в docker-compose.override.yml на любой свободный, например 8001:8080.

Итог

Чистый сервер превращается в рабочую систему описания сети за десять шагов и примерно полчаса, из которых большая часть — скачивание образов и первичные миграции. Дальше NetBox живёт как обычный набор контейнеров: обновление — смена тега, резервное копирование — два архива, диагностика — логи Compose. Когда база заполнена, к ней подключают автоматизацию: REST API и GraphQL отдают те же данные, что видно в интерфейсе, а значит конфигурации коммутаторов, инвентаризация и отчёты собираются скриптами, а не руками.