--- title: "Variáveis de ambiente" description: "A tabela completa de variáveis de ambiente da instância: modo e porta, espaços e o banco de metadados, busca semântica, a imagem Docker." --- # 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. ```bash 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:/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 é `/spaces`, defina apenas se suas notas ficarem fora da raiz de dados. | `/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 é `/engine`, defina para mover os índices para outro disco. | `/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 é `/jobs`, defina para movê-lo para outro disco. | `/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` | > [!note] Banco de metadados vs. arquivos > 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](/docs/self-hosting/). ## 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` | > [!warning] Dois interruptores independentes > 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](/docs/concepts/search/) e [Configuração da busca](/docs/self-hosting/search-setup/). ## 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](/docs/self-hosting/backup/). | 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)` | > [!important] A imagem e o build a partir do código-fonte > `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](/docs/self-hosting/configuration/) — instalação, volumes, configuração de produção. - [Busca](/docs/concepts/search/) — 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](/docs/reference/keyboard-shortcuts/) — layouts e presets.