---
title: "Instalação"
description: "Uma única imagem Docker serve a API, o MCP e a interface web na porta 3000; um único volume /data guarda todo o estado."
---

# Instalação

O Notarium é distribuído como **uma única imagem autossuficiente**: um só processo Node serve a API REST, o endpoint MCP para agentes e a interface web compilada em uma única porta (`3000` por padrão). Nenhum serviço externo — nada de banco de dados, broker de mensagens ou motor de busca separado — é necessário: o motor de conhecimento roda dentro desse mesmo processo. Todo o estado vive em um único volume `/data`: o banco de metadados, os índices derivados, seus arquivos Markdown (a fonte da verdade) e os artefatos de exportação.

> [!note] O que você vai precisar
> Apenas **Docker** (ou Docker Desktop) e uma porta livre. Não é preciso instalar Node, banco de dados nem índice vetorial à parte — está tudo dentro da imagem.

## Executar a imagem

O caminho mais rápido é subir um contêiner a partir da imagem pré-construída:

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

Um único volume `/data` guarda todo o estado: o banco de metadados, os índices, suas notas e os artefatos de exportação. Não há mais nada para configurar — a porta `3000` e o caminho de dados `/data` já vêm embutidos na imagem. O volume sobrevive à recriação do contêiner; a porta à esquerda de `:3000` pode ser trocada por qualquer uma que esteja livre.

Não é preciso acrescentar nenhum comando ao `docker run`: o ponto de entrada da imagem é a CLI `notarium` embutida, e por padrão ela executa `start`. É a mesma CLI que traz os comandos de operador — `backup`, `restore`, `admin`, `healthcheck`, `version`. Veja [CLI da imagem](/docs/self-hosting/cli/).

## Usando Docker Compose

Para uma instância que você pretende manter, um arquivo compose é mais fácil de editar e de manter sob controle de versão, e o `restart` traz o contêiner de volta depois que o host reinicia.

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

volumes:
  notarium-data:
```

Salve como `compose.yaml` e suba tudo com `docker compose up -d`. O volume nomeado `notarium-data` vive independentemente do contêiner: o `docker compose down` não o remove, e só um `docker volume rm` explícito o apaga.

> [!note] As configurações também vão aqui
> As variáveis de ambiente entram no bloco `environment:` do serviço. Se preferir mantê-las em um arquivo à parte, acrescente ali também a linha `env_file: .env` — sozinho, um `.env` ao lado do arquivo compose **não** chega ao contêiner: o Docker Compose apenas usa esses valores para substituir variáveis no texto do próprio arquivo compose. A lista completa está em [Variáveis de ambiente](/docs/reference/environment-variables/).

## Primeira execução

Abra `http://localhost:3000` e você será recebido pela **tela de configuração inicial**. Por padrão, a instância roda no modo `password`, e o primeiro visitante cria o **proprietário** — a única conta com direitos de administrador e dona dos espaços que criar. Não existe senha pré-definida; assim que o proprietário se registra, a configuração inicial é encerrada de vez. Para saber mais sobre os modos, veja [Autenticação](/docs/self-hosting/authentication/).

## Volumes de dados

| Volume | O que guarda | Natureza |
|---|---|---|
| `/data` | Seus arquivos Markdown (`/data/spaces`, uma pasta por espaço), o banco de metadados (`/data/meta.db` — identificadores, histórico de versões, usuários, acesso), os índices derivados do motor (`/data/engine`) e os artefatos de exportação. | Os arquivos são a fonte da verdade (o princípio file-first); o banco de metadados não pode ser derivado dos arquivos; os índices são derivados e voltam com uma reconstrução. |

Proteja o volume em si: perdê-lo é perder seus dados junto. Se os índices em `/data/engine` se perderem, eles se reconstroem a partir dos arquivos; já o banco de metadados (`/data/meta.db` — histórico, usuários, acesso) e as próprias notas (`/data/spaces`) não podem ser restaurados de lugar nenhum — fazer backup deles é obrigatório. Para saber como tirar um backup verificado sem parar o serviço, veja [Backup e restauração](/docs/self-hosting/backup/).

## Construir a partir do código-fonte

Se você trabalha com o repositório do Notarium, o ponto de entrada único para o Docker é o `make`:

```bash
cp .env.example .env   # os valores padrão funcionam — não é preciso preencher nada
make up                # imagem de produção localmente → http://localhost:3000
make dev               # stack de desenvolvimento com hot-reload (HMR)
```

Comandos úteis: `make logs` (logs), `make ps` (status), `make down` (parar e remover), `make sh` (shell dentro do contêiner).

## Instalação sem registry (air-gapped)

Para implantar em um ambiente isolado, a imagem pode ser transferida como arquivo, sem acesso a um registry:

```bash
make image                              # construir a imagem
make save                               # exportar para notarium-<version>.tar.gz
# mova o arquivo para o host de destino e então:
docker load < notarium-<version>.tar.gz # carregar a imagem
```

Depois é só executá-la com o seu próprio `compose`/`.env` — a coordenada do registry não fica embutida na imagem.

O próximo passo é ajustar a instância às suas necessidades: veja [Configuração](/docs/self-hosting/configuration/).