Установить NGENSIA с готовой конфигурацией

Проверьте серверный комплект

Команда install и создание первого Superuser относятся к локальному кандидату нового установщика. Его поставка на действующий сервер не подтверждена. До начала получите проверенный комплект у сопровождающего; прежний установщик для этого сценария не подходит. Применимость инструкции.

Этот сценарий устанавливает конфигурацию NGENSIA и создаёт первого Superuser. Старые рабочие данные не переносятся. Это не пустая коммерческая конфигурация и не восстановление действующей системы.

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

Первый раз устанавливаете сервер? Начните с подготовки с нуля. Там показано, где вводить команды, как подключиться по SSH, получить права и установить Docker, Compose и Python. Возвращайтесь сюда после итогового списка проверок.

• Отдельная Linux-машина x86_64, Docker Engine и Compose.
• Python 3.8+, util-linux, права на Docker.
• Доверенный комплект выпуска: папка deploy, архив образа и файлы контрольных сумм/манифеста.
• Согласованные домен, место для данных и внешний каталог резервных копий.

Какую ОС поставить? Готовые команды подготовки рассчитаны на Ubuntu Server 24.04 LTS x86_64. Debian, RHEL и другие Linux требуют проверки точной версии и адаптации подготовки сервера. Перед выбором прочитайте сравнение ОС и список проверок совместимости. Поддержка ОС со стороны Docker сама по себе не подтверждает работу всего комплекта NGENSIA.

Нужен доступ сервера к реестрам закреплённых образов PostgreSQL и Caddy либо их заранее доставленные проверенные копии. Архив ngensia-image.tar содержит образ приложения, а не обязательно весь комплект для автономной установки без интернета.

До установки проверьте существующие процессы и свободные ресурсы:

uname -m
free -h
df -h /
docker version
docker compose version
docker ps
ss -lntup

Не переустанавливайте работающий Docker и не останавливайте соседние проекты. Требуемую мощность определяют по нагрузке; универсальной гарантии для малого VPS нет.

Права Linux

Текущий rootful Docker-комплект выполняйте из административной root-сессии, например после sudo -i, затем перейдите в каталог комплекта. Одного членства в группе docker недостаточно: runtime создаётся от root с правами 0700. Не ослабляйте эти права для обхода ошибки. Rootless Docker и user namespace в этом сценарии отдельно не квалифицированы.

1. Подготовьте комплект

Пример каталога — /opt/ngensia. Не кладите новый комплект поверх работающей установки.

1. Получите у сопровождающего проверенный комплект для этой процедуры. Публикация инструкции не означает, что новый установщик уже выпущен; случайной ссылки на скачивание здесь нет.
2. На своём компьютере откройте SFTP-клиент, подключитесь к тому же серверу с тем же пользователем, что использовали для SSH. Сверьте ключ сервера. Передайте комплект в отдельный пустой каталог в домашней папке этого пользователя. SFTP — защищённая передача файлов; это не загрузка через браузер NGENSIA.
3. В root-сессии сервера скопируйте содержимое полученного комплекта в новый пустой /opt/ngensia. Если SFTP-пользователь не имеет прав на /opt, это нормально: не открывайте каталог всем. Попросите администратора перенести файлы или используйте команду ниже с точным путём своего каталога.

Пример: SFTP передал распакованный комплект в /home/ubuntu/ngensia-bundle. Это пример пути, замените его своим; не копируйте внешнюю папку целиком вместо её содержимого. Если получили архив, используйте формат и команду распаковки из его сопроводительного файла: расширение и структура поставки могут отличаться.

ls -la /home/ubuntu/ngensia-bundle
ls -la /opt/ngensia

Продолжайте только если первый каталог содержит нужный комплект, а второй пуст (кроме . и ..). Тогда:

cp -a -- /home/ubuntu/ngensia-bundle/. /opt/ngensia/
cd /opt/ngensia
ls -l SHA256SUMS manifest.json ngensia-image.tar deploy/load-image.sh

Все четыре пути должны существовать. Если нет — проверьте, не получилась ли лишняя вложенная папка. Файл SHA256SUMS — список контрольных сумм, manifest.json — описание выпуска, ngensia-image.tar — образ приложения, deploy — серверные команды.

Проверьте целостность и загрузите образ. Команды ниже вводятся на сервере от root:

cd /opt/ngensia
sha256sum -c SHA256SUMS
cd deploy
sh load-image.sh

У всех перечисленных файлов ожидается OK. Если проверка не прошла, остановитесь и повторно получите комплект: контрольная сумма проверяет целостность, но не авторство. load-image.sh загружает образ и подставляет проверенный ID. Если он сообщает о существующей .env, не удаляйте её для обхода проверки: возможно, здесь уже готовили или запускали установку.

Откройте созданный файл настроек:

nano .env

В nano перемещайтесь стрелками. Для сохранения нажмите Ctrl+O, затем Enter, для выхода — Ctrl+X. Это сочетания клавиш, их не нужно вводить текстом.

Строка	Что указать
DOMAIN=	Свой домен, например helpdesk.example.com, без https://, порта и /
COMPOSE_PROJECT_NAME=	Уникальное имя новой установки, например ngensia-company-prod; не имя существующего проекта
ATTACHMENTS_STORAGE=	disk для первого запуска с вложениями на диске или s3 после выполнения инструкции S3
APP_IMAGE=, POSTGRES_IMAGE=, CADDY_IMAGE=	Оставить проверенные значения из комплекта; не заменять на latest

PostgreSQL — только 17. Остальные параметры и расположение данных. В частности, папка /opt/ngensia не означает, что все Docker-тома находятся в ней.

2. Подготовьте первого Superuser

Это будущий администратор NGENSIA в браузере, не пользователь Linux. В той же root-сессии создайте закрытый каталог и откройте файл:

umask 077
install -d -m 0700 /secure
test ! -e /secure/first-admin.json && nano /secure/first-admin.json

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

{
  "tenantId": "company",
  "login": "owner",
  "displayName": "Администратор",
  "email": "owner@example.com",
  "password": "ЗАМЕНИТЕ_НА_СВОЙ_УНИКАЛЬНЫЙ_ПАРОЛЬ"
}

Замените все значения своими. tenantId — постоянный технический код организации (например, company): до 64 символов, первый — латинская буква или цифра, остальные — латинские буквы, цифры, _ или -, без пробелов и кириллицы. login — имя для входа. Укажите действующий адрес ответственного администратора. Пароль — уникальный, от 12 до 256 символов, не совпадающий с логином; политика проверенного комплекта может предъявлять дополнительные требования. Сохраните его в менеджере паролей. Не передавайте пароль аргументом командной строки и не сохраняйте в Git.

Сохраните файл через Ctrl+O, Enter, Ctrl+X. Это JSON: нужны двойные кавычки, нельзя добавлять запятую после последнего поля. Кавычка внутри значения записывается как \", обратная косая черта — как \\. Проверка ниже проверяет формат, не печатая пароль:

python3 -c 'import json; json.load(open("/secure/first-admin.json", encoding="utf-8")); print("JSON OK")'

Продолжайте только после JSON OK. Затем запускайте команды по одной, дожидаясь завершения каждой:

chmod 600 /secure/first-admin.json
cd /opt/ngensia/deploy
sh ngensia.sh install /secure/first-admin.json
sh ngensia.sh start
sh ngensia.sh status

Нужны новый Compose-проект, отсутствие runtime и пустая база. install создаёт базу и конфигурацию с первым пользователем; start запускает приложение; status показывает состояние. Если любая команда завершилась ошибкой, не вводите следующую и не удаляйте тома: сохраните сообщение без секретов и выясните завершённый шаг с сопровождающим. Повторная установка поверх существующей запрещена.

3. Проверьте результат

Ожидаются здоровые контейнеры приложения и PostgreSQL. Выполните внутреннюю проверку, затем настройте домен и HTTPS в закрытом/согласованном контуре. Если сайт ещё не открывается по домену после start, это само по себе не ошибка: публичный прокси включается отдельным шагом.

Откройте в браузере https://ВАШ-ДОМЕН, убедитесь, что нет предупреждения о сертификате, и войдите логином и паролем из JSON. После успешного входа, когда пароль уже сохранён в менеджере, удалите только подготовленный вами файл:

rm -i -- /secure/first-admin.json

Команда спросит подтверждение. Это удаление файла, а не гарантированное стирание данных с носителя; не храните его копии, содержимое терминала или снимки с паролем в общих местах. Не удаляйте каталог runtime: там находятся секреты действующей системы.

Текущий экран входа. Используйте логин и пароль, заданные при установке.

Текущий экран входа. Используйте логин и пароль, заданные при установке.

Не смешивайте сценарии

Для старой системы с данными используйте восстановление, а не install. Создание новой конфигурации и восстановление копии — разные операции.

Что ещё нужно сделать

Установщик импортирует настройки и создаёт пользователя атомарно, но не назначает за вас новых исполнителей. Пройдите первичную настройку. Команда start сама не открывает интернет-порты и не включает все бизнес-обработчики.