opnexus – the command-line tool

With opnexus you update OPNexus with one command, roll back when something goes wrong and back up the database – without hand-editing containers or the database.

Overview

opnexus is a Bash script for installations that run from ready-made release images. It sits next to the docker-compose.yml in the release bundle and knows four commands:

Command	What it does
`opnexus status`	Shows the version, the services and the database revision.
`opnexus update [VERSION]`	Pulls new images, switches, waits for “healthy” and rolls back automatically if something fails.
`opnexus rollback`	Undoes the last update, including the database when needed.
`opnexus backup`	Writes a database backup right away.

Requirements

Docker with Compose v2 and Bash on the server.
An installation from the release bundle (ready-made images from the registry). Your .env contains OPNEXUS_IMAGE_REPO; the bundle already sets it. Without it the tool stops – it is not meant for local builds (use git pull && docker compose up -d --build there).
Run it in the folder with docker-compose.yml and .env, or from anywhere with OPNEXUS_DIR=/path/to/opnexus.

cd /opt/opnexus-1.15.0
./opnexus status

`status`

Shows what is running and, if there is one, the last update that can be rolled back.

$ ./opnexus status
Image-Repo:        git.opnexus.dev/opnexus
OPNEXUS_VERSION:   1
Laufende Version:  1.15.0
DB-Revision:       0004
backend: healthy
frontend: healthy
proxy: running

OPNEXUS_VERSION is the “track” the installation follows: a fixed version (1.15.0), a minor track (1.15), a major track (1) or latest. The labels in the output are in German, the tool's output language.

`update`

./opnexus update            # follow the track chosen in .env
./opnexus update 1.15.0     # fixed version
./opnexus update 1.15       # newest 1.15.x

How it runs, step by step:

Read the state. If the backend is not running or does not answer, the tool stops – repair first, then update.
Pull the images. Nothing changes on the running system meanwhile. If the pull fails, nothing was changed.
Remember the old state (file .opnexus-update-state) so a rollback knows where to go.
Switch. OPNEXUS_VERSION is set in .env, then docker compose up -d --no-build runs. If the new version needs a database migration, the backend backs the database up itself first (pre-upgrade-….dump).
Wait until backend, frontend and proxy are healthy (240 seconds at most).
On failure the tool shows the backend log and rolls back automatically.

Read the changelog before updating. An update usually takes only the services' restart; the web interface is briefly unavailable.

`rollback`

./opnexus rollback

Puts the installation back to the state before the last update: onto exactly the image tag that was set before.

If the update did not migrate the database, only the services are set back to the old version.
If it did, the backup taken before the update is restored. Only a backup created after this update started is used, and it is checked for readability first. A safety copy of the current state (pre-rollback-….dump) is written before; if restoring fails, the tool restores that copy.
Afterwards OPNEXUS_VERSION in .env is pinned to the old version. For the next attempt, name the target version again.

Important: log history and resource measurements are not part of the backups and are empty after a database rollback. Everything else – hosts, rules, users, audit history – is back to its state before the update. Only one step is rolled back (the last update).

`backup`

./opnexus backup

Writes a backup as manual-<time>.dump into the Docker volume postgres_backups. The data of the two large tables (firewall logs and resource measurements) is deliberately left out, otherwise the dump would be huge; all settings and the change history are included. A companion container also writes automatic backups into the same volume on a regular basis.

docker compose exec postgres-backup ls -l /backups

Configuration

Setting	Effect
`OPNEXUS_DIR`	Folder with `docker-compose.yml` and `.env`, if not the script's own.
`OPNEXUS_UPDATE_TIMEOUT`	Seconds to wait for “healthy” (default 240).
`OPNEXUS_NO_AUTO_ROLLBACK=1`	No automatic rollback after a failed update; the state stays for analysis, manually: `opnexus rollback`.
`.env`: `OPNEXUS_IMAGE_REPO`, `OPNEXUS_VERSION`	Registry and track of the installation.
`.env`: `POSTGRES_USER`, `POSTGRES_DB`, `POSTGRES_PASSWORD`	Database access for backup and rollback (default user and database: `opnexus`).

Safeguards

Pull first, then switch: a failed download changes nothing.
Automatic fallback: if the new version does not become healthy, it is rolled back.
Backup before the migration and a check before restoring: never overwritten with a too-old or broken backup.
Safety copy of the state before a database rollback.
Input checked: the version may only contain characters an image tag can have.
Password not in the process list: the database password reaches the tools through the environment, not as an argument.

Troubleshooting

The tool prints its messages in German. The most common ones:

Message	What to do
“OPNEXUS_IMAGE_REPO ist in .env nicht gesetzt”	The installation does not run from release images. Either switch to release images or update locally with `git pull && docker compose up -d --build`.
“Pull fehlgeschlagen — nichts wurde verändert”	Is the registry reachable? Does the version exist? Then simply try again.
“Backend läuft nicht oder antwortet nicht”	Repair first (`docker compose logs backend`), then update.
“Update nicht gesund geworden”	The backend log follows; the tool rolls back by itself. With `OPNEXUS_NO_AUTO_ROLLBACK=1` the state stays for analysis.
“Kein Update-Zustand … nichts zurückzurollen”	A rollback only works after an `opnexus update` (it needs the state file that update created).
“Datenbank wurde migriert, aber es gibt kein pre-upgrade-Backup”	The backup before the migration is missing (for example because of `SKIP_MIGRATION_BACKUP`). The backend stays stopped; intervene manually. Your own `opnexus backup` helps in future.

Limits

Only for installations from release images (amd64).
A rollback goes back one step – to the state before the last update.
After a database rollback, log history and measurements are empty.
The tool manages the OPNexus installation, not your firewalls; it changes nothing there.

More help

If the only admin is locked out without an authenticator and without recovery codes, this command switches off two-factor sign-in for one account on the server (it needs shell access to the server):

docker compose exec backend python -m app.reset_2fa USERNAME

The full guide is in the handbook (German) and the README (section “Release images & CI”).