Upgrading to Version 2

Upgrading from 1.4.x to Version 2

This page walks a running 1.4.x install through the upgrade to IRIS-NG-v2.0.0. A fresh install doesn't need it — follow Getting Started as usual.

Three facts shape the whole procedure:

1. The upgrade is one-way. 24 schema migrations apply automatically on first boot (Alembic head f8b3c62d94a7). Once they have run, 1.4.x code refuses to start against the database. Your backup is the only road back.
2. An image rebuild is mandatory. Python and UI dependencies changed (gunicorn 26.2.0, marked 18.0.11, svelte 5.57.0, among others) and much of the interface ships as static assets baked into the image at build time. Containers recreated without --build serve the old code and the old UI.
3. Your data and integrations carry over. The full migration chain was rehearsed against a clone of a real 1.4.x production database: every migration applies in one boot and every pre-existing row survives. The API stays compatible with v2.5.0-beta.1 clients, all schema changes are additive, .env needs no new variables, and PostgreSQL stays on 17 — no database engine migration is involved.

The new v2 features (mail rules, clustering rules, investigation flows, war rooms) stay inert until you configure them, so the instance behaves familiarly right after the upgrade — plus a new /home landing page and the redesigned case tabs.

Step 1 — Back up the databases

Do this while 1.4.x is still running. It takes seconds and it is the only rollback.

docker exec iriswebapp_db pg_dump -U postgres -Fc iris_db   > iris_db_pre_v2.dump
docker exec iriswebapp_db pg_dump -U postgres -Fc iris_tasks > iris_tasks_pre_v2.dump

Check that both files are non-trivially sized before continuing — a zero-byte dump is not a backup:

ls -lh iris_db_pre_v2.dump iris_tasks_pre_v2.dump

Keep the files somewhere outside the repository directory.

Step 2 — Update the source tree

git fetch --all
git reset --hard origin/main

Use reset --hard, not git pull. main is published as a sanitized snapshot whose history can be replaced, so git pull may fail with fatal: Need to specify how to reconcile divergent branches. The reset form always works. It discards any local edits to tracked files — your .env, certificates and database live outside the tracked tree and are untouched.

If you prefer to pin the release rather than track main:

git fetch --all --tags
git checkout IRIS-NG-v2.0.0

Step 3 — Rebuild and restart

docker compose -f docker-compose.dev.yml up -d --build --force-recreate

Both flags are load-bearing:

• --build — see fact 2 above. Without it the containers boot v2 Python against 1.4.x dependencies and serve 1.4.x static assets.
• --force-recreate — a plain up --build can leave worker and ai_worker on the old container while only app is recreated, and the resulting code skew crashes hook tasks with a NotImplementedError deep in task_hook_wrapper.

Migrations run themselves during the first boot; with the rehearsed dataset the whole chain applied within a normal boot cycle. You can watch them go by:

docker logs -f iriswebapp_app

Step 4 — Verify

1. Log in. You should land on the new /home page.

2. Settings → System should report IRIS-NG-v2.0.0.

3. The database should be at the v2 schema head:

   docker exec iriswebapp_db psql -U postgres -d iris_db -t \
     -c "SELECT version_num FROM alembic_version;"

   Expected: f8b3c62d94a7.

4. Open an existing case and confirm your notes, timeline, IOCs and assets are all present.

Then take a look around: the sidebar gained Operations (Alerts, Alert Clusters) and Intel (Correlation) sections, the case tabs have master/detail views (the previous tables remain available behind a "Show legacy table" toggle on each), and the settings pages are consolidated into one Manage IRIS rail.

Rolling back

There is exactly one path back, and it requires the Step 1 dumps. Restoring discards everything done in v2 after the upgrade.

# stop everything that talks to the database
docker compose -f docker-compose.dev.yml stop app worker ai_worker

# restore both databases from the pre-upgrade dumps
docker exec -i iriswebapp_db pg_restore -U postgres --clean --create -d postgres < iris_db_pre_v2.dump
docker exec -i iriswebapp_db pg_restore -U postgres --clean --create -d postgres < iris_tasks_pre_v2.dump

# return the tree to the last 1.4.x release and rebuild
git fetch --all --tags
git checkout IRIS-NG-v1.4.1
docker compose -f docker-compose.dev.yml up -d --build --force-recreate

Without the dumps there is no rollback: 1.4.x code aborts at boot against a migrated database with Can't locate revision <hex> — that error means the database has v2 migrations applied and the running code has never heard of them.

If you were on the dev-branch preview

You are already on the v2 schema — the released main supersedes the preview branch. Just move over and rebuild (the rebuild matters: the release carries dependency bumps the preview may predate):

git fetch --all
git checkout -B main origin/main
docker compose -f docker-compose.dev.yml up -d --build --force-recreate

No new migrations apply beyond what the preview already ran, and a backup taken before the original jump to the preview remains your 1.4.x rollback point.

Kubernetes / Helm

Chart 1.0.0 (appVersion IRIS-NG-v2.0.0) is attached to the release and derives its image tags from appVersion, so helm upgrade with the new chart deploys the v2 images. The same rules apply: take a pg_dump inside the postgres pod first, and expect the migration to be one-way. Note the chart upgrade path from 0.8.1 has not been rehearsed the way the Compose path has — treat it with proportionate care, and see Kubernetes for the chart's general caveats (single-node verified, Postgres is a Deployment rather than a StatefulSet).

If something goes wrong

Symptom	Cause	Fix
fatal: Need to specify how to reconcile divergent branches on git pull	main is a snapshot; histories diverged	git fetch --all && git reset --hard origin/main
Boot fails with Can't locate revision <hex>	1.4.x code against a migrated (v2) database	Complete the upgrade, or restore the Step 1 dumps to roll back
UI looks like 1.4.x, or new pages 404, after the upgrade	Containers recreated without --build — stale image	Re-run Step 3 with both flags
Hook tasks crash with NotImplementedError in task_hook_wrapper	worker/ai_worker left on the old container	Re-run Step 3 with --force-recreate
Cannot log in after restoring a backup	Wrong IRIS_SECRET_KEY/IRIS_SECURITY_PASSWORD_SALT in .env	Restore the matching .env alongside the database

More symptom-first entries in Troubleshooting.