Instalação e primeira execução

O Notarium é distribuído como uma única imagem autossuficiente: um só processo serve a interface web, a API REST e o endpoint MCP para agentes, enquanto o motor de conhecimento roda dentro dele. Nenhum serviço externo — nada de banco de dados, broker de mensagens ou motor de busca separado — é necessário. Para começar, basta ter Docker e uma porta livre.

Esta página é o caminho rápido: subir uma instância, abrir no navegador e criar o proprietário. A auto-hospedagem detalhada (Postgres, proxy reverso, configuração de produção) fica na seção Self-host.

O que você vai precisar

• Docker (ou Docker Desktop) — nada mais para instalar: Node, o banco de dados e o índice de busca já estão dentro da imagem.
• Uma porta livre — 3000 por padrão.
• Um pouco de espaço em disco para suas notas e o índice derivado.

Rodando um único contêiner

O caminho mais curto é rodar a imagem pré-construída docouno/notarium:

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

Depois de alguns segundos, abra http://localhost:3000.

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 /data já vêm embutidos na imagem. Você pode trocar a porta à esquerda de 3000 por qualquer uma que esteja livre.

Uma alternativa é construir a partir do código-fonte via make, o ponto de entrada único para tudo que envolve Docker:

cp .env.example .env   # os padrões funcionam — não há nada para preencher
make up                # constrói a imagem de produção e sobe → http://localhost:3000

Outros comandos são úteis no dia a dia: make logs para os logs, make ps para o status, make down para parar e remover, make sh para abrir um shell dentro do contêiner.

Volumes: onde os dados ficam

Todo o estado vive em um único volume — é ele que você precisa preservar ao recriar o contêiner:

O princípio central é file-first: a fonte da verdade são os arquivos .md em /data/spaces. Os índices de busca e o grafo em /data/engine são derivados: eles são reconstruídos a partir dos arquivos, então, se você perdê-los, uma reindexação os traz de volta. Já o banco de metadados /data/meta.db — histórico de versões, usuários e acesso — vive apenas no volume, por isso /data merece o mesmo cuidado que suas notas. Para backups, você só precisa das suas notas e do meta.db; os índices derivados podem ficar de fora.

Primeira execução: a tela de configuração

Na primeira visita, o Notarium recebe você com uma tela de configuração. Não há senha predefinida: o primeiro visitante cria o proprietário da instância — essa conta se torna o administrador e o dono dos espaços que criar. Depois disso, a configuração se fecha para sempre, e você chega ao editor, já dentro do seu espaço pessoal.

É assim que funciona o modo de autenticação padrão — AUTH_MODE=password. Ele foi pensado para uma instância acessível publicamente: login, sessões, tokens pessoais para agentes. O segundo modo, none (um único principal com acesso total, sem tela de login), serve apenas para um ambiente confiável: um desktop, desenvolvimento local ou uma intranet fechada. Os detalhes estão na seção Autenticação.

Configuração básica

Os padrões são zero-config: a imagem como está já basta para começar. O ajuste fino acontece por meio de variáveis de ambiente (no Docker, o .env as repassa; nada fica embutido na imagem):

A busca de texto completo funciona sempre, sem nenhuma configuração. A busca semântica (vetorial) é opcional, ativada pela flag VECTOR_SEARCH=on: ela carrega um modelo de embeddings local (na ordem de centenas de megabytes de RAM), por isso vem desligada na imagem publicada e precisa ser ativada de forma deliberada. Sem ela, a busca continua funcionando sobre o texto completo — sem erro; esse é o modo normal. A lista completa de variáveis e a configuração da busca estão nas seções Configuração e Configuração da busca.

Próximos passos

A instância está no ar e o proprietário foi criado — hora de preencher sua base de conhecimento e abri-la a um agente:

• Sua primeira nota — a árvore de arquivos, o editor web e o salvamento em .md.
• Conectar um agente — o token, o endpoint POST /mcp e a primeira chamada.

Quer entender o modelo por completo? Dê uma olhada na seção Conceitos: espaços, tipos de nota, o grafo e o modelo de acesso.