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.
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:
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.
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.
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.
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.
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.
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.
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:
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:
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.