OmniLux Docs

Appearance

Updating OmniLux ​

Use this page as the operational checklist before and after upgrades.

Before updating ​

Back up your database before any update:

bash
# Docker
docker cp omnilux:/app/data/omnilux.db ./omnilux.db.bak

# Bare metal
cp /var/lib/omnilux/omnilux.db /var/lib/omnilux/omnilux.db.bak

Docker ​

For image-based installs, the normal flow is pull, restart, then verify health:

bash
docker compose pull
docker compose up -d

If you build from source:

bash
git pull
docker compose up --build -d

Bare metal ​

For source-based installs, pull, rebuild, restart, then verify the service:

bash
cd /opt/omnilux
git pull
pnpm install
pnpm build
sudo systemctl restart omnilux

Database migrations ​

Migrations run automatically when OmniLux starts. There's no manual migration step. The migration system is sequential (001 through 090+) and each migration is applied exactly once.

If a migration fails, OmniLux will log the error and refuse to start. In that case:

  1. Check the logs for the specific migration error
  2. Restore your database backup
  3. Report the issue on GitHub

Downgrading ​

Downgrading is not officially supported because database migrations are forward-only. If you need to roll back:

  1. Stop OmniLux
  2. Restore your database backup
  3. Check out the previous version: git checkout v0.x.x
  4. Rebuild and restart

Checking the current version ​

The version is displayed in the web UI footer and available via the health endpoint:

bash
curl http://localhost:4000/api/health

After updating ​

Confirm these before you call the upgrade done:

  1. The web UI loads.
  2. api/health responds successfully.
  3. Background scans and playback still work.
  4. Any reverse proxy or remote path still reaches the server.