# Installation

> Every way to run Contextator — Docker Compose, plain docker run, building the image yourself, or from source — plus the first account and a reverse proxy.

- Updated: 2026-11-04
- Source: https://contextator.com/en/docs/installation/
- Language: en-US
- Author: Muhammet Şafak

---
Contextator ships as **one Docker image** containing PostgreSQL 16 with pgvector and the Node.js
application. There is no separate database to install and no migration step: the schema is created and
kept up to date on every start.

- [Requirements](#requirements)
- [Docker Compose with the published image (recommended)](#docker-compose-with-the-published-image-recommended)
- [Plain `docker run`](#plain-docker-run)
- [Build the image yourself](#build-the-image-yourself)
- [The first account](#the-first-account)
- [Behind a reverse proxy](#behind-a-reverse-proxy)
- [From source, without Docker](#from-source-without-docker)
- [Upgrading](#upgrading)
- [Command line](#command-line)
- [Uninstalling](#uninstalling)

---

## Requirements

| | |
|---|---|
| Docker | Any recent version with Compose v2 (`docker compose`, not `docker-compose`) |
| Disk | ~1.2 GB for the image (~860 MB for the `-slim` one), ~470 MB for the default embedding model (~120 MB with `EMBEDDING_DTYPE=q8`), plus your documents and their vectors |
| RAM | 2 GB is comfortable; embedding is CPU-bound, not memory-hungry |
| CPU | Any x86-64 or ARM64 CPU. No GPU is needed or used. The published image is built for `linux/amd64` and `linux/arm64`, so it runs on Apple Silicon without emulation |
| Network | Only for the one-time model download and for remote sources (git, Notion, Confluence, web, S3, Google Drive, GitHub). Air-gapped installs are possible — see [Embedding Models](/en/docs/embedding-models/) |

Runs on Linux, macOS and Docker Desktop for Windows (WSL 2 backend).

---

## Docker Compose with the published image (recommended)

No clone needed — just the compose file and the annotated environment template:

```bash
mkdir contextator && cd contextator
curl -fsSLO https://raw.githubusercontent.com/Contextator/Contextator/main/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/Contextator/Contextator/main/.env.example
cp .env.example .env
```

Edit `.env` — at minimum, point it at your documentation:

```bash
DOCS_HOST_PATH=/path/to/your/docs     # mounted read-only at /docs in the container
PORT=3444                             # host port
SETUP_CODE=                           # optional: pick the first-run code yourself
```

Then:

```bash
docker compose up -d
docker compose logs -f                # wait for "embedding model ready"
```

Open **http://localhost:3444/** and create the first account — see
[The first account](#the-first-account).

### What the compose file does

- Pulls and runs one container named `contextator`, publishing `${CONTEXTATOR_BIND:-127.0.0.1}:${PORT}:3444`. The published image is
  `contextator/contextator`.
- Creates three volumes that survive `docker compose down`, upgrades and container removal:
  `contextator-pgdata` (the database), `contextator-models` (downloaded models) and
  `contextator-data` (uploaded files, git checkouts, and Notion, Confluence, documentation-site, S3, Google Drive and GitHub pulls).
- Mounts `DOCS_HOST_PATH` read-only at `/docs`.
- Restarts the container unless you stopped it (`restart: unless-stopped`).

If `DATABASE_URL` is set the embedded PostgreSQL is not started and the container uses that database instead — it is also how the `-slim` image, which ships without PostgreSQL, is run.

Inside the container, PostgreSQL listens only on `127.0.0.1` and is not published — see
[Backup and Data](/en/docs/backup-and-data/) for how to reach it when you need to.

---

## Plain `docker run`

Without Compose, mount the same four paths yourself:

```bash
docker run -d --name contextator -p 127.0.0.1:3444:3444 \
  -e SETUP_CODE=whatever-you-like \
  -v contextator-pgdata:/var/lib/postgresql/data \
  -v contextator-models:/app/.cache/models \
  -v contextator-data:/data \
  -v /path/to/your/docs:/docs:ro \
  contextator/contextator
```

Add any other settings with `-e` — see [Configuration](/en/docs/configuration/).

`127.0.0.1` publishes the port on this machine only, the same default Compose uses. To reach the
instance from other machines, put the address of the interface to listen on in its place
(`-p 192.168.1.20:3444:3444`, or `0.0.0.0` for every interface) — and keep each project's MCP access on
**token required** or **account required**, which is how a new project starts. With Compose, the same
switch is `CONTEXTATOR_BIND` in `.env`.

To run Contextator on a Kubernetes cluster instead, use the Helm chart; see [Running on Kubernetes](/en/docs/kubernetes/).

---

## Build the image yourself

The compose file above pulls `contextator/contextator`. To build it from source instead — to try a
change to the `Dockerfile`, or on an architecture the published image does not cover — clone the
repository and layer the build override on top:

```bash
git clone https://github.com/Contextator/Contextator.git contextator && cd contextator
cp .env.example .env
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
```

`docker-compose.build.yml` builds the image from the checked-out source and tags it
`contextator/contextator:source` — deliberately not `latest`. Compose's default `pull_policy` is
`missing`, so a shared tag would make the two workflows clobber each other silently: build once, and a
later plain `docker compose up -d` would keep running your old local build under the published name
instead of pulling the real one. Everything else — volumes, environment, ports — is exactly what
`docker-compose.yml` defines.

---

## The first account

The dashboard requires an account, and a fresh installation has none. Until the first one exists, every
start prints a one-time **setup code** on stdout:

```
┌─ Contextator first-run setup ───────────────────────────────────────────┐
│ No user accounts exist yet; the dashboard is waiting for its first one. │
│                                                                         │
│   Open   http://localhost:3444/setup                                    │
│   Code   KRTW-9MHD-2PQF                                                 │
│                                                                         │
│ A new code is printed on every start until that first account exists.   │
└─────────────────────────────────────────────────────────────────────────┘
```

`docker compose logs -f` shows it. Open `/setup` — `/` redirects there by itself — and give the code, a
username and a password of at least 12 characters. That account is `root`, and creating it closes setup
for good; there is nothing left to rotate.

Set `SETUP_CODE` in `.env` to choose the code instead, the same way you would choose
`POSTGRES_PASSWORD`. A code you chose is not echoed into the log. If a generated one is lost, restart
the server and read the new one.

Everything after that — more accounts, roles, per-project members — is on
[Accounts and Permissions](/en/docs/accounts-and-permissions/).

> **Serving the dashboard over plain HTTP** on a LAN address? Set `AUTH_COOKIE_SECURE=0`, or browsers
> drop the session cookie and sign-in loops back to `/login`.

---

## Behind a reverse proxy

A new project's MCP endpoint is **token required** by default, but any project can be switched to
**open** or to **account required** on its own page ([Security](/en/docs/security/)). If the server is
reachable by anyone you do not trust, check no project that should be private was switched to open, and
put the proxy's own authentication in front of any project you deliberately leave open.

Three things to get right:

1. **Do not buffer responses.** The legacy SSE transport is a long-lived stream.
2. **Tell the dashboard its public URL** so the snippets it prints are correct.
3. **Pin the cookie flag.** The proxy terminates TLS, so the application only learns the scheme from
   `X-Forwarded-Proto`. Say it outright instead:

```bash
PUBLIC_BASE_URL=https://docs.example.com
AUTH_COOKIE_SECURE=1
```

An nginx location that works:

```nginx
location / {
    proxy_pass http://127.0.0.1:3444;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_read_timeout 1h;
}
```

If browsers on another origin must reach `/mcp/*`, list that origin in `ALLOWED_ORIGINS`. Command-line
clients send no `Origin` header and are always allowed.

---

## From source, without Docker

Useful for development or when you already run PostgreSQL.

```bash
docker compose -f docker-compose.dev.yml up -d   # PostgreSQL 16 + pgvector on localhost:5432
cp .env.example .env
```

In `.env`:

```bash
DATABASE_URL=postgres://contextator:contextator@localhost:5432/contextator
ALLOWED_DOC_ROOTS=/home/me/docs          # or C:/Users/me/docs on Windows
DATA_DIR=.data                           # git checkouts, uploads, Notion/Confluence/site pulls
SECRET_KEY=                              # only needed for private repositories / Notion / Confluence
```

Then:

```bash
npm install
npm run dev        # tsx watch → http://localhost:3444
npm test           # unit tests
npm run typecheck
```

Requires Node.js 24 or newer since 1.0.0 — the floor in `package.json`'s `engines`, and the version the container
ships — and a PostgreSQL 16 with the `vector` extension.

---

## Upgrading

```bash
docker compose pull
docker compose up -d
```

Building from source instead: `git pull`, then
`docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build`.

The schema is brought up to date automatically at startup. Your data is in volumes and is untouched by
an upgrade. Three upgrades need a decision from you: a change of embedding dimensions — see
[Embedding Models](/en/docs/embedding-models/); coming from a release before 0.2.0, a check of
`DATABASE_URL`, below; and, coming from 0.4.x with `TRUST_PROXY=1` or `true` in your environment, naming
the proxy instead, because 0.5.0 refuses those values at startup — see
[Running behind a reverse proxy](/en/docs/configuration/#running-behind-a-reverse-proxy).

**Coming from before 0.2.0: check `DATABASE_URL` in `.env` first.** Older `.env.example` files shipped
`DATABASE_URL=postgres://contextator:contextator@localhost:5432/contextator` for running from source.
From 0.2.0 the container reads that line: it does not start its own PostgreSQL and tries to reach the
database at its own loopback, where nothing is listening. Clear `DATABASE_URL` in `.env` before
`docker compose up -d`, unless you are deliberately naming an external database. The startup log names
the database it chose and warns when a loopback address is set on an image that embeds PostgreSQL. Your
data is untouched either way. See [The container keeps restarting](/en/docs/troubleshooting/#the-container-keeps-restarting).

**Tags.** `latest` always points at the newest stable release; `1` follows the newest `1.x` release, for an installation that takes every update under the [compatibility policy](https://github.com/Contextator/Contextator/blob/main/docs/compatibility.md); `1.0` tracks the latest patch inside the
`1.0.x` line; `1.0.0` is one exact, immutable release. Pin a versioned tag for anything you upgrade
deliberately by setting `CONTEXTATOR_TAG` in `.env` (e.g. `CONTEXTATOR_TAG=1.0.0`) — this is read at
every start, not only the first. Each of these also exists with a `-slim` suffix (`latest-slim`, `1-slim`, `1.0-slim`, `1.0.0-slim`): the same application without PostgreSQL, which needs `DATABASE_URL`. The `1` tag is published from 1.0.0 on; the 0.x releases have none.

**What 1.0.0 promises.** From 1.0.0 on, what a release may break is written down in one place, the [compatibility policy](https://github.com/Contextator/Contextator/blob/main/docs/compatibility.md): which surfaces are frozen, how a removal is announced, and that every `1.x` upgrades every earlier `1.x`. Coming from 0.7.x, read its "Moving from `0.7.x` to `1.0.0`" section and the 1.0.0 entries of the [changelog](https://github.com/Contextator/Contextator/blob/main/CHANGELOG.md) first.

---

## Command line

Since 0.6.0 both images, the default one and `-slim`, carry a `contextator` command. It is a small client of the
[admin API](/en/docs/admin-api/) for what you would otherwise write as a few `curl` calls and a polling loop in a CI job:
create a project from a git repository, add a source of any type, wait for its index, mint an MCP token. It is the version of the image you already run,
not a separate download.

```bash
docker run --rm \
  -e CONTEXTATOR_URL=https://docs.example.com -e CONTEXTATOR_TOKEN \
  contextator/contextator:1.0.0-slim \
  contextator project create handbook --git https://github.com/acme/handbook --wait
```

`contextator` as the first argument makes the container run that command and nothing else: no server, no database, no model
download. Any other start of the image is unchanged.

| Command | What it does |
|---------|--------------|
| `contextator project create <name> --git <url>` | Creates the project, adds a git source of the same name and queues its first index run; `--wait` follows the run, with a timeout |
| `contextator source add --project <name\|id> --type <type>` | Adds a source of any type to an existing project and queues an index run. The settings go in `--config-json` or `--config-file` (`-` reads standard input), not both; the server validates them. A credential is never an argument: `--secret-env <VAR>` names the variable that holds it |
| `contextator project status <name\|id>` | Where the project's index stands; with `--wait` it exits `5` if the run failed |
| `contextator token create --project <name\|id>` | Mints an MCP token; `--json` or `--show-secret` is required because the secret is shown once. `--source <name\|id>` (repeatable) binds it to some of the project's sources; `--expires-in-days` takes `30`, `90` or `365`, and `--allowed-cidr` (repeatable) names a network allowed to present it |
| `contextator backup` | The existing backup under this name; it needs the default image, not `-slim` |

Connect it with `CONTEXTATOR_URL` and `CONTEXTATOR_TOKEN`, an account's [API token](/en/docs/accounts-and-permissions/) or
`ADMIN_TOKEN`. The token is never an argument, because an argument shows in the process list and in shell history; use
`--token-file <path>` to read it from a file. Output is lines or `--json`, progress goes to stderr and the result to stdout, and
exit codes tell the cases apart (`0` success, `2` usage, `3` rejected credential, `4` not found or already exists, `5` the index
run failed, `6` timed out, `7` unreachable). The command warns when the server's version is not its own, so use the same image
tag for both. It is not published to npm.

---

## Uninstalling

```bash
docker compose down            # stops and removes the container — DATA IS KEPT
docker compose down -v         # also deletes the volumes — DATA IS GONE
```

Your original documentation is never modified: `/docs` is mounted read-only, and local directory
sources are scanned in place rather than copied.
