--- title: "Variables de entorno" description: "La tabla completa de variables de entorno: modo y puerto, espacios y base de metadatos, búsqueda semántica y la imagen de Docker." --- # Variables de entorno Notarium se configura mediante variables de entorno. Los valores predeterminados ya funcionan: para una ejecución local no necesitas rellenar nada; copia `.env.example` a `.env` y edita solo las líneas que realmente necesites. El stack de Docker pasa `.env` al contenedor tal cual (los valores no se incrustan en la imagen), así que un mismo archivo describe tanto tu instancia local como la de producción. ```bash cp .env.example .env # los valores predeterminados funcionan — edita solo lo que necesites ``` A continuación, la referencia completa. Algunas variables se definen directamente en `.env.example`; otras (el ajuste fino de la búsqueda) tienen valores predeterminados en el código y no figuran explícitamente en el ejemplo: esas se señalan aparte. ## Variables principales Lo básico: puerto, modo de autenticación y la ubicación de la base de datos de metadatos y los espacios. | Variable | Propósito | Por defecto | Ejemplo | |---|---|---|---| | `DATA_DIR` | El único ajuste de datos: la raíz de la que se deriva todo lo demás — la base de datos de metadatos, los índices, las notas, los artefactos. Sin definir → se usa un valor predeterminado razonable. | `/data` (Docker); `~/.local/share/notarium` (host) | `DATA_DIR=/srv/notarium` | | `PORT` | El puerto en el que escucha el backend; un único listener de Fastify sirve `/api`, `/mcp` y los recursos estáticos de la SPA. | `3000` | `PORT=3000` | | `AUTH_MODE` | Modo de autenticación: `password` (inicio de sesión más una pantalla de configuración en el primer arranque, requiere la base de datos de metadatos) o `none` (un único principal con acceso total para escritorio/dev/intranet de confianza, sin interfaz de inicio de sesión). | `password` | `AUTH_MODE=none` | | `META_DB_URL` | La base de datos de metadatos: identidad, registro de revisiones, registro de espacios, autenticación, proyectos. Por defecto es sqlite bajo `DATA_DIR`, así que el modo `password` funciona sin configuración. Opcional: defínela solo para trasladar el estado de los metadatos a un Postgres externo (estado compartido, HA). | `sqlite:/meta.db` | `META_DB_URL=postgres://user:pass@db:5432/notarium` | | `SPACES_ROOT` | La raíz donde cada espacio es una carpeta; permite crear espacios desde la interfaz en tiempo de ejecución. Opcional: por defecto es `/spaces`, defínela solo si tus notas viven fuera de la raíz de datos. | `/spaces` | `SPACES_ROOT=/mnt/notes` | | `SPACES_CONFIG` | Topología explícita de espacios: JSON en línea o una ruta a un archivo JSON. Anula las variables de espacio único. | sin definir | `SPACES_CONFIG=/data/spaces.json` | | `ENGINE_DATA_DIR` | Donde el motor guarda los índices derivados — un archivo por espacio. El nombre del archivo sigue al de la carpeta del espacio y no cambia cuando se renombra el espacio. Borrar el directorio → reindexado en el arranque; el índice es recuperable. Opcional: por defecto es `/engine`, defínela para llevar los índices a otro disco. | `/engine` | `ENGINE_DATA_DIR=/mnt/ssd/engine` | | `JOBS_DATA_DIR` | El directorio de los trabajos: los artefactos de las exportaciones asíncronas (derivados, se limpian por TTL) **y** los archivos subidos de una importación sin terminar — estos viven exactamente lo que vive su trabajo, y por eso entran en la copia de seguridad. Opcional: por defecto es `/jobs`, defínela para moverlo a otro disco. | `/jobs` | `JOBS_DATA_DIR=/mnt/ssd/jobs` | | `SPACE_IDLE_EVICT_SECONDS` | Desaloja el modelo de lectura de un espacio inactivo. `0` — mantenerlo en caliente; los espacios con una conexión SSE activa nunca se desalojan. | `0` | `SPACE_IDLE_EVICT_SECONDS=900` | | `SYNC_POLL_SECONDS` | El intervalo de sondeo de cambios externos en disco (cada sondeo es un reescaneo completo del espacio). `0` — desactivar el sondeo. Para montajes no observables (volumen de red, en memoria) el intervalo efectivo se limita a un máximo de 60 s. | `120` | `SYNC_POLL_SECONDS=0` | | `PUBLIC_BASE_URL` | La dirección externa canónica de la instancia detrás de un proxy inverso — para los metadatos OAuth de los conectores MCP. Sin ella, la dirección se deriva de las cabeceras reenviadas del proxy. | sin definir | `PUBLIC_BASE_URL=https://notes.example.com` | | `TRUST_PROXY` | Una lista separada por comas de IP/CIDR de los proxies **inmediatos** — de ahí se deduce la IP real del cliente para los límites de intentos de inicio de sesión y para admitir nuevos clientes OAuth. Sin definir equivale al valor predeterminado seguro: `X-Forwarded-For` no influye en los límites. Los valores booleanos, los recuentos de saltos, los rangos con nombre y los rangos que abarcan todas las direcciones (`/0`) se rechazan en el arranque. | sin definir | `TRUST_PROXY=172.18.0.0/16` | > [!note] Base de datos de metadatos frente a archivos > En el disco viven dos cosas distintas. `SPACES_ROOT` es la **verdad en Markdown** (tus notas, una carpeta por espacio). `META_DB_URL` es la base de datos de metadatos: lo que no se puede derivar de los archivos (usuarios, accesos, historial de versiones). Más en la sección [Autoalojamiento](/docs/self-hosting/). ## Espacio único (host directo, sin Docker) Para ejecutar un único espacio sin `SPACES_CONFIG` y sin `SPACES_ROOT` (por ejemplo, una ejecución local directa, sin Docker). | Variable | Propósito | Por defecto | Ejemplo | |---|---|---|---| | `ENGINE` | El motor de un único espacio. El único valor es `notarium`; puedes dejarla sin definir. | `notarium` | `ENGINE=notarium` | | `NOTES_DIR` | Ruta absoluta a la carpeta de notas de un único espacio (modo de espacio único). | sin definir | `NOTES_DIR=/home/me/notes` | ## Búsqueda semántica La búsqueda léxica de texto completo (FTS) siempre funciona, sin configuración. La búsqueda semántica (vectorial) y la híbrida **hay que activarlas explícitamente**: un stack nativo pesado (`onnxruntime` + `sqlite-vec`, ~660 MB en disco) más el modelo de embeddings bge-m3 (~600 MB en disco, cientos de MB de RAM). Las variables de abajo tienen valores predeterminados en el código y no figuran explícitamente en `.env.example`. | Variable | Propósito | Por defecto | Ejemplo | |---|---|---|---| | `VECTOR_SEARCH` | `on`/`off` — activa la semántica y la fusión híbrida. Cuando falta el stack nativo, `on` recurre a la búsqueda de texto completo — sin error. | `on` (código), `off` (imagen publicada) | `VECTOR_SEARCH=on` | | `EMBED_MODEL` | El id del modelo de embeddings (transformers.js/ONNX). Defínela **junto** con `EMBED_DIMENSIONS`. | `Xenova/bge-m3` | `EMBED_MODEL=Xenova/multilingual-e5-small` | | `EMBED_DIMENSIONS` | El ancho del vector; **debe** coincidir con el modelo (bge-m3 — 1024, e5-small — 384). Una discrepancia es fail-closed: la nota se queda solo con FTS. | `1024` | `EMBED_DIMENSIONS=384` | | `EMBED_DTYPE` | Cuantización del modelo: `fp32` / `fp16` / `q8` / `q4`. | `q8` | `EMBED_DTYPE=fp16` | | `EMBED_THREADS` | El número de hilos intra-op de ONNX por worker de indexación en segundo plano (un pool de `EMBED_WORKERS` workers). | `1` por worker (repliegue sin pool — la mitad de los núcleos) | `EMBED_THREADS=2` | | `EMBED_WORKERS` | El tamaño del pool de `worker_threads` de embeddings = paralelismo de la indexación en segundo plano entre núcleos. Cada worker mantiene su propia copia del modelo (afecta a la RAM). | `max(1, min(cores−2, 4))` | `EMBED_WORKERS=8` | | `EMBED_QUERY_PREFIX` / `EMBED_PASSAGE_PREFIX` | Prefijos para modelos asimétricos (e5). Para el bge-m3 simétrico, **déjalos sin definir** — de lo contrario la calidad baja de formas que no notarás. | sin definir | `EMBED_QUERY_PREFIX="query: "` | | `EMBED_CPU_MEM_ARENA` | `on`/`off`. `off` mantiene el consumo plano en ~1,9 GB de RAM para bge-m3 — una protección contra el OOM en una máquina ajustada y sin swap (con `on` la arena puede trepar hasta varios GB). | `on` | `EMBED_CPU_MEM_ARENA=off` | | `GRAPH_BOOST` | `on`/`off` — un tercer canal RRF (un refuerzo por grafo sobre los enlaces, wiki-link de 1 salto). Inerte cuando `VECTOR_SEARCH=off`. | `off` | `GRAPH_BOOST=on` | > [!warning] Dos interruptores independientes > Para que la semántica funcione localmente necesitas **ambos**: el stack nativo **instalado** (`make deps-vector`; el `make deps` por defecto no lo instala, la imagen publicada siempre lo incluye) **y** `VECTOR_SEARCH=on`. Si falta el stack, `on` recurre a la búsqueda léxica de texto completo — sin error. Más en las secciones [Búsqueda](/docs/concepts/search/) y [Configuración de la búsqueda](/docs/self-hosting/search-setup/). ## Copia de seguridad y restauración Los comandos integrados `backup`, `backup verify` y `restore` funcionan sin configuración. Las variables de abajo solo importan cuando la raíz del contenedor está montada en solo lectura o cuando tus datos son bastante más grandes de lo habitual. Más en [Copia de seguridad y restauración](/docs/self-hosting/backup/). | Variable | Propósito | Por defecto | Ejemplo | |---|---|---|---| | `NOTARIUM_BACKUP_TMPDIR` | El directorio para los archivos intermedios de una copia de seguridad, una verificación o una restauración. Defínela si la raíz del contenedor es de solo lectura o si a `/tmp` le falta espacio: una copia de seguridad en streaming puede necesitar temporalmente sitio para el archivo comprimido más dos etapas expandidas. | `/tmp` | `NOTARIUM_BACKUP_TMPDIR=/mnt/scratch` | | `NOTARIUM_BACKUP_MAX_BYTES` | El techo de tamaño — tanto para la entrada comprimida como para la carga expandida. Una protección contra las zip-bombs; solo las instalaciones grandes y de confianza lo suben. | 64 GiB | `NOTARIUM_BACKUP_MAX_BYTES=137438953472` | | `NOTARIUM_BACKUP_MAX_ENTRIES` | El techo del número de entradas del archivo. | `1000000` | `NOTARIUM_BACKUP_MAX_ENTRIES=2000000` | | `NOTARIUM_BACKUP_MAX_METADATA_BYTES` | Un techo de memoria aparte para los nombres, las estructuras internas del ZIP y `manifest.json`. | 32 MiB | `NOTARIUM_BACKUP_MAX_METADATA_BYTES=67108864` | ## Docker y compilación | Variable | Propósito | Por defecto | Ejemplo | |---|---|---|---| | `IMAGE` / `TAG` | La referencia de la imagen para `docker compose` / `make up`. La vía principal de instalación es la imagen pública `docouno/notarium:latest`; sobrescribe la coordenada para usar tu propio registro o una etiqueta concreta. | `docouno/notarium:latest` | `IMAGE=docouno/notarium` `TAG=latest` | | `GIT_SHA` / `BUILD_TIME` | Build-args; se incrustan en `GET /api/about` y en la pestaña **Settings → About**. Sin ellos — `null`. | vacío | `GIT_SHA=$(git rev-parse --short HEAD)` | > [!important] La imagen y la compilación desde el código fuente > `docouno/notarium:latest` es la imagen pública y la vía principal de instalación; `IMAGE` / `TAG` determinan qué imagen descargará `docker compose` / `make up`. Si la imagen aún no se ha descargado del registro — compila desde el código fuente en el repositorio principal: `make up` (el comportamiento es idéntico). ## Véase también - [Configuración de autoalojamiento](/docs/self-hosting/configuration/) — instalación, volúmenes, configuración de producción. - [Búsqueda](/docs/concepts/search/) — léxica, semántica, fusión híbrida y el repliegue a la búsqueda de texto completo sin error. - [Referencia de atajos de teclado](/docs/reference/keyboard-shortcuts/) — distribuciones y preajustes.