---
title: "Installation"
description: "A single Docker image serves the API, MCP, and web interface on port 3000; a single /data volume holds all state."
---

# Installation

Notarium ships as **a single self-contained image**: one Node process serves the REST API, the MCP endpoint for agents, and the compiled web interface on a single port (`3000` by default). No external services — no database, no message broker, no separate search engine — are required: the knowledge engine runs inside that same process. All state lives in a single `/data` volume: the metadata database, derived indexes, your Markdown files (the source of truth), and export artifacts.

> [!note] What you'll need
> Just **Docker** (or Docker Desktop) and a free port. There's no need to install Node, a database, or a vector index separately — it's all inside the image.

## Run the image

The fastest path is to spin up a container from the prebuilt image:

```bash
docker run -d --name notarium \
  -p 3000:3000 \
  -v notarium-data:/data \
  docouno/notarium:latest
```

A single `/data` volume holds all state: the metadata database, indexes, your notes, and export artifacts. There's nothing else to set — port `3000` and the data path `/data` are already baked into the image. The volume survives recreating the container; the port to the left of `:3000` can be changed to any free one.

You don't need to append a command to `docker run`: the image's entry point is the built-in `notarium` CLI, and by default it runs `start`. The same CLI carries the operator commands — `backup`, `restore`, `admin`, `healthcheck`, `version`. See [Image CLI](/docs/self-hosting/cli/).

## Using Docker Compose

For an instance you intend to keep, a compose file is easier to edit and to keep under version control, and `restart` brings the container back after a host reboot.

```yaml
services:
  notarium:
    image: docouno/notarium:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - notarium-data:/data

volumes:
  notarium-data:
```

Save it as `compose.yaml` and bring it up with `docker compose up -d`. The named volume `notarium-data` lives independently of the container: `docker compose down` leaves it in place, and only an explicit `docker volume rm` deletes it.

> [!note] Settings go here too
> Environment variables go in the service's `environment:` block. If you'd rather keep them in a separate file, add an `env_file: .env` line there as well — an `.env` file sitting next to the compose file does **not** reach the container on its own: Docker Compose only substitutes it into the text of the compose file itself. The full list — [Environment variables](/docs/reference/environment-variables/).

## First run

Open `http://localhost:3000` and you'll be greeted by the **first-run setup screen**. By default the instance runs in `password` mode, and the first visitor creates the **owner** — the single account with administrator rights and ownership of the spaces it creates. There's no preset password; once the owner registers, setup closes for good. For more on the modes, see [Authentication](/docs/self-hosting/authentication/).

## Data volumes

| Volume | What it holds | Nature |
|---|---|---|
| `/data` | Your Markdown files (`/data/spaces`, one folder per space), the metadata database (`/data/meta.db` — identifiers, version history, users, access), the engine's derived indexes (`/data/engine`), and export artifacts. | Files are the source of truth (the file-first principle); the metadata database can't be derived from files; indexes are derived and are restored by a rebuild. |

Guard the volume itself: lose it and your data goes with it. If the indexes in `/data/engine` are lost, they rebuild from the files, but the metadata database (`/data/meta.db` — history, users, access) and the notes themselves (`/data/spaces`) can't be restored from anywhere — backing them up is mandatory. For how to take a verified backup without stopping the service, see [Backup and restore](/docs/self-hosting/backup/).

## Building from source

If you're working with the Notarium repository, the single entry point for Docker is `make`:

```bash
cp .env.example .env   # defaults work — nothing to fill in
make up                # prod image locally → http://localhost:3000
make dev               # dev stack with hot-reload (HMR)
```

Handy commands: `make logs` (logs), `make ps` (status), `make down` (stop and remove), `make sh` (shell in the container).

## Registry-free install (air-gapped)

To deploy into an isolated environment, the image can be moved as a file, without access to a registry:

```bash
make image                              # build the image
make save                               # export to notarium-<version>.tar.gz
# move the archive to the target host, then:
docker load < notarium-<version>.tar.gz # load the image
```

Then run it with your own `compose`/`.env` — the registry coordinate isn't baked into the image.

The next step is to tailor the instance to your needs: see [Configuration](/docs/self-hosting/configuration/).