Self-hosting overview
Run Iris on your own infrastructure with Docker Compose.
Iris is MIT-licensed and designed to run on standard infrastructure. A deployment consists of two application processes and three backing services.
Architecture
| Component | What it is | Default port |
|---|---|---|
| API | NestJS — REST API, WebSocket gateway, Bull job processor | 3000 |
| Web | Next.js — dashboard, test authoring UI, run viewer | 3001 |
| PostgreSQL | Primary datastore (users, projects, tests, runs) | 5432 |
| Redis | Bull job queue for test runs | 6379 |
| MinIO | S3-compatible storage for screenshots and frame artifacts | 9000/9001 |
The repository ships a docker-compose.yml that runs the three backing services:
pnpm docker:up # docker compose up -d
pnpm docker:down # stop and remove containersPostgreSQL runs postgres:17-alpine (user/password/db all default to iris), Redis runs redis:7-alpine with append-only persistence, and MinIO uses minioadmin/minioadmin root credentials with a console on port 9001. All three persist data in named Docker volumes.
The compose defaults (database password iris, MinIO minioadmin) are for
local development. Change them for any deployment reachable from a network,
and update DATABASE_URL and the MINIO_* variables to match.
Production checklist
- Set strong secrets —
BETTER_AUTH_SECRET(openssl rand -hex 32, identical in API and web), database password, MinIO credentials. - Configure URLs —
WEB_URLandBETTER_AUTH_URLon the API must point at the public web URL;NEXT_PUBLIC_API_URLon the web app must point at the public API URL. - Choose a browser environment — local Playwright needs browsers installed on the API host; Browserbase offloads browser execution to the cloud.
- Run migrations on deploy:
pnpm db:generate && pnpm db:migrate. - Expose MinIO —
MINIO_PUBLIC_URLmust be reachable by browsers loading run screenshots.
The full list of configuration options is in the environment variable reference.