Umbryx Core installation¶

End-to-end from a fresh clone to a working instance. Commands are the real ones from the repository.

1. Get the source¶

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

2. Configure the environment¶

cp .env.example .env

Minimum day-one values (see the Configuration reference for the full list):

DB_PASSWORD="<strong-postgres-password>"
JWT_SECRET="$(openssl rand -hex 32)"
ENCRYPTION_KEY="$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")"
ADMIN_PASSWORD="<strong-admin-password>"
APP_ENV=production

With APP_ENV=production the backend refuses to start without an explicit, well-formed ENCRYPTION_KEY — do not rely on auto-generation outside dev.

3. Start the stack¶

docker compose up -d --build

This builds the backend and frontend images and starts five services: db (PostgreSQL 16), redis, backend, frontend, nginx. Database migrations run automatically on backend startup (Alembic upgrade head) — there is no manual migration step.

Open http://<host>:3000.

On a fresh database the login screen offers to create the administrator account (first-run setup).
Set SETUP_TOKEN=<random> in .env beforehand if you want that screen gated with a token.
If ADMIN_USERNAME/ADMIN_PASSWORD are set in the environment at first start, the admin is created automatically instead.

Continue with Verification.

Alternative: the installer wizard¶

./install.sh            # interactive: single-node mode
./install.sh --dry-run  # preview without changes

Air-gapped Core¶

An offline bundle can be built with scripts/build-airgap-bundle.sh (images + checksums + compose + installer). The same script exists in both editions; note that Core does not need any license activation afterwards.

Updating¶

git pull
docker compose up -d --build

Migrations run on startup. Back up before upgrading — especially the data/ directory and the database, since ENCRYPTION_KEY-encrypted data is unrecoverable without it (see Backup and restore).

Common installation problems¶

Symptom	Cause / fix
Backend exits: `ENCRYPTION_KEY must be explicitly set when APP_ENV='production'`	Expected fail-fast — set a valid Fernet key in `.env`
Backend exits: `invalid format (not a valid Fernet key)`	Typo in the key; regenerate
`password authentication failed for user "umbryx"`	`DB_PASSWORD` changed after the DB volume was initialized — reset the volume (`docker compose down -v`, data loss) or restore the old password
App unreachable	Check the published `PORT` (default 3000) and that `docker compose ps` shows all services healthy
Migrations fail	Ensure the code and the database come from the same version; restore a backup or `alembic stamp <revision>` deliberately