Narvelium Платформа
ПорталNarvelium Starter
Развёртывание

Воспроизводимая установка Narvelium

Руководство описывает установку из основного репозитория Haper-Forge/narvelium-lms: схема базы управляется миграциями Alembic, мастер первичной настройки в рабочем контуре закрыт, лицензия второй версии подписывается Ed25519, а настройки конкретного заказчика задаются переменными окружения.

0. Что даёт портал

Портал включает обучение и тесты, цифровой центр, роли и права доступа, видимость данных на уровне записей, журнал действий, вход через OIDC/Keycloak и AD/LDAP, связку с Bitrix24, чтение данных из 1С по OData, миграции схемы Alembic, лицензию второй версии с подписью Ed25519 и подписанными правами на модули, учёт активных рабочих мест и расширения. Для запуска нужны сервер с Linux и Docker, внешний обратный прокси с TLS-сертификатом и сетевой доступ только к тем корпоративным системам, которые вы решили подключить.

1. Требования

ПараметрМинимум для установки
ОСLinux x86_64, рекомендуется Ubuntu 24.04 LTS
Процессор / память2 виртуальных ядра / 4 ГБ
Диск30 ГБ плюс отдельный запас под резервные копии
Среда выполненияDocker Engine 24+ / Docker Compose v2
TLSВнешний обратный прокси на 127.0.0.1:8090

2. Настройка окружения

1

Создайте .env

cp .env.example .env
python3 scripts/init_local_env.py

Файл .env с реальными значениями в репозиторий не попадает. Для рабочего контура проверьте как минимум:

APP_ENVIRONMENT=production
DEV_MODE=false
POSTGRES_DB=...
POSTGRES_USER=...
POSTGRES_PASSWORD=<strong random>
SECRET_KEY=<32+ chars>
SUPERADMIN_EMAIL=admin@company.ru
LICENSE_V1_HMAC_ENABLED=false
LICENSE_V2_PUBLIC_KEY_PATH=/app/certs/narvelium-license-public.pem

Вход по коду из письма, AD, OIDC, демонстрационный режим и 1С включаются только явными настройками окружения. Корневой сертификат заказчика размещается локально в ./certs и подключается только для чтения в /app/certs.

3. Запуск приложения

docker compose config
docker compose up -d postgres-anon
docker compose run --rm backend-anon alembic -c /app/alembic.ini upgrade head
docker compose up -d --build backend-anon nginx-anon
curl -fsS http://127.0.0.1:8090/healthz
curl -fsS http://127.0.0.1:8090/readyz
curl -fsS http://127.0.0.1:8090/api/product/capabilities

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

4. Внешний TLS и обратный прокси

Публичный сайт и приложение работают на одном домене: https://narvelium.ru/ и /lms/. Внешний nginx или Apache передаёт запросы /lms/ на локальный адрес http://127.0.0.1:8090/. В основном репозитории есть готовые примеры настроек для обоих вариантов.

Для публичного сайта обязательны HSTS, запрет подмены типа содержимого (nosniff), политика встраивания в рамку, запрет выдачи секретов, дампов и ключей, а также CSP. Цифровой центр не использует встроенные скрипты, и ослаблять CSP без необходимости не следует.

5. Первый администратор

SUPERADMIN_EMAIL задаёт первого администратора с полным доступом. Вход по коду из письма требует EMAIL_AUTH_ENABLED=true и работающего почтового сервера. Для корпоративного контура доступны вход через AD/LDAPS и OIDC/Keycloak. Вход по логину и паролю на стендах и в рабочем контуре не допускается, а демонстрационный режим включается только явной настройкой и защищён кодом доступа.

6. Лицензия второй версии

Приложение принимает лицензии nv2.* с подписью Ed25519 и проверяет их только открытым ключом. В лицензии указаны постоянный installation_id, редакция, max_users, срок действия и подписанные права на модули. Закрытый ключ подписи хранится только в сервисе лицензий.

Для поставки лицензий второй версии укажите LICENSE_V1_HMAC_ENABLED=false. Старый формат HMAC поддерживается только для совместимости при обновлении. Подробности: страница лицензирования.

7. Обновление

Обновление выполняется только на согласованную версию (SHA или тег). Перед переключением создаётся резервная копия, затем применяются миграции alembic upgrade head, пересобирается серверная часть и проверяется /readyz.

git fetch --prune origin
git reset --hard <approved-sha>
docker compose up -d postgres-anon
docker compose run --rm backend-anon alembic -c /app/alembic.ini upgrade head
docker compose build --pull backend-anon
docker compose up -d --no-deps --force-recreate backend-anon nginx-anon

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

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

Используйте штатный сценарий из поставки:

scripts/backup_instance.sh /srv/backups/narvelium

Он сохраняет базу PostgreSQL, постоянные данные data/app, опись и контрольную сумму SHA-256. Файл .env по умолчанию в копию не попадает; включать его следует только в защищённом и зашифрованном контуре резервного копирования. Для общего сценария резервного копирования на сервере разрешён режим --optional: намеренно остановленная установка не должна срывать копирование других сервисов на этом сервере, но реальная ошибка pg_dump остаётся ошибкой.

Подробности: docs/BACKUP_OPERATIONS.md.

9. Минимальная приёмка

  1. /healthz и /readyz — HTTP 200.
  2. Версия схемы совпадает с текущей версией миграций Alembic.
  3. /api/product/capabilities — единая архитектура портала.
  4. Лицензия второй версии проверяется открытым ключом Ed25519 и связана с текущим installation_id.
  5. Шестой активный пользователь не проходит проверку по числу рабочих мест.
  6. Отключённое право на модуль недоступно и при прямом вызове API.
  7. Обычный сотрудник не видит чужие проекты, задачи и данные о загрузке.
  8. OIDC, AD, Bitrix24 и 1С проходят отдельную приёмку при подключении.
  9. Резервная копия создана, а проверка восстановления выполнена на отдельном стенде.
  10. Версия, запущенная в рабочем контуре, присутствует в основном репозитории narvelium-lms.

Перечисленные проверки выполняются на согласованном стенде; основной сценарий проверки — scripts/portal_release_acceptance.py. Результаты фиксируются в протоколе приёмки.