OpsNexus
DocsGetting started

Upgrading

Back up, pull the new version, rebuild the containers, let migrations run, then upgrade your build agents.

On this page

OpsNexus is upgraded from source: you pull the new version of the repository and rebuild the images. Database migrations run automatically when the API starts. After the server is upgraded, you upgrade your build agents from the app.

Before you start

  1. Read the Changelog for the versions between yours and the new one. Look for new settings and changed behaviour.
  2. Plan a short maintenance window. The web app and API are unavailable while the containers restart and migrations run.
  3. Make sure you have enough disk space for new images and a backup.

1. Back up

Always take a backup you can restore outside the app before an upgrade.

With the bundled database and Vault, from the repository root (Git Bash on Windows):

bash
./scripts/backup.sh

This writes a database dump and a Vault archive to backups/. With an external PostgreSQL or Vault, take a snapshot with their own tools.

You can also create a backup in Settings → Backup & restore. Keep in mind that an in-app restore only accepts a backup made with the same database schema version, so it cannot undo a schema change made by the upgrade. Use the database dump for that. See Backup and restore.

2. Get the new version

bash
cd OpsNexus
git fetch
git pull

If you deploy a specific tag or branch, check it out instead of pulling.

3. Check for new settings

New versions can add settings to .env.example. Compare it with your .env:

bash
git diff ORIG_HEAD HEAD -- .env.example

Add any new settings you need to .env. Settings you leave out use their built-in defaults. See Environment variables.

4. Rebuild and restart

bash
docker compose up -d --build

This rebuilds the api, worker, scheduler and web images and recreates the containers. To also pick up security fixes in the base images and the PostgreSQL, Redis, Vault and guacd images, use:

bash
docker compose pull
docker compose build --pull
docker compose up -d

5. Watch the migrations

When the api container starts, it:

  1. runs database migrations (alembic upgrade head);
  2. runs first-run setup, which does nothing on an existing installation;
  3. starts the web server.

The worker, scheduler and web containers wait until the API is healthy. Follow the API log:

bash
docker compose logs -f api

You should see Running database migrations..., then the server starting. If a migration fails, the API does not start. Fix the cause shown in the log, then start it again with docker compose up -d.

To run migrations by hand in the running stack:

bash
docker compose exec api alembic upgrade head

To see which migration the database is at:

bash
docker compose exec api alembic current

If you use make, make migrate runs the same alembic upgrade head command.

6. Check that everything works

  1. Run docker compose ps. All services except vault-init should be running or healthy.
  2. Sign in and open Settings → System status. The database, cache and queue, secret store and background workers should all be OK.
  3. Open CI/CD → Builds and Build agents and check that agents report and builds run.

Upgrade build agents

The agent program ships inside the OpsNexus server image. After a server upgrade, agents can download the new version from your server.

Agents installed as a service

To upgrade one agent:

  1. Open Build agents and select the agent.
  2. Select Upgrade.

The agent picks up the command on its next heartbeat. If it is running pipeline jobs, it waits until they finish. It then downloads the new onx_agent.py from OpsNexus, replaces its own file and exits, and the service manager (systemd, launchd or the Windows scheduled task) starts it again. The agent's version is shown on its card.

You can also re-run the installer from Build agents → Download & install.

Agents in Docker

The Upgrade button replaces the program inside the running container, but the change is lost when the container is recreated. Rebuild the image instead.

For the bundled runner service:

bash
docker compose --profile runner up -d --build runner

For agents you started with the Docker command from Download & install, rebuild the image and recreate the container, as the command shows.

Tip

Upgrade one agent first and run a pipeline on it before you upgrade the rest.

Roll back

If an upgrade fails and you need the previous version:

  1. Check out the version you ran before, for example git checkout <previous tag or commit>.

  2. Rebuild the images: docker compose build.

  3. Restore the database dump you took before the upgrade:

    bash
    ./scripts/restore.sh backups/opsnexus-<timestamp>.sql.gz

  4. Start the stack: docker compose up -d.

Warning

Restoring the dump replaces all data with the state at backup time. Changes made after the backup are lost.

Change the server address

If OpsNexus moves to a new address during an upgrade, update PUBLIC_URL (and AGENT_URL if you use it). Agents keep the address they registered with. On each installed agent machine, run this as the account that owns the agent config, then restart the agent:

bash
python onx_agent.py set-url https://opsnexus.example.com

Docker agents use the ONX_URL environment variable, which always wins over the saved address. See Build agents.