---
title: "Instalação e primeira execução"
description: "Suba o Notarium com um único contêiner Docker, abra em localhost:3000 e passe pela tela de configuração inicial que cria o proprietário."
---

# 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](/docs/self-hosting/).

## 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`:

```bash
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.

> [!note] Construindo a partir do código-fonte
> Se a imagem ainda não foi baixada do registry, construa a partir do código-fonte no repositório principal do Notarium com `make up` (veja abaixo): o comportamento é idêntico.

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

```bash
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:

| Volume | Ponto de montagem | O que armazena |
|---|---|---|
| `notarium-data` | `/data` | Tudo: suas notas (`/data/spaces`), o banco de metadados (`/data/meta.db`), os índices de busca derivados (`/data/engine`) e os artefatos de exportação (`/data/jobs`) |

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.

> [!tip] Sua própria porta
> Troque a porta `3000` no lado esquerdo de `-p <sua>:3000` (ou pela variável `PORT` no `.env`). A imagem escuta em todas as interfaces do contêiner — ela expõe exatamente o que você mapear.

## 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](/docs/self-hosting/authentication/).

## 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):

| Variável | Valor | Padrão |
|---|---|---|
| `PORT` | A porta em que o servidor escuta | `3000` |
| `AUTH_MODE` | `password` (login + configuração) ou `none` (ambiente confiável) | `password` |
| `VECTOR_SEARCH` | Ativa a busca semântica (vetorial) além da léxica | `off` 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](/docs/self-hosting/configuration/) e [Configuração da busca](/docs/self-hosting/search-setup/).

## 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](/docs/getting-started/first-note/) — a árvore de arquivos, o editor web e o salvamento em `.md`.
- [Conectar um agente](/docs/getting-started/connect-agent/) — o token, o endpoint `POST /mcp` e a primeira chamada.

Quer entender o modelo por completo? Dê uma olhada na seção [Conceitos](/docs/concepts/): espaços, tipos de nota, o grafo e o modelo de acesso.