Руководство по установщику NextBox

Это руководство помогает установить, обновить, расширить или удалить NextBox и дополнительные компоненты с помощью nextbox-installer.

Установщик готовит Docker Compose окружение, создает конфигурационные файлы, проверяет базовые требования и, если это разрешено, запускает контейнеры через Docker.

• Что делает установщик
• Требования
  • Общие требования
  • Windows
  • Linux
  • Доступ к registry
• Скачивание установщика
  • Linux
  • Windows
• Компоненты и профили
  • Профили
  • Компоненты
• Перед началом
• Быстрая установка
  • Только NextBox
  • Полная установка
  • Ручной выбор компонентов
  • Security с DLP и KESL
• Интерактивный режим
• CLI-режим
  • Основные флаги
  • Матрица обновлений
  • Проверить план перед установкой
  • Выполнить только предпроверку
  • Проверить будущую конфигурацию без изменения установки
• Обновление
• Доустановка компонентов
• Удаление
  • Частичное удаление компонента
  • Полное удаление без удаления данных
  • Полное удаление вместе с данными
  • Удалить контейнеры, но оставить конфиги
• Проверки и диагностика
  • Найти установки NextBox
  • Показать текущую установку
  • Только предпроверка
  • Только план действий
• Какие файлы создает установщик
• Как работает установщик
  • Новая установка
  • Обновление
  • Доустановка
  • Удаление
• Важные особенности и подводные камни
  • Новая установка требует пустую директорию
  • Docker Compose должен быть v2
  • Docker daemon должен быть запущен
  • Registry должен быть доступен по сети
  • --scheme https не включает TLS автоматически
  • LiveKit требует корректные внешние адреса
  • LiveKit использует общий Redis
  • Порты должны быть свободны
  • install-summary.txt содержит секреты
  • Ручные изменения конфигов отслеживаются
  • --dry-run не меняет live-файлы и контейнеры
  • Docker volumes удаляются только явно
  • Запуск установщика через Docker требует правильных путей
• Запуск установщика через Docker-образ
• Полезные команды после установки
• FAQ
  • Можно ли запустить установщик без аргументов?
  • Какой режим лучше: интерактивный или CLI?
  • Что делать, если установщик пишет, что Docker не найден?
  • Что делать, если Docker daemon не отвечает?
  • Что делать, если registry недоступен?
  • Что делать, если порт занят?
  • Можно ли установить в директорию, где уже есть файлы?
  • Где посмотреть адрес установленного NextBox?
  • Что такое .nextbox-file-state.json?
  • Почему установщик просит --accept-drift?
  • Будут ли удалены данные при удалении?
  • Можно ли удалить только один компонент?
  • Можно ли доустановить OnlyOffice позже?
  • Почему компоненты нельзя поставить без NextBox?
  • Как установить Callbox?
  • Как включить HTTPS?
  • Что делать после успешной установки?
  • Можно ли хранить install-summary.txt в системе контроля версий?
  • Как понять, какую версию установил installer?
  • Что делать, если установка прервалась?

Что делает установщик

nextbox-installer автоматизирует подготовку NextBox окружения на Docker Compose.

Он умеет:

• создавать новую установку;
• обновлять версию образов в существующей установке;
• доустанавливать компоненты без удаления уже работающих сервисов;
• удалять отдельные компоненты или всю установку;
• находить существующие установки в типичных директориях и среди Docker Compose проектов;
• выполнять предпроверки: Docker, Docker Compose, Docker daemon, доступность registry, права на директорию, свободное место и занятость портов;
• генерировать docker-compose.yaml, Caddyfile, конфигурации LiveKit, Security и служебные файлы;
• сохранять контрольный слепок конфигов и предупреждать, если файлы были изменены вручную;
• запускать docker compose pull, docker compose up -d, docker compose down и связанные команды.

Важно

Установщик не заменяет Docker. Docker должен быть установлен и запущен заранее.

Требования

Общие требования

• Docker.
• Docker Compose v2, то есть команда docker compose, а не только старый docker-compose.
• Доступ к Docker daemon.
• Доступ к registry nextbox-docker.ptnl.moscow.
• Свободные порты для выбранных компонентов.
• Доступ на запись в директорию установки.
• Минимум 2 GiB свободного места. Если свободно меньше 10 GiB, установщик покажет предупреждение.

Windows

На Windows рекомендуется запускать nextbox-installer.exe напрямую.

Требуется:

• Docker Desktop;
• режим Linux containers;
• WSL2 backend;
• запущенный Docker Desktop.

По умолчанию директория установки на Windows:

%USERPROFILE%\NextBox

Пример:

.\nextbox-installer.exe install --profile nextbox --dir "$env:USERPROFILE\NextBox" --domain 10.8.1.2

Linux

По умолчанию директория установки:

/opt/nextbox

Пример:

./nextbox-installer install --profile nextbox --dir /opt/nextbox --domain 10.8.1.2

Если у пользователя нет доступа к Docker, добавьте его в группу docker или запускайте команды с нужными правами.

Доступ к registry

Registry nextbox-docker.ptnl.moscow общедоступен и не требует авторизации.

docker pull nextbox-docker.ptnl.moscow/nextbox/frontend:oak-1.11.0

На Windows:

docker pull nextbox-docker.ptnl.moscow/nextbox/frontend:oak-1.11.0

Скачивание установщика

Скачайте установщик для вашей операционной системы:

Платформа	Ссылка
Linux amd64	nextbox-installer
Windows amd64	nextbox-installer.exe

Linux

curl -fL \
  -o nextbox-installer \
  https://nextbox-nexus.ptnl.moscow/repository/nextbox-raw/nextbox-installer/linux-amd64/nextbox-installer

chmod +x nextbox-installer

./nextbox-installer --help

Windows

PowerShell:

Invoke-WebRequest `
  -Uri "https://nextbox-nexus.ptnl.moscow/repository/nextbox-raw/nextbox-installer/windows-amd64/nextbox-installer.exe" `
  -OutFile ".\nextbox-installer.exe"

.\nextbox-installer.exe --help

Компоненты и профили

Установщик поддерживает готовые профили и ручной выбор компонентов.

Профили

Профиль	Что устанавливает
nextbox	базовый NextBox
nextbox-callbox	NextBox, Callbox, LiveKit
nextbox-callbox-onlyoffice	NextBox, Callbox, LiveKit, OnlyOffice
full	NextBox, Callbox, LiveKit, OnlyOffice, PDF Editor, Security

Компоненты

Компоненты можно указать вручную через --components.

Компонент	Назначение
nextbox	основной NextBox
callbox	звонки и связанные API
livekit	медиа-сервер для звонков
onlyoffice	редактор документов
pdf	PDF Editor
security	Security модуль
dlp	DLP интеграция Infowatch, включает Security
kesl	антивирусная интеграция KESL, включает Security

Важно

Любой компонент кроме самого nextbox устанавливается поверх NextBox. Для callbox, livekit, onlyoffice, pdf, security, dlp и kesl должен быть включен nextbox.

Перед началом

1. Убедитесь, что Docker запущен:

docker info

2. Проверьте Docker Compose v2:

docker compose version

3. Выберите директорию установки.

Для новой установки директория должна быть пустой или отсутствовать. Если в ней уже есть docker-compose.yaml, .version или install-summary.txt, установщик посчитает, что там уже есть установка NextBox.

4. Выберите домен или IP сервера.

Значение --domain используется для внешних URL, конфигурации LiveKit и итоговой сводки.

Быстрая установка

Только NextBox

Linux:

./nextbox-installer install \
  --profile nextbox \
  --dir /opt/nextbox \
  --domain 10.8.1.2

Windows:

.\nextbox-installer.exe install `
  --profile nextbox `
  --dir "$env:USERPROFILE\NextBox" `
  --domain 10.8.1.2

После завершения NextBox будет доступен по адресу:

http://<domain>:8095/

Если вы указали --domain 10.8.1.2, адрес будет:

http://10.8.1.2:8095/

Полная установка

./nextbox-installer install \
  --profile full \
  --dir /opt/nextbox \
  --domain nextbox.example.local \
  --nextbox-port 8095 \
  --livekit-port 7880 \
  --livekit-tcp-port 7881 \
  --livekit-udp-port 3478

Ручной выбор компонентов

./nextbox-installer install \
  --components nextbox,callbox,livekit,onlyoffice,pdf \
  --dir /opt/nextbox \
  --domain 10.8.1.2

Security с DLP и KESL

./nextbox-installer install \
  --components nextbox,security,dlp,kesl \
  --dir /opt/nextbox \
  --domain 10.8.1.2 \
  --infowatch-ip 10.0.0.10 \
  --infowatch-token token \
  --infowatch-company Example \
  --kesl-ip 10.0.0.11

Интерактивный режим

Если запустить установщик без аргументов, откроется интерактивный TUI:

./nextbox-installer

На Windows:

.\nextbox-installer.exe

В интерактивном режиме можно выбрать:

• режим: установка, обновление, доустановка или удаление;
• профиль или отдельные компоненты;
• версию;
• директорию установки;
• домен или IP;
• порты;
• запуск docker compose pull;
• запуск docker compose up -d;
• dry-run со staging-проверкой без изменения live-файлов и контейнеров;
• удаление Docker volumes при удалении.

На экране подтверждения показано компактное решение: итог, риски и опции запуска. Клавиша p открывает полный прокручиваемый план, p или Enter возвращает к решению.

Интерактивный режим и CLI используют один движок операций: инспекция установки, построение и валидация плана, рендер в staging, docker compose config, атомарная замена файлов, pull/up --wait и фиксация контрольного слепка.

CLI-режим

CLI удобен для автоматизации, инструкций внедрения и повторяемых установок.

Общий формат:

./nextbox-installer <command> [flags]

Доступные команды:

Команда	Назначение
install	создать новую установку
update	обновить версию образов существующей установки
extend	доустановить компоненты
remove	удалить компоненты или всю установку
detect	найти установки NextBox
current	показать состояние текущей установки
preflight	выполнить только предпроверку
plan	показать план без выполнения

Основные флаги

Флаг	Описание	Значение по умолчанию
--dir	директория установки	Windows: %USERPROFILE%\NextBox, Linux: /opt/nextbox
--profile	готовый профиль установки	не выбран
--components	компоненты через запятую	не выбраны
--version	версия образов NextBox/Callbox	oak-1.11.0
--domain	IP или домен сервера	localhost
--scheme	схема внешних URL: http или https	http
--nextbox-port	внешний порт NextBox/Caddy	8095
--callbox-port	внешний порт Callbox API	8081
--livekit-port	HTTP порт LiveKit	7880
--livekit-tcp-port	TCP порт LiveKit WebRTC	7881
--livekit-udp-port	UDP порт LiveKit TURN	3478
--livekit-external	внешний адрес LiveKit	берется из --domain
--livekit-turn-domain	TURN-домен LiveKit без протокола и порта	вычисляется автоматически
--nextbox-api	URL NextBox/Callbox для LiveKit webhook	вычисляется автоматически
--recording	включить запись звонков Callbox через LiveKit Egress	false
--egress-files-url	внутренний или внешний URL файлов записей	не задан
--whisper-url	URL сервиса транскрибации	не задан
--vapid-public, --vapid-private	VAPID-ключи web push	не заданы
--push-proxy-url, --push-proxy-token	внешний сервис мобильных push-уведомлений	не задан
--ai-summary-url, --ai-summary-key, --ai-summary-model	OpenAI-compatible API для резюме записей	не задан
--pull=false	не выполнять docker compose pull	true
--up=false	не выполнять docker compose up/down	true
--dry-run	отрендерить и проверить staging без изменения live-файлов и Docker	false
--skip-preflight	пропустить предпроверку	false
--accept-drift	разрешить перезапись вручную измененных конфигов	false
--force	алиас для --accept-drift	false
--remove-volumes	удалить Docker volumes при удалении	false
--remove-configs=false	не удалять конфиги при полном удалении	true

Начиная с версии oak-1.11.0, профиль NextBox автоматически включает сервис spaces. При обновлении с alder-1.10.0 установщик добавляет его в существующий compose и переводит RabbitMQ и его consumers на единые user/password/vhost. Существующий пароль пользователя nextbox сохраняется; для legacy-конфигурации создается новый секрет, а user/vhost подготавливаются в уже существующем RabbitMQ volume до запуска всего стека. В более старых версиях сервис не генерируется.

Матрица обновлений

Разрешены повтор текущей версии и только прямой переход на соседний релиз:

Из версии	В версию
lilac-1.7.0	elm-1.8.1
elm-1.8.1	thuja-1.9.0
thuja-1.9.0	alder-1.10.0
alder-1.10.0	oak-1.11.0

Например, переход thuja-1.9.0 → oak-1.11.0 будет остановлен с предложением сначала установить alder-1.10.0. Downgrade и версии, отсутствующие в таблице, также блокируются до рендера staging и backup. В TUI следующий допустимый релиз выбирается автоматически; в CLI целевую версию необходимо явно передать через --version.

Проверить план перед установкой

./nextbox-installer plan \
  --mode install \
  --profile nextbox \
  --dir /opt/nextbox \
  --domain 10.8.1.2

Выполнить только предпроверку

./nextbox-installer preflight \
  --mode install \
  --profile nextbox \
  --dir /opt/nextbox \
  --domain 10.8.1.2

Проверить будущую конфигурацию без изменения установки

./nextbox-installer install \
  --profile nextbox \
  --dir /opt/nextbox \
  --domain 10.8.1.2 \
  --dry-run

Обновление

Обновление меняет теги образов NextBox/Callbox в docker-compose.yaml, обновляет .version, пересоздает контрольный слепок файлов и, если разрешено, выполняет Docker команды. До замены live-файлов всегда создается полный backup PostgreSQL через pg_dumpall. Старые установки с отдельным livekit_redis автоматически переводятся на общий Redis 7: перед major upgrade установщик выполняет SAVE и сохраняет RDB snapshot, LiveKit и Egress переводятся в logical DB 1, legacy-контейнер и сгенерированный redis.conf удаляются.

./nextbox-installer update \
  --dir /opt/nextbox \
  --version oak-1.11.0

Перед обновлением рекомендуется:

./nextbox-installer current --dir /opt/nextbox
./nextbox-installer plan --mode update --dir /opt/nextbox --version oak-1.11.0

Если конфигурационные файлы были изменены вручную, установщик остановится и попросит повторить команду с --accept-drift.

./nextbox-installer update \
  --dir /opt/nextbox \
  --version oak-1.11.0 \
  --accept-drift

Перед перезаписью измененных файлов будут созданы резервные копии вида:

<имя-файла>.bak-YYYYMMDD-HHMMSS

Backup базы сохраняется отдельно:

<директория-установки>/backups/pre-update-<текущая>-to-<целевая>-YYYYMMDD-HHMMSS.sql
<директория-установки>/backups/pre-update-<текущая>-to-<целевая>-YYYYMMDD-HHMMSS.redis.rdb

RDB-файл создаётся только при миграции persistent Redis с версии 6 на 7. При ошибке после начала изменения runtime установщик автоматически останавливает новый стек, возвращает прежние конфиги, восстанавливает SQL backup и, если выполнялся major upgrade Redis, возвращает исходный RDB snapshot, после чего запускает прежний стек. Backup-файлы не удаляются и после успешного обновления. Обычный downgrade на версию ниже текущей запрещен: восстановление старой версии доступно только как аварийная часть той же неуспешной операции обновления.

Доустановка компонентов

Доустановка добавляет новые компоненты в существующую установку.

Пример: добавить OnlyOffice и PDF Editor:

./nextbox-installer extend \
  --dir /opt/nextbox \
  --components onlyoffice,pdf

При доустановке установщик:

• читает текущий docker-compose.yaml;
• сохраняет существующие секреты;
• объединяет текущий состав компонентов с новыми;
• обновляет конфигурационные файлы;
• поднимает PostgreSQL;
• создает недостающие базы данных для новых компонентов;
• выполняет docker compose up -d.

Если доустанавливается любой компонент кроме самого NextBox, NextBox должен уже быть установлен или должен быть включен в итоговый состав.

Удаление

Удаление бывает частичным и полным.

Частичное удаление компонента

Пример: удалить только PDF Editor, не удаляя данные:

./nextbox-installer remove \
  --dir /opt/nextbox \
  --components pdf \
  --remove-volumes=false

При частичном удалении установщик:

• удаляет выбранные контейнеры через docker compose rm -sf;
• при включенном --remove-volumes удаляет связанные Docker volumes выбранных компонентов;
• пересобирает docker-compose.yaml для оставшихся компонентов;
• запускает оставшуюся установку через docker compose up -d --remove-orphans.

Полное удаление без удаления данных

./nextbox-installer remove \
  --dir /opt/nextbox \
  --components nextbox \
  --remove-volumes=false

При полном удалении без --remove-volumes выполняется docker compose down. Docker volumes с данными остаются.

Полное удаление вместе с данными

./nextbox-installer remove \
  --dir /opt/nextbox \
  --components nextbox \
  --remove-volumes=true

Осторожно

--remove-volumes=true удаляет Docker volumes. Это может удалить пользовательские данные, базы данных, файлы и состояние сервисов. Используйте этот флаг только если данные больше не нужны или уже есть резервная копия.

Удалить контейнеры, но оставить конфиги

По умолчанию при полном удалении установщик удаляет конфигурационные файлы. Чтобы оставить их:

./nextbox-installer remove \
  --dir /opt/nextbox \
  --components nextbox \
  --remove-configs=false

Проверки и диагностика

Найти установки NextBox

./nextbox-installer detect

Установщик ищет:

• директорию из NEXTBOX_INSTALL_DIR;
• директорию по умолчанию;
• ~/NextBox, ~/nextbox, ~/Documents/NextBox, ~/Documents/nextbox;
• на Windows: C:\NextBox, %ProgramData%\NextBox;
• на Linux: /opt/nextbox, /srv/nextbox, /var/lib/nextbox, /usr/local/nextbox;
• Docker Compose проекты с подходящими labels.

Показать текущую установку

./nextbox-installer current --dir /opt/nextbox

Команда показывает директорию, версию, компоненты, порты, URL, состояние файлов и сервисы.

Только предпроверка

./nextbox-installer preflight \
  --mode install \
  --profile full \
  --dir /opt/nextbox \
  --domain nextbox.example.local

Предпроверка проверяет:

• платформу;
• наличие Docker;
• наличие Docker Compose v2;
• доступность Docker daemon;
• директорию установки;
• контрольный слепок файлов для обновления и доустановки;
• свободное место;
• доступность registry;
• занятость портов для новой установки.

Только план действий

./nextbox-installer plan \
  --mode remove \
  --dir /opt/nextbox \
  --components onlyoffice

План показывает, какие контейнеры, порты, файлы и Docker команды будут затронуты.

Какие файлы создает установщик

В директории установки создаются служебные и конфигурационные файлы.

Файл	Назначение
docker-compose.yaml	основной Docker Compose файл
Caddyfile	конфигурация Caddy для NextBox и расширений
default.conf	конфигурационный файл, если нужен текущей сборке
.version	текущая версия образов
install-summary.txt	сводка установки, URL и секреты
.nextbox-file-state.json	контрольный слепок с хешами файлов
init-db.sql	начальная подготовка баз PostgreSQL
livekit.yaml	конфигурация LiveKit
egress.yaml	конфигурация LiveKit Egress
security_config.yaml	конфигурация Security интеграций

Секреты

install-summary.txt содержит секреты. Не публикуйте его и не отправляйте в открытые каналы. На Linux рекомендуется ограничить доступ к файлу командой chmod 600 install-summary.txt.

Как работает установщик

Новая установка

1. Читает параметры из TUI или CLI.
2. Проверяет выбранные компоненты, версию, директорию и порты.
3. Выполняет preflight-проверки.
4. Генерирует секреты, если они не были заданы ранее.
5. Создает конфигурационные файлы в директории установки.
6. Сохраняет контрольный слепок файлов в .nextbox-file-state.json.
7. Выполняет docker compose pull, если не указан --pull=false.
8. Выполняет docker compose up -d, если не указан --up=false.

Обновление

1. Находит текущую установку по --dir.
2. Читает .version.
3. Проверяет целевую версию по матрице: разрешает текущий или соседний forward-релиз, запрещает прыжки, неизвестные версии и downgrade.
4. Проверяет контрольный слепок файлов.
5. Рендерит кандидат в staging и проверяет его через docker compose config.
6. Поднимает PostgreSQL при необходимости и сохраняет полный pg_dumpall в backups/; при переходе общего Redis с версии 6 на 7 дополнительно сохраняет RDB snapshot.
7. Атомарно обновляет docker-compose.yaml и .version.
8. Выполняет docker compose pull; при переходе на oak-1.11.0 подготавливает RabbitMQ user/vhost.
9. Выполняет docker compose up -d --wait, если это не отключено.
10. Обновляет контрольный слепок. При ошибке после начала runtime-изменений автоматически восстанавливает файлы, PostgreSQL, Redis snapshot при его наличии и старый стек.

Доустановка

1. Читает текущий docker-compose.yaml.
2. Определяет уже установленные компоненты.
3. Сохраняет существующие секреты.
4. Добавляет новые компоненты к текущему составу.
5. Создает резервные копии измененных вручную файлов.
6. Перегенерирует конфигурационные файлы.
7. Поднимает PostgreSQL и создает недостающие базы данных.
8. Запускает обновленный compose.

Удаление

1. Определяет текущую установку.
2. Определяет выбранные для удаления компоненты.
3. Если остается часть установки, удаляет выбранные контейнеры и пересобирает compose.
4. Если удаляется все, выполняет docker compose down или docker compose down -v.
5. При полном удалении удаляет конфигурационные файлы, если не указан --remove-configs=false.

Важные особенности и подводные камни

Новая установка требует пустую директорию

Для новой установки директория должна быть пустой. Если директория не пустая, выберите другую директорию или используйте режим обновления/доустановки для существующей установки.

Docker Compose должен быть v2

Установщик вызывает:

docker compose ...

Если доступна только команда docker-compose, установите Compose v2 plugin.

Docker daemon должен быть запущен

Если Docker Desktop закрыт или daemon недоступен, установщик не сможет скачать и запустить контейнеры.

На Windows обычно помогает:

• запустить Docker Desktop;
• включить Linux containers;
• дождаться статуса Docker Desktop Running.

Registry должен быть доступен по сети

Registry nextbox-docker.ptnl.moscow общедоступен. Если при docker compose pull возникают ошибки, проверьте сетевой доступ, DNS, proxy/firewall и доступность Docker daemon.

docker pull nextbox-docker.ptnl.moscow/nextbox/frontend:oak-1.11.0

--scheme https не включает TLS автоматически

Флаг --scheme влияет на внешние URL в конфигурации и сводке. Встроенный Caddy в генерируемой конфигурации слушает HTTP и имеет auto_https off.

Если нужен HTTPS, обычно ставят внешний reverse proxy или балансировщик с TLS-сертификатом перед NextBox.

LiveKit требует корректные внешние адреса

Для LiveKit важны:

• --livekit-external: внешний адрес, по которому клиенты будут подключаться к LiveKit;
• --livekit-turn-domain: TURN-домен без http://, https://, пути и порта;
• открытые TCP/UDP порты.

TURN-домен не должен быть localhost.

LiveKit использует общий Redis

Отдельный контейнер Redis для LiveKit не создается. Профили с LiveKit используют общий сервис redis на redis:6379:

• сервисы NextBox и Callbox продолжают использовать DB 0;
• LiveKit и Egress используют DB 1;
• LiveKit и Egress всегда должны ссылаться на одинаковые Redis address и DB;
• общий образ автоматически переключается на Redis 7 при установке или доустановке LiveKit.

При обновлении старой установки или доустановке LiveKit сервис livekit_redis удаляется из Compose, зависимости переводятся на redis, а livekit.yaml и egress.yaml обновляются атомарно. Устаревший redis.conf также удаляется. Если операция завершается неуспешно после запуска Redis 7, установщик возвращает прежнюю конфигурацию, восстанавливает сохранённый Redis 6 RDB snapshot и поднимает предыдущий стек.

Порты должны быть свободны

По умолчанию используются:

Сервис	Порт
NextBox/Caddy	8095/tcp
Callbox API	8081/tcp
LiveKit HTTP	7880/tcp
LiveKit TCP WebRTC	7881/tcp
LiveKit TURN UDP	3478/udp

Если порт занят, укажите другой порт через соответствующий флаг.

install-summary.txt содержит секреты

Файл нужен администратору, но его нельзя публиковать. В нем могут быть service token, JWT secret, LiveKit API key/secret и другие чувствительные значения.

Ручные изменения конфигов отслеживаются

После генерации установщик сохраняет хеши конфигурационных файлов. При обновлении или доустановке он проверяет, не изменились ли файлы вручную.

Если изменения найдены, команда остановится. Чтобы продолжить, сначала посмотрите план, затем запустите команду с:

--accept-drift

Перед перезаписью будут созданы .bak-* копии.

--dry-run не меняет live-файлы и контейнеры

--dry-run рендерит кандидат конфигурации во временную staging-директорию, запускает для него docker compose config, а затем удаляет staging. Live-файлы, backup базы, контрольный слепок и контейнеры не изменяются.

Docker volumes удаляются только явно

Удаление Docker volumes происходит только при --remove-volumes=true. Без этого данные остаются в volumes даже после docker compose down.

Запуск установщика через Docker требует правильных путей

Если установщик запускается внутри Docker-контейнера, путь в --dir должен совпадать с путем, который видит Docker daemon. Это важно для bind mounts в docker-compose.yaml.

На Windows надежнее запускать nextbox-installer.exe напрямую.

Запуск установщика через Docker-образ

Можно запустить установщик из Docker-образа. Образу нужен доступ к Docker socket.

Сборка:

docker build -t nextbox-installer:local .

Установка на Linux:

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/nextbox:/opt/nextbox \
  nextbox-installer:local install \
  --profile full \
  --dir /opt/nextbox \
  --domain 10.8.1.2

План без изменений:

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/nextbox:/opt/nextbox \
  nextbox-installer:local plan \
  --mode install \
  --profile nextbox \
  --dir /opt/nextbox \
  --domain 10.8.1.2

Доустановка:

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/nextbox:/opt/nextbox \
  nextbox-installer:local extend \
  --dir /opt/nextbox \
  --components onlyoffice,pdf

Удаление компонента:

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/nextbox:/opt/nextbox \
  nextbox-installer:local remove \
  --dir /opt/nextbox \
  --components pdf \
  --remove-volumes=false

Полезные команды после установки

Выполняйте команды из директории установки.

Перейти в директорию:

cd /opt/nextbox

Показать контейнеры:

docker compose ps

Посмотреть логи всех сервисов:

docker compose logs -f

Посмотреть логи конкретного сервиса:

docker compose logs -f gateway

Перезапустить сервисы:

docker compose up -d

Остановить сервисы без удаления данных:

docker compose down

Скачать новые образы и перезапустить:

docker compose pull
docker compose up -d

FAQ

Можно ли запустить установщик без аргументов?

Да. Без аргументов запускается интерактивный TUI:

./nextbox-installer

Какой режим лучше: интерактивный или CLI?

Для первой ручной установки удобен интерактивный режим. Для повторяемых установок, инструкций внедрения и автоматизации лучше CLI.

Что делать, если установщик пишет, что Docker не найден?

Установите Docker и убедитесь, что команда docker доступна в PATH.

Проверьте:

docker version

Что делать, если Docker daemon не отвечает?

На Windows запустите Docker Desktop и дождитесь, пока он полностью стартует. Проверьте, что включен режим Linux containers.

На Linux проверьте сервис Docker:

systemctl status docker

Что делать, если registry недоступен?

Проверьте сетевой доступ к nextbox-docker.ptnl.moscow, DNS, proxy/firewall и работу Docker daemon:

docker pull nextbox-docker.ptnl.moscow/nextbox/frontend:oak-1.11.0

Что делать, если порт занят?

Выберите другой порт.

Например, для NextBox:

./nextbox-installer install \
  --profile nextbox \
  --dir /opt/nextbox \
  --domain 10.8.1.2 \
  --nextbox-port 8088

Можно ли установить в директорию, где уже есть файлы?

Для новой установки нет. Директория должна быть пустой или отсутствовать. Это защита от перезаписи чужих файлов.

Для существующей установки используйте update, extend или remove.

Где посмотреть адрес установленного NextBox?

Откройте файл:

install-summary.txt

Или выполните:

./nextbox-installer current --dir /opt/nextbox

Что такое .nextbox-file-state.json?

Это контрольный слепок конфигурационных файлов. Установщик использует его, чтобы понять, были ли файлы изменены вручную после установки.

Почему установщик просит --accept-drift?

Он обнаружил, что конфигурационные файлы отличаются от состояния, которое сам же зафиксировал после предыдущей установки или обновления.

Сначала посмотрите план:

./nextbox-installer plan --mode update --dir /opt/nextbox --version oak-1.11.0

Если изменения понятны и вы готовы продолжить:

./nextbox-installer update --dir /opt/nextbox --version oak-1.11.0 --accept-drift

Будут ли удалены данные при удалении?

Только если явно указать:

--remove-volumes=true

Без этого Docker volumes остаются.

Можно ли удалить только один компонент?

Да. Например:

./nextbox-installer remove --dir /opt/nextbox --components onlyoffice

Установщик пересоберет compose для оставшихся компонентов.

Можно ли доустановить OnlyOffice позже?

Да:

./nextbox-installer extend --dir /opt/nextbox --components onlyoffice

Почему компоненты нельзя поставить без NextBox?

Все компоненты кроме самого nextbox работают как расширения NextBox или его инфраструктуры. Поэтому NextBox должен быть установлен или выбран в составе установки.

Как установить Callbox?

Callbox, как и остальные компоненты, устанавливается только поверх NextBox. Для новой установки используйте профиль nextbox-callbox:

./nextbox-installer install \
  --profile nextbox-callbox \
  --dir /opt/nextbox \
  --domain nextbox.example.local

Для уже установленного NextBox используйте доустановку:

./nextbox-installer extend --dir /opt/nextbox --components callbox

Как включить HTTPS?

Флаг --scheme https формирует внешние URL с https, но не выпускает сертификаты и не включает TLS во встроенном Caddy.

Для HTTPS используйте внешний reverse proxy, балансировщик или другой слой TLS перед NextBox.

Что делать после успешной установки?

Проверьте контейнеры:

cd /opt/nextbox
docker compose ps

Откройте URL из install-summary.txt или из вывода команды:

./nextbox-installer current --dir /opt/nextbox

Можно ли хранить install-summary.txt в системе контроля версий?

Нет. Файл содержит секреты и должен оставаться только у администратора установки.

Как понять, какую версию установил installer?

Версия образов записывается в файл:

.version

Также ее показывает:

./nextbox-installer current --dir /opt/nextbox

Что делать, если установка прервалась?

1. Посмотрите вывод установщика и логи Docker.
2. Проверьте состояние контейнеров:

cd /opt/nextbox
docker compose ps
docker compose logs -f

3. После исправления причины повторите команду установки или выполните:

docker compose up -d

Если директория уже содержит сгенерированные файлы, новая команда install может не пройти из-за защиты от непустой директории. В таком случае проверьте файлы, удалите некорректную незавершенную установку вручную или используйте подходящий режим обслуживания.