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.
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:<DATA_DIR>/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 <DATA_DIR>/spaces, defínela solo si tus notas viven fuera de la raíz de datos. | <DATA_DIR>/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 <DATA_DIR>/engine, defínela para llevar los índices a otro disco. | <DATA_DIR>/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 <DATA_DIR>/jobs, defínela para moverlo a otro disco. | <DATA_DIR>/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 |
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.
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 |
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 y Configuración de la búsqueda.
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.
| 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) |
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 — instalación, volúmenes, configuración de producción.
- Búsqueda — 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 — distribuciones y preajustes.