Getting Started

Getting Started

Prerequisites

• Docker 24+ and Docker Compose v2
• 8 GB RAM minimum (16 GB recommended when running local LLM via LM Studio)
• Git

Clone and run

git clone https://github.com/zach115th/iris-ng.git
cd iris-ng

# Copy and edit the environment file
cp .env.model .env
# Edit .env — set POSTGRES_PASSWORD, SECRET_KEY, IRIS_ADM_PASSWORD at minimum

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

The stack comes up on https://localhost (nginx with a self-signed cert). Default admin credentials are whatever you set in .env.

Services

Container	Role
iriswebapp_app	Flask/gunicorn web + REST API
iriswebapp_worker	Celery default queue (hooks, modules)
iriswebapp_ai_worker	Celery ai_queue (AI jobs, concurrency=1)
iriswebapp_db	PostgreSQL 15
iriswebapp_nginx	TLS termination + reverse proxy
iriswebapp_rabbitmq	RabbitMQ broker
iriswebapp_claude_proxy	Claude HTTP sidecar (optional, port 7440)

AI backend configuration

IRIS-NG ships with an AI backend admin UI at /manage/settings → AI tab.

The default backend is LM Studio (always-on, runs locally). Configure the primary slot URL to http://host.docker.internal:1234/v1 and the model name to whatever you have loaded.

Optional: enable the Claude sidecar as the alt slot — see AI Features.

Migrating from vanilla DFIR-IRIS

IRIS-NG is purely additive over v2.5.0-beta.1 (new tables and columns only — no renames, no removals), but vanilla DFIR-IRIS cannot connect to an iris-ng database without the schema additions in place.

scripts/import_vanilla_db.sh handles the full migration in two phases — one command on the old host, one command on the new host.

Step 1 — Export from the old host

Run this from the root of your vanilla DFIR-IRIS checkout on the source server:

bash scripts/import_vanilla_db.sh export --out ./iris-export

--out is optional; if omitted the script auto-names the directory ./iris-export-YYYYMMDD-HHMMSS. The export creates a directory (not a single file) containing up to five files:

iris-export/
├── iris.dump              ← Postgres dump (required — migration aborts without this)
├── server_data.tar.gz     ← uploaded evidence files and datastore
├── user_templates.tar.gz  ← uploaded .docx report templates
├── iris-downloads.tar.gz  ← previously generated reports
└── secrets.env            ← IRIS_SECRET_KEY + IRIS_SECURITY_PASSWORD_SALT

Important: copy the entire directory (all files) to the new host. If you only copy iris.dump, the script will still run but user passwords and uploaded files will not carry over.

Step 2 — Import on the new host

Run this from the root of your iris-ng checkout on the destination server. The --from flag is required and must point to the directory you copied over:

bash scripts/import_vanilla_db.sh import --from /path/to/iris-export

For example, if you copied the bundle to /root/iris-ng/iris-export-20260629-184838:

bash scripts/import_vanilla_db.sh import --from /root/iris-ng/iris-export-20260629-184838

The script will print a migration plan and ask for confirmation before wiping the existing iris-ng database. It then:

1. Stops the app, worker, and ai_worker containers (leaves db running)
2. Drops and recreates iris_db, restores the Postgres dump
3. Runs a pre-Alembic schema sanity check
4. Restores the named volumes (evidence, templates, generated reports)
5. Carries IRIS_SECRET_KEY + IRIS_SECURITY_PASSWORD_SALT into iris-ng's .env
6. Reconciles any columns that vanilla's broken alembic/env.py left uncommitted
7. Brings the app back up — Alembic adds iris-ng's new tables on startup
8. Runs a post-Alembic check confirming all iris-ng tables exist

Additional flags

Flag	What it does
--out <dir>	(export) write bundle to this directory (default: auto-named)
--from <dir>	(import) required — path to the exported bundle directory
--skip-volumes	(import) do not restore evidence/template volumes
--skip-secrets	(import) do not carry over IRIS_SECRET_KEY / IRIS_SECURITY_PASSWORD_SALT
-f / --force	skip the confirmation prompt

After import

• Login with your existing credentials at https://localhost/login
• If secrets were not carried over, find the generated admin password with: docker compose logs app | grep "Administrator password"
• Reconfigure MISP sync under /manage/modules — the old upstream iris_misp_module config does not carry over (iris-ng uses a different module, iris_misp_sync_module)

The script supports vanilla DFIR-IRIS v2.4.x and v2.5.0-beta.1.

Upgrading iris-ng

Always use --build --force-recreate together:

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

Do not omit --force-recreate. A plain up --build can leave worker and ai_worker on the old container while only app is rebuilt, causing ORM mapper state mismatches that crash hook tasks with a NotImplementedError deep in task_hook_wrapper before any module's hooks_handler runs.

First login

1. Navigate to https://localhost/login
2. Sign in with the admin credentials from .env
3. Go to /manage/modules → enable IrisMISPSync if you have a MISP instance
4. Go to /manage/settings → AI tab → enter your LM Studio (or cloud) backend URL

Ports

Port	Service
443	IRIS-NG web UI and API (nginx, TLS)
7440	Claude proxy sidecar (internal Docker network only)

TLS

The default compose stack uses a self-signed certificate generated at container start. For production, mount your own cert/key into the nginx container by editing the docker-compose.dev.yml nginx volume mounts.