Установка Umbryx Core¶

Полный путь от свежего клона до работающего экземпляра. Команды — реальные, из репозитория.

1. Получите исходники¶

git clone https://github.com/Umbryx-Project/umbryx-core.git
cd umbryx-core

2. Сконфигурируйте окружение¶

cp .env.example .env

Минимум на первый день (полный список — в Справочнике конфигурации):

DB_PASSWORD="<надёжный-пароль-postgres>"
JWT_SECRET="$(openssl rand -hex 32)"
ENCRYPTION_KEY="$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")"
ADMIN_PASSWORD="<надёжный-пароль-админа>"
APP_ENV=production

С APP_ENV=production бэкенд отказывается стартовать без явного корректного ENCRYPTION_KEY — не полагайтесь на автогенерацию вне dev.

3. Запустите стек¶

docker compose up -d --build

Соберутся образы backend и frontend и поднимутся пять сервисов: db (PostgreSQL 16), redis, backend, frontend, nginx. Миграции БД выполняются автоматически при старте бэкенда (Alembic upgrade head) — отдельного шага миграций нет.

4. Первый вход¶

Откройте http://<host>:3000.

На чистой БД экран входа предложит создать аккаунт администратора (first-run setup).
Задайте SETUP_TOKEN=<random> в .env заранее, если хотите закрыть этот экран токеном.
Если при первом старте заданы ADMIN_USERNAME/ADMIN_PASSWORD, админ создаётся автоматически.

Дальше — Верификация.

Альтернатива: мастер установки¶

./install.sh            # интерактивно: режим single-node
./install.sh --dry-run  # предпросмотр без изменений

Core в air-gap¶

Офлайн-бандл собирается scripts/build-airgap-bundle.sh (образы + чексуммы + compose + установщик). Скрипт одинаков в обоих изданиях; Core после установки не требует никакой лицензионной активации.

Обновление¶

git pull
docker compose up -d --build

Миграции применяются при старте. Создавайте резервную копию перед обновлением — особенно каталог data/ и БД: данные, зашифрованные ENCRYPTION_KEY, без него невосстановимы (см. Резервное копирование и восстановление).

Типичные проблемы установки¶

Симптом	Причина / решение
Бэкенд падает: `ENCRYPTION_KEY must be explicitly set when APP_ENV='production'`	Ожидаемый fail-fast — задайте корректный Fernet-ключ в `.env`
Бэкенд падает: `invalid format (not a valid Fernet key)`	Опечатка в ключе; сгенерируйте заново
`password authentication failed for user "umbryx"`	`DB_PASSWORD` изменён после инициализации volume БД — сбросьте volume (`docker compose down -v`, потеря данных) или верните старый пароль
Приложение недоступно	Проверьте публикуемый `PORT` (по умолчанию 3000) и что `docker compose ps` показывает все сервисы здоровыми
Миграции падают	Убедитесь, что код и БД одной версии; восстановите резервную копию или осознанно выполните `alembic stamp <revision>`

Подробнее — в Устранении неполадок.