Variáveis de ambiente
O Notarium é configurado por variáveis de ambiente. Os padrões simplesmente funcionam — para rodar localmente você não precisa preencher nada: copie .env.example para .env e edite só as linhas que realmente importam. O stack Docker repassa o .env para o contêiner como está (os valores não ficam gravados na imagem), então o mesmo arquivo descreve tanto a sua instância local quanto a de produção.
cp .env.example .env # os padrões funcionam — edite só o que precisar
Abaixo está a referência completa. Algumas variáveis são definidas diretamente no .env.example; outras (ajuste fino da busca) têm padrões no código e não aparecem no exemplo — essas estão sinalizadas à parte.
Núcleo
O básico: porta, modo de autenticação e a localização do banco de metadados e dos espaços.
| Variável | Finalidade | Padrão | Exemplo |
|---|---|---|---|
DATA_DIR | O único ajuste de dados: a raiz da qual todo o resto é derivado — o banco de metadados, os índices, as notas, os artefatos. Não definida → usa-se um padrão razoável. | /data (Docker); ~/.local/share/notarium (host) | DATA_DIR=/srv/notarium |
PORT | A porta em que o backend escuta; um único listener Fastify serve /api, /mcp e os assets estáticos da SPA. | 3000 | PORT=3000 |
AUTH_MODE | Modo de autenticação: password (login e uma tela de configuração no primeiro uso, exige o banco de metadados) ou none (um único principal com acesso total, para desktop/dev/intranet confiável, sem interface de login). | password | AUTH_MODE=none |
META_DB_URL | O banco de metadados: identidade, registro de revisões, cadastro de espaços, autenticação, projetos. Por padrão usa sqlite sob DATA_DIR, então o modo password funciona sem nenhuma configuração. Opcional: defina apenas para mover o estado de metadados para um Postgres externo (estado compartilhado, HA). | sqlite:<DATA_DIR>/meta.db | META_DB_URL=postgres://user:pass@db:5432/notarium |
SPACES_ROOT | A raiz onde cada espaço é uma pasta; habilita a criação de espaços pela interface em tempo de execução. Opcional: por padrão é <DATA_DIR>/spaces, defina apenas se suas notas ficarem fora da raiz de dados. | <DATA_DIR>/spaces | SPACES_ROOT=/mnt/notes |
SPACES_CONFIG | Topologia explícita de espaços: JSON inline ou o caminho para um arquivo JSON. Sobrescreve as variáveis de espaço único. | não definida | SPACES_CONFIG=/data/spaces.json |
ENGINE_DATA_DIR | Onde o motor guarda os índices derivados — um arquivo por espaço. O nome do arquivo acompanha o nome da pasta do espaço e não muda quando o espaço é renomeado. Apagar o diretório → uma reindexação na inicialização; o índice é recuperável. Opcional: por padrão é <DATA_DIR>/engine, defina para mover os índices para outro disco. | <DATA_DIR>/engine | ENGINE_DATA_DIR=/mnt/ssd/engine |
JOBS_DATA_DIR | O diretório das tarefas: os artefatos das exportações assíncronas (derivados, limpos por TTL) e os arquivos enviados de uma importação inacabada — esses vivem exatamente o tempo que a tarefa deles durar, e é por isso que entram no backup. Opcional: por padrão é <DATA_DIR>/jobs, defina para movê-lo para outro disco. | <DATA_DIR>/jobs | JOBS_DATA_DIR=/mnt/ssd/jobs |
SPACE_IDLE_EVICT_SECONDS | Descarrega o modelo de leitura (read model) de um espaço ocioso. 0 — mantém aquecido; espaços com uma conexão SSE ativa nunca são descarregados. | 0 | SPACE_IDLE_EVICT_SECONDS=900 |
SYNC_POLL_SECONDS | O intervalo de sondagem de alterações externas em disco (cada sondagem é um reescaneamento completo do espaço). 0 — desativa a sondagem. Para montagens não observáveis (volume de rede, in-memory) o intervalo efetivo é limitado a 60 s. | 120 | SYNC_POLL_SECONDS=0 |
PUBLIC_BASE_URL | O endereço externo canônico da instância atrás de um proxy reverso — para os metadados OAuth dos conectores MCP. Sem ele, o endereço é derivado dos cabeçalhos encaminhados pelo proxy. | não definida | PUBLIC_BASE_URL=https://notes.example.com |
TRUST_PROXY | Uma lista, separada por vírgulas, de IPs/CIDRs dos proxies imediatos — é dela que sai o IP real do cliente para os limites de tentativas de login e para a admissão de novos clientes OAuth. Não definida significa o padrão seguro: o X-Forwarded-For não influencia os limites. Valores booleanos, contagens de saltos, faixas nomeadas e faixas que cobrem todos os endereços (/0) são rejeitados na inicialização. | não definida | TRUST_PROXY=172.18.0.0/16 |
Duas coisas diferentes ficam em disco. SPACES_ROOT é a verdade Markdown (suas notas, uma pasta por espaço). META_DB_URL é o banco de metadados: o que não pode ser derivado dos arquivos (usuários, acesso, histórico de versões). Mais na seção Auto-hospedagem.
Espaço único (bare-host, sem Docker)
Para rodar um único espaço sem SPACES_CONFIG e sem SPACES_ROOT (por exemplo, uma execução local direta no host, sem Docker).
| Variável | Finalidade | Padrão | Exemplo |
|---|---|---|---|
ENGINE | O motor de um único espaço. O único valor é notarium; você pode deixá-la sem definir. | notarium | ENGINE=notarium |
NOTES_DIR | Caminho absoluto para a pasta de notas de um único espaço (modo de espaço único). | não definida | NOTES_DIR=/home/me/notes |
Busca semântica
A busca léxica de texto completo (FTS) sempre funciona, sem nenhuma configuração. A busca semântica (vetorial) e a híbrida são opt-in: um stack nativo pesado (onnxruntime + sqlite-vec, ~660 MB em disco) mais o modelo de embeddings bge-m3 (~600 MB em disco, centenas de MB de RAM). As variáveis abaixo têm padrões no código e não aparecem no .env.example.
| Variável | Finalidade | Padrão | Exemplo |
|---|---|---|---|
VECTOR_SEARCH | on/off — liga a semântica e a fusão híbrida. Quando o stack nativo está ausente, on recai na busca de texto completo — sem erro. | on (código), off (imagem publicada) | VECTOR_SEARCH=on |
EMBED_MODEL | O id do modelo de embeddings (transformers.js/ONNX). Defina junto com EMBED_DIMENSIONS. | Xenova/bge-m3 | EMBED_MODEL=Xenova/multilingual-e5-small |
EMBED_DIMENSIONS | A largura do vetor; precisa casar com o modelo (bge-m3 — 1024, e5-small — 384). Uma divergência é fail-closed: a nota permanece apenas em FTS. | 1024 | EMBED_DIMENSIONS=384 |
EMBED_DTYPE | Quantização do modelo: fp32 / fp16 / q8 / q4. | q8 | EMBED_DTYPE=fp16 |
EMBED_THREADS | O número de threads intra-op do ONNX por worker de indexação em segundo plano (um pool de EMBED_WORKERS workers). | 1 por worker (fallback sem pool — metade dos núcleos) | EMBED_THREADS=2 |
EMBED_WORKERS | O tamanho do pool de worker_threads de embeddings = paralelismo da indexação em segundo plano pelos núcleos. Cada worker mantém sua própria cópia do modelo (isso afeta a RAM). | max(1, min(núcleos−2, 4)) | EMBED_WORKERS=8 |
EMBED_QUERY_PREFIX / EMBED_PASSAGE_PREFIX | Prefixos para modelos assimétricos (e5). Para o bge-m3 simétrico, deixe sem definir — senão a qualidade cai de um jeito que você não vai perceber. | não definidas | EMBED_QUERY_PREFIX="query: " |
EMBED_CPU_MEM_ARENA | on/off. off mantém o consumo estável em ~1,9 GB de RAM para o bge-m3 — uma proteção contra OOM em uma máquina apertada e sem swap (com on a arena pode subir aos poucos até vários GB). | on | EMBED_CPU_MEM_ARENA=off |
GRAPH_BOOST | on/off — um terceiro canal do RRF (um graph boost sobre os links, wikilink de 1 salto). Inerte quando VECTOR_SEARCH=off. | off | GRAPH_BOOST=on |
Para a semântica funcionar localmente você precisa dos dois: o stack nativo instalado (make deps-vector; o make deps padrão não o instala, a imagem publicada sempre o traz) e VECTOR_SEARCH=on. Se o stack estiver ausente, on recai na busca léxica de texto completo — sem erro. Mais nas seções Busca e Configuração da busca.
Backup e restauração
Os comandos embutidos backup, backup verify e restore funcionam sem nenhuma configuração. As variáveis abaixo só importam quando a raiz do contêiner está montada somente para leitura ou quando seus dados são bem maiores que o normal. Mais em Backup e restauração.
| Variável | Finalidade | Padrão | Exemplo |
|---|---|---|---|
NOTARIUM_BACKUP_TMPDIR | O diretório para os arquivos intermediários de um backup, de uma verificação ou de uma restauração. Defina se a raiz do contêiner for somente leitura ou se faltar espaço em /tmp: um backup em streaming pode precisar temporariamente de espaço para o arquivo compactado mais dois estágios expandidos. | /tmp | NOTARIUM_BACKUP_TMPDIR=/mnt/scratch |
NOTARIUM_BACKUP_MAX_BYTES | O teto de tamanho — tanto da entrada compactada quanto do conteúdo expandido. Uma proteção contra zip bomb; só instalações grandes e confiáveis aumentam esse valor. | 64 GiB | NOTARIUM_BACKUP_MAX_BYTES=137438953472 |
NOTARIUM_BACKUP_MAX_ENTRIES | O teto do número de entradas no arquivo compactado. | 1000000 | NOTARIUM_BACKUP_MAX_ENTRIES=2000000 |
NOTARIUM_BACKUP_MAX_METADATA_BYTES | Um teto de memória à parte para os nomes, as estruturas internas do ZIP e o manifest.json. | 32 MiB | NOTARIUM_BACKUP_MAX_METADATA_BYTES=67108864 |
Docker e build
| Variável | Finalidade | Padrão | Exemplo |
|---|---|---|---|
IMAGE / TAG | A referência da imagem para docker compose / make up. O caminho principal de instalação é a imagem pública docouno/notarium:latest; substitua a coordenada para usar seu próprio registry ou uma tag específica. | docouno/notarium:latest | IMAGE=docouno/notarium TAG=latest |
GIT_SHA / BUILD_TIME | Build-args; embutidos em GET /api/about e na aba Settings → About. Sem eles — null. | vazio | GIT_SHA=$(git rev-parse --short HEAD) |
docouno/notarium:latest é a imagem pública e o caminho principal de instalação; IMAGE / TAG definem qual imagem o docker compose / make up vai baixar. Se a imagem ainda não foi baixada do registry — faça o build a partir do código-fonte no repositório principal: make up (o comportamento é idêntico).
Veja também
- Configuração da auto-hospedagem — instalação, volumes, configuração de produção.
- Busca — léxica, semântica, fusão híbrida e o fallback para a busca de texto completo sem erro.
- Referência de atalhos de teclado — layouts e presets.