> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/deployment-and-infrastructure/docker.md).

# Docker

## Quick Start

### Without Authentication (default)

```bash
docker compose up
```

This starts EDDI on port `7070` and MongoDB, both published on `127.0.0.1` only. No login required: `docker-compose.yml` sets the three authentication opt-outs described below, which is why it does not publish EDDI on other interfaces unless you set `EDDI_BIND` — and refuses to do even that while authentication is off, see [Publishing EDDI on the network](#publishing-eddi-on-the-network).

Loopback keeps the network out, not a web page in your own browser. So while authentication is off EDDI answers only requests addressed to `localhost`, an IP address or a host in `EDDI_SECURITY_UNAUTHENTICATED_ALLOWED_HOSTS` (default `eddi`, the service name other containers use) — anything else gets `421` — and refuses cross-site `POST`/`PUT`/`PATCH`/`DELETE` from origins not in `QUARKUS_HTTP_CORS_ORIGINS` with `403`. Browsing to `http://localhost:7070` works as before; if you reach EDDI under another name, add it to the list. See [Running without authentication](https://docs.labs.ai/security-and-compliance/security.md#running-without-authentication).

The stack also publishes `7443` (`EDDI_HTTPS_PORT`), Quarkus' HTTPS port. Nothing listens there until you configure a TLS certificate ([TLS Directly in Quarkus](https://docs.labs.ai/security-and-compliance/security.md#option-2-tls-directly-in-quarkus)); until then a connection to it is refused.

### Publishing EDDI on the network

`EDDI_BIND` is the host interface EDDI is published on (`127.0.0.1` by default, so a laptop install is never reachable from the LAN by accident). Setting it to `0.0.0.0` or a LAN address is allowed only once authentication is on: every whole stack that publishes on `EDDI_BIND` — `docker-compose.yml`, `docker-compose.postgres-only.yml` and `docker-compose.cluster.yml` — carries the same one-shot `bind-guard` service that the published service depends on, and it exits 1 — so EDDI never starts — when `EDDI_BIND` is not a loopback address while `EDDI_SECURITY_ALLOW_UNAUTHENTICATED` is still `true`. The message it prints names the way out:

```bash
# in .env — then bring the Keycloak overlay up
EDDI_BIND=0.0.0.0
EDDI_SECURITY_ALLOW_UNAUTHENTICATED=false
QUARKUS_OIDC_TENANT_ENABLED=true
docker compose -f docker-compose.yml -f docker-compose.auth.yml up
```

The guard runs on a database image the stack pulls anyway (`mongo`, or `postgres` in the PostgreSQL stack), so it costs no extra image, works offline and works with `docker-compose.local.yml`. It checks the two variables as compose resolves them, so a value set in `.env`, in the shell or by an overlay all count. `install.sh` performs the same check before it pulls images. `docker-compose.auth.yml` tells the guard that authentication is on, so it layers onto either base stack.

`ComposeStackTest` keeps the copies identical and renders every combination the installers assemble and the documentation prints with `docker compose config` (where Docker is installed; otherwise it checks that every service an overlay overrides exists in each base it is layered on):

| Base stack                         | Overlays that layer on it                                                                                                                                                                                                                                                |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `docker-compose.yml`               | `docker-compose.auth.yml`, `docker-compose.monitoring.yml` (alone or together), `docker-compose.local.yml`, `docker-compose.nats.yml`, `docker-compose.ollama.yml` (+ `docker-compose.ollama-nvidia.yml`), `docker-compose.chroma.yml`, `docker-compose.mcp-sidecar.yml` |
| `docker-compose.postgres-only.yml` | `docker-compose.auth.yml`, `docker-compose.monitoring.yml` (alone or together), `docker-compose.local.yml`                                                                                                                                                               |
| `docker-compose.cluster.yml`       | none — a whole stack on its own                                                                                                                                                                                                                                          |
| `docker-compose.openwebui.yml`     | none — a whole stack on its own                                                                                                                                                                                                                                          |

To expose an **unauthenticated** instance on purpose — an isolated network only you can reach — set `EDDI_I_UNDERSTAND_PUBLIC=true` as well; the GCP provisioner's `--i-understand-public` does exactly that. Every API endpoint, the secrets vault and the MCP server are then open to whoever can reach the port, and EDDI's own `AuthStartupGuard` says so in its log at startup.

### With Keycloak Authentication

This repository ships a Keycloak overlay. Layer it on the base stack:

```bash
docker compose -f docker-compose.yml -f docker-compose.auth.yml up
```

This starts:

* **Keycloak 26** on `127.0.0.1:8180` (admin console: `http://localhost:8180/admin`, login `admin` / `KC_BOOTSTRAP_ADMIN_PASSWORD` — `admin` unless you set it; the installers generate one into `.env`)
* **`keycloak-guard`**, a one-shot check Keycloak waits for: it exits 1, so Keycloak never starts, when `KEYCLOAK_BIND` is not a loopback address while `KC_BOOTSTRAP_ADMIN_PASSWORD` is unset or `admin`. The loopback quick start needs no `.env`; to publish Keycloak on another interface, set `KC_BOOTSTRAP_ADMIN_PASSWORD` first (the installers and the GCP provisioner already do). Keycloak reads that password only when it first creates the master realm, so on an existing `keycloak-data` volume put the console's current admin password there
* **`keycloak-admin-rotate`**, a one-shot step EDDI waits for: once Keycloak is healthy it tries the `admin` login, and if an existing volume still accepts it, sets the account to the configured `KC_BOOTSTRAP_ADMIN_PASSWORD` (the password goes to `kcadm` on stdin). The guard alone cannot see a stored password, so this is what makes a new `.env` value take effect on an old volume. If `KC_BOOTSTRAP_ADMIN_USERNAME` names another user, the original `admin` account is checked and rotated the same way. Once a login with the configured credentials succeeds it leaves a marker in the volume, and `keycloak-guard` serves an existing volume off loopback only after that marker exists: start an old volume once on loopback. With a non-default `KC_BOOTSTRAP_ADMIN_PASSWORD` (a password of `admin` skips the check and the step succeeds), if that login fails (the admin password was changed in the console so `.env` no longer matches, or `KC_BOOTSTRAP_ADMIN_USERNAME` was renamed on an existing volume), the step exits 1 and EDDI does not start, on loopback too: put the console's password back in `.env`, restore the user name, or reset the `keycloak-data` volume.
* **EDDI** on port `7070` with OIDC auth enabled
* **MongoDB** for data storage

The realm seeds three accounts, **none of them with a password**:

| Username | Role                                       |
| -------- | ------------------------------------------ |
| `eddi`   | `eddi-admin`, `eddi-editor`, `eddi-viewer` |
| `viewer` | `eddi-viewer` (read-only)                  |
| `user`   | `eddi-user`                                |

Set a password for the one you need in the admin console (Users → *name* → Credentials → Set password). `install.sh --with-auth` does it for `eddi` and prints a one-time password; add `--demo-users` for the other two. They used to ship as `eddi`/`eddi`, `viewer`/`viewer` and `user`/`user`.

### Compose files and overlays

Run from a checkout of the repository (or a directory holding the compose files):

```bash
# Default (EDDI + MongoDB)
docker compose up

# PostgreSQL instead of MongoDB — a complete stack, so it is NOT layered on
# docker-compose.yml (an overlay cannot un-declare the base's mongodb service).
# The database password has no default. Generate it ONCE into .env, which
# compose reads on every run: PostgreSQL keeps the first password in its
# volume, so a new one on a later run is a password the database rejects
# (install.sh --db=postgres writes it into .env for you).
# .env holds secrets, so only you may read it: it is created under umask 077,
# an existing one is tightened, and nothing is written unless both succeeded.
# The leading \n keeps the entry on its own line when the file's last line has
# no newline.
(umask 077 && touch .env) && chmod 600 .env && {
  grep -q '^POSTGRES_PASSWORD=' .env || printf '\nPOSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 24)" >> .env
}
docker compose -f docker-compose.postgres-only.yml up

# With Keycloak authentication. No realm account ships a password (see the
# header of docker-compose.auth.yml, or let install.sh --with-auth set one)
docker compose -f docker-compose.yml -f docker-compose.auth.yml up

# With Prometheus + Grafana monitoring
docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up

# With a local LLM — Ollama on the same Docker network, reachable as
# http://ollama:11434 (no host.docker.internal needed)
docker compose -f docker-compose.yml -f docker-compose.ollama.yml up -d

# The same local LLM, on the host's NVIDIA GPUs — layered on the Ollama overlay
# above, never instead of it (all it adds is `gpus: all`)
docker compose -f docker-compose.yml -f docker-compose.ollama.yml \
  -f docker-compose.ollama-nvidia.yml up -d

# Auth + monitoring + NATS together (overlays stack in any combination)
docker compose -f docker-compose.yml -f docker-compose.auth.yml \
  -f docker-compose.monitoring.yml -f docker-compose.nats.yml up

# A cluster: three EDDI replicas behind a round-robin load balancer, a
# three-node NATS JetStream cluster and MongoDB — a whole stack, run on its own.
# Its three secrets are generated ONCE into .env, for the same reason as above:
# the MongoDB volume keeps its first password, and the vault's contents can only
# be decrypted with the master key they were encrypted under.
# -hex, not -base64: MONGO_PASSWORD goes into the MongoDB connection string as
# written, and base64's `/` and `+` change the meaning of a URI.
(umask 077 && touch .env) && chmod 600 .env &&
  for key in EDDI_VAULT_MASTER_KEY MONGO_PASSWORD NATS_PASSWORD; do
    grep -q "^${key}=" .env || printf '\n%s=%s\n' "$key" "$(openssl rand -hex 24)" >> .env
  done
docker compose -f docker-compose.cluster.yml up -d
```

Available compose overlays: `docker-compose.auth.yml` (Keycloak), `docker-compose.monitoring.yml` (Prometheus+Grafana), `docker-compose.nats.yml` (cluster mode with one replica and one NATS server), `docker-compose.ollama.yml` (local LLM; add `docker-compose.ollama-nvidia.yml` on top for NVIDIA GPU access), `docker-compose.chroma.yml` (vector store), `docker-compose.mcp-sidecar.yml` (reach a stdio-only MCP server through a bridge sidecar — read the [MCP Client](https://docs.labs.ai/protocols-and-integration/mcp-client.md#stdio-servers-via-a-bridge-sidecar) guide first), `docker-compose.local.yml` (build from source). `docker-compose.postgres-only.yml` is a complete standalone stack rather than an overlay — use it on its own, not with `-f docker-compose.yml`; so is `docker-compose.openwebui.yml`, a runnable [Open WebUI](https://docs.labs.ai/protocols-and-integration/open-webui-integration.md) demo of the OpenAI-compatible API, and `docker-compose.cluster.yml`, the multi-replica stack above (see [Clustering](https://docs.labs.ai/deployment-and-infrastructure/clustering.md)).

The Ollama overlay pulls `llama3.2:3b` on first start and keeps models in a named volume; override with `OLLAMA_PULL_MODEL=qwen3:4b`, or set it empty (`OLLAMA_PULL_MODEL=`) to skip the pull. It also sets `EDDI_OLLAMA_DEFAULT_BASE_URL`, so the agent wizard and the setup API pre-fill a base URL that resolves from inside the container — the one thing that trips up every first local-LLM agent, because `localhost` there is the container, not the host.

`docker-compose.ollama-nvidia.yml` adds GPU access to that Ollama and needs two things of the host, neither of which it degrades gracefully without: **Docker Compose 2.30.0 or newer**, which is where the `gpus` service attribute was introduced — older versions fail on it, so check `docker compose version` — and the **NVIDIA Container Toolkit** configured as a Docker runtime. `gpus: all` is a device *request*: with no GPU driver registered, the daemon cannot satisfy it and the container fails to start (`could not select device driver "" with capabilities: [[gpu]]`) rather than quietly falling back to the CPU. If you want Ollama on the CPU, leave this overlay off.

### Manual Docker Setup

Create a network and start MongoDB on it (the same `mongo:7.0.43` image `docker-compose.yml` pins). EDDI's default connection string points at a host named `mongodb`, so the container name matters:

```bash
docker network create eddi
docker run --name mongodb --network eddi -d mongo:7.0.43
```

Start EDDI (without auth) — **local development only:**

> ⚠️ These three opt-outs disable authentication on *every* endpoint, including `/secretstore` (the vault) and `/mcp` (agent CRUD). The port is bound to `127.0.0.1` below so the container is not reachable from the network. Do not publish it on `0.0.0.0`, and do not use this form on a shared or cloud host. For anything beyond your own machine, use the authenticated example below.

```bash
docker run --name eddi \
  --network eddi \
  -p 127.0.0.1:7070:7070 \
  -e EDDI_SECURITY_ALLOW_UNAUTHENTICATED=true \
  -e EDDI_MCP_ALLOW_UNAUTHENTICATED=true \
  -e EDDI_SECRETSTORE_ALLOW_UNAUTHENTICATED=true \
  -d labsai/eddi:latest
```

> **Note:** The image runs in production mode, where `AuthStartupGuard` and `HighValueSurfaceGuard` refuse to boot while OIDC is off. Without these three opt-outs the container exits at startup. This is exactly what `docker-compose.yml` sets for you.

Start EDDI (with auth):

```bash
docker run --name eddi \
  --network eddi \
  -p 7070:7070 \
  -e EDDI_VAULT_MASTER_KEY="$EDDI_VAULT_MASTER_KEY" \
  -e QUARKUS_OIDC_TENANT_ENABLED=true \
  -e QUARKUS_OIDC_AUTH_SERVER_URL=http://your-keycloak:8080/realms/eddi \
  -e QUARKUS_OIDC_CLIENT_ID=eddi-backend \
  -d labsai/eddi:latest
```

## Environment Variables

### Authentication

| Variable                                      | Default                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                             |
| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `QUARKUS_OIDC_TENANT_ENABLED`                 | `false`                                 | Enable/disable Keycloak auth                                                                                                                                                                                                                                                                                                                                                                                            |
| `QUARKUS_OIDC_AUTH_SERVER_URL`                | `http://localhost:8180/realms/eddi`     | Keycloak realm URL                                                                                                                                                                                                                                                                                                                                                                                                      |
| `QUARKUS_OIDC_CLIENT_ID`                      | `eddi-backend`                          | OIDC client ID                                                                                                                                                                                                                                                                                                                                                                                                          |
| `QUARKUS_HTTP_CORS_ORIGINS`                   | `http://localhost:3000,...`             | Allowed CORS origins                                                                                                                                                                                                                                                                                                                                                                                                    |
| `EDDI_SECURITY_ALLOW_UNAUTHENTICATED`         | `false`                                 | Opt out of the production auth requirement. Required to boot with OIDC disabled                                                                                                                                                                                                                                                                                                                                         |
| `EDDI_MCP_ALLOW_UNAUTHENTICATED`              | `false`                                 | Knowingly expose `/mcp` without authentication. Required to boot with OIDC disabled                                                                                                                                                                                                                                                                                                                                     |
| `EDDI_SECRETSTORE_ALLOW_UNAUTHENTICATED`      | `false`                                 | Knowingly expose `/secretstore` without authentication. Required to boot with OIDC disabled                                                                                                                                                                                                                                                                                                                             |
| `EDDI_SECURITY_UNAUTHENTICATED_ALLOWED_HOSTS` | *(unset; `eddi` in the compose stacks)* | With authentication off, the host names besides `localhost`, `*.localhost`, IP addresses and `host.docker.internal` / `gateway.docker.internal` / `host.containers.internal` EDDI answers to (`host` or `host:port`, comma-separated). Other hosts get `421` — the DNS-rebinding defence. See [Running without authentication](https://docs.labs.ai/security-and-compliance/security.md#running-without-authentication) |

> **Note:** `QUARKUS_OIDC_TENANT_ENABLED` is a **runtime** toggle. No rebuild needed to enable/disable auth.

### Storage and Secrets

| Variable                                                    | Default                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MONGODB_CONNECTIONSTRING`                                  | `mongodb://mongodb:27017/eddi?...` | MongoDB connection string                                                                                                                                                                                                                                                                                                                                                                                                         |
| `EDDI_DATASTORE_TYPE`                                       | `mongodb`                          | `mongodb` or `postgres`                                                                                                                                                                                                                                                                                                                                                                                                           |
| `EDDI_VAULT_MASTER_KEY`                                     | *(empty)*                          | Enables the [secrets vault](https://docs.labs.ai/security-and-compliance/secrets-vault.md). Without it EDDI starts, but the vault is disabled, and the audit ledger is unsigned unless the independent `EDDI_AUDIT_HMAC_KEY` (`eddi.audit.hmac-key`) is set. Production refuses a weak key (under 16 characters, fewer than 6 distinct characters, or a known default/placeholder) unless `EDDI_VAULT_ALLOW_WEAK_MASTER_KEY=true` |
| `POSTGRES_PASSWORD`                                         | *(required)*                       | `docker-compose.postgres-only.yml` only: the database password for both PostgreSQL and EDDI. No default — the file used to ship `eddi`/`eddi`. The postgres image reads it at first init only, so keep it stable; `install.sh --db=postgres` generates one into `.env`                                                                                                                                                            |
| `MONGO_INITDB_ROOT_USERNAME` / `MONGO_INITDB_ROOT_PASSWORD` | `eddi` / `changeme`                | MongoDB's root user, created on first init. Only `mongod` and the one-shot `mongodb-app-user` service see it; EDDI does not connect with it                                                                                                                                                                                                                                                                                       |
| `MONGO_APP_USERNAME`                                        | `eddi_app`                         | EDDI's own MongoDB user: `readWrite` + `dbAdmin` on `eddi`, nothing else. `mongodb-app-user` creates it, or resets its password, on every `up` — including on a volume from before it existed, so no manual migration is needed                                                                                                                                                                                                   |
| `MONGO_APP_PASSWORD`                                        | the root password                  | Password of that user. Set a distinct one (`openssl rand -hex 24`): left unset, EDDI's credential is still the root password under another name. URL-safe characters only — it is placed into the connection string unencoded. See [Upgrading from 6.5](https://docs.labs.ai/deployment-and-infrastructure/upgrading-from-6.5.md#mongodb-least-privilege-user)                                                                    |
| `MONGO_PASSWORD`                                            | *(required)*                       | `docker-compose.cluster.yml` only: the MongoDB root password, required like `NATS_PASSWORD` (it used to default to `changeme`). Read by the mongo image at first init only. The replicas connect as `MONGO_APP_USERNAME` / `MONGO_APP_PASSWORD` (falling back to this password), never as root                                                                                                                                    |
| `EDDI_BIND`                                                 | `127.0.0.1`                        | Host interface EDDI is published on. Anything but loopback is refused while `EDDI_SECURITY_ALLOW_UNAUTHENTICATED` is `true` — see [Publishing EDDI on the network](#publishing-eddi-on-the-network)                                                                                                                                                                                                                               |
| `EDDI_I_UNDERSTAND_PUBLIC`                                  | `false`                            | Acknowledges a deliberately unauthenticated, non-loopback `EDDI_BIND`; lifts the refusal above                                                                                                                                                                                                                                                                                                                                    |

Set configuration through environment variables like these rather than by overriding `JAVA_OPTS_APPEND`: the image sets `JAVA_OPTS_APPEND` itself, and a runtime value replaces it instead of adding to it.

### Update check

EDDI looks for a newer release once a day and puts a notification in the administrators' inbox (the bell in the Manager's top bar) when there is one. It is **on by default**: one anonymous request a day to `api.github.com/repos/labsai/EDDI/releases/latest`, the first a minute after boot, carrying nothing about your deployment.

| Variable                    | Default | Description                                                                                                                                                                                                                                                                                               |
| --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EDDI_UPDATE_CHECK_ENABLED` | `true`  | `false` switches the check off entirely — the first check after the first start included, because it is read before the database is touched. It wins over the Manager's switch, which then shows as locked. Compose passes it through from `.env`; the Helm chart sets it from `eddi.updateCheck.enabled` |

Administrators can also turn it off on the Manager's **Updates** page; that is stored in the database, so it survives restarts and applies to every node. A white-labelled deployment that has not set `eddi.branding.show-update-check` neither checks nor notifies. `eddi.update-check.interval` (default `24h`) changes the cadence.

### AI Tools

```bash
-e EDDI_TOOLS_WEBSEARCH_PROVIDER=brave \
-e EDDI_TOOLS_WEBSEARCH_BRAVE_API_KEY=your_key
```

(`google` still works with `EDDI_TOOLS_WEBSEARCH_GOOGLE_API_KEY` and `EDDI_TOOLS_WEBSEARCH_GOOGLE_CX` until Google shuts the Custom Search JSON API down on 2027-01-01; see [langchain.md → Web Search Tool](https://docs.labs.ai/agent-configuration/langchain.md#web-search-tool).)

```bash
-e EDDI_TOOLS_WEATHER_OPENWEATHERMAP_API_KEY=your_key
```

### Full Example

```bash
docker run --name eddi \
  --network eddi \
  -p 7070:7070 \
  -e EDDI_VAULT_MASTER_KEY="$EDDI_VAULT_MASTER_KEY" \
  -e QUARKUS_OIDC_TENANT_ENABLED=true \
  -e QUARKUS_OIDC_AUTH_SERVER_URL=http://keycloak:8080/realms/eddi \
  -e EDDI_TOOLS_WEBSEARCH_PROVIDER=brave \
  -e EDDI_TOOLS_WEBSEARCH_BRAVE_API_KEY=YOUR_KEY \
  -d labsai/eddi:latest
```
