Skip to content

Getting Started

Jump to bottom
zach115th edited this page Jun 29, 2026 · 10 revisions

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:

  1. Exports a Postgres dump from the old host
  2. Copies named volumes (uploaded evidence, report templates)
  3. Carries over secrets
  4. Restores on the new host and runs a post-restore schema sanity check
# On the source host (vanilla DFIR-IRIS):
bash scripts/import_vanilla_db.sh export

# On the destination host (iris-ng):
bash scripts/import_vanilla_db.sh import <path-to-export-bundle>

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.

patreon.com/zach115th
buymeacoffee.com/zach115th

Clone this wiki locally