--- title: "Variables d'environnement" description: "Le tableau complet des variables d'environnement de l'instance : mode et port, espaces et base de métadonnées, recherche sémantique, image Docker." --- # Variables d'environnement Notarium se configure via des variables d'environnement. Les valeurs par défaut fonctionnent telles quelles — pour un usage local, vous n'avez rien à renseigner : copiez `.env.example` vers `.env`, puis modifiez uniquement les lignes dont vous avez réellement besoin. La stack Docker transmet `.env` au conteneur tel quel (les valeurs ne sont pas figées dans l'image), si bien qu'un même fichier décrit à la fois votre instance locale et votre instance de production. ```bash cp .env.example .env # les valeurs par défaut fonctionnent — ne modifiez que ce qui est nécessaire ``` Ci-dessous, la référence complète. Certaines variables sont définies directement dans `.env.example` ; d'autres (le réglage fin de la recherche) ont des valeurs par défaut dans le code et ne sont pas explicitées dans l'exemple — elles sont signalées à part. ## Cœur L'essentiel : le port, le mode d'authentification et l'emplacement de la base de métadonnées et des espaces. | Variable | Rôle | Par défaut | Exemple | |---|---|---|---| | `DATA_DIR` | L'unique bouton de réglage des données : la racine dont tout le reste dérive — la base de métadonnées, les index, les notes, les artefacts. Non définie → une valeur par défaut raisonnable est utilisée. | `/data` (Docker) ; `~/.local/share/notarium` (hôte) | `DATA_DIR=/srv/notarium` | | `PORT` | Le port sur lequel écoute le backend ; un unique listener Fastify sert `/api`, `/mcp` et les ressources statiques de la SPA. | `3000` | `PORT=3000` | | `AUTH_MODE` | Mode d'authentification : `password` (connexion plus un écran de configuration au premier lancement, nécessite la base de métadonnées) ou `none` (un unique principal en accès total pour desktop/dev/intranet de confiance, sans interface de connexion). | `password` | `AUTH_MODE=none` | | `META_DB_URL` | La base de métadonnées : identité, journal des révisions, registre des espaces, authentification, projets. Par défaut, sqlite sous `DATA_DIR`, si bien que le mode `password` fonctionne sans configuration. Optionnelle : ne la définissez que pour déplacer l'état des métadonnées vers un Postgres externe (état partagé, HA). | `sqlite:/meta.db` | `META_DB_URL=postgres://user:pass@db:5432/notarium` | | `SPACES_ROOT` | La racine où chaque espace est un dossier ; permet de créer des espaces depuis l'interface à l'exécution. Optionnelle : vaut `/spaces` par défaut, ne la définissez que si vos notes se trouvent en dehors de la racine des données. | `/spaces` | `SPACES_ROOT=/mnt/notes` | | `SPACES_CONFIG` | Topologie explicite des espaces : JSON en ligne ou chemin vers un fichier JSON. Prend le pas sur les variables single-space. | non définie | `SPACES_CONFIG=/data/spaces.json` | | `ENGINE_DATA_DIR` | Là où le moteur conserve les index dérivés — un fichier par espace. Le nom du fichier suit celui du dossier de l'espace et ne change pas lorsque l'espace est renommé. Supprimer le répertoire → une réindexation au démarrage ; l'index est récupérable. Optionnelle : vaut `/engine` par défaut, définissez-la pour déplacer les index sur un autre disque. | `/engine` | `ENGINE_DATA_DIR=/mnt/ssd/engine` | | `JOBS_DATA_DIR` | Le répertoire des tâches : les artefacts des exports asynchrones (dérivés, nettoyés par TTL) **et** les fichiers téléversés d'un import inachevé — ces derniers vivent exactement aussi longtemps que leur tâche, et c'est pourquoi ils ont leur place dans une sauvegarde. Optionnelle : vaut `/jobs` par défaut, définissez-la pour le déplacer sur un autre disque. | `/jobs` | `JOBS_DATA_DIR=/mnt/ssd/jobs` | | `SPACE_IDLE_EVICT_SECONDS` | Décharge le modèle de lecture (read model) d'un espace inactif. `0` — le garder au chaud ; les espaces disposant d'une connexion SSE active ne sont jamais déchargés. | `0` | `SPACE_IDLE_EVICT_SECONDS=900` | | `SYNC_POLL_SECONDS` | L'intervalle d'interrogation des modifications externes sur disque (chaque interrogation est un rescan complet de l'espace). `0` — désactiver l'interrogation. Pour les montages non surveillables (volume réseau, en mémoire), l'intervalle effectif est plafonné à 60 s. | `120` | `SYNC_POLL_SECONDS=0` | | `PUBLIC_BASE_URL` | L'adresse externe canonique de l'instance derrière un reverse proxy — pour les métadonnées OAuth des connecteurs MCP. Sans elle, l'adresse est dérivée des en-têtes forwarded du proxy. | non définie | `PUBLIC_BASE_URL=https://notes.example.com` | | `TRUST_PROXY` | La liste, séparée par des virgules, des IP/CIDR des proxys **immédiats** — elle sert à déterminer l'adresse IP réelle du client pour les limites de tentatives de connexion et pour l'admission de nouveaux clients OAuth. Non définie, c'est le comportement par défaut et sûr : `X-Forwarded-For` n'a aucun effet sur les limites. Les valeurs booléennes, les compteurs de sauts, les plages nommées et les plages couvrant toutes les adresses (`/0`) sont rejetés au démarrage. | non définie | `TRUST_PROXY=172.18.0.0/16` | > [!note] Base de métadonnées vs fichiers > Deux choses différentes coexistent sur le disque. `SPACES_ROOT`, c'est la **vérité Markdown** (vos notes, un dossier par espace). `META_DB_URL`, c'est la base de métadonnées : ce qui ne peut pas être dérivé des fichiers (utilisateurs, accès, historique des versions). Plus de détails dans la section [Auto-hébergement](/docs/self-hosting/). ## Single-space (bare-host, sans Docker) Pour exécuter un espace unique sans `SPACES_CONFIG` ni `SPACES_ROOT` (par exemple, une exécution locale en bare-run sans Docker). | Variable | Rôle | Par défaut | Exemple | |---|---|---|---| | `ENGINE` | Le moteur d'un espace unique. La seule valeur est `notarium` ; vous pouvez la laisser non définie. | `notarium` | `ENGINE=notarium` | | `NOTES_DIR` | Chemin absolu vers le dossier de notes d'un espace unique (mode single-space). | non définie | `NOTES_DIR=/home/me/notes` | ## Recherche sémantique La recherche lexicale plein texte (FTS) fonctionne toujours, sans aucune configuration. La recherche sémantique (vectorielle) et la recherche hybride sont **à activer explicitement** : une lourde stack native (`onnxruntime` + `sqlite-vec`, ~660 Mo sur disque) plus le modèle d'embeddings bge-m3 (~600 Mo sur disque, plusieurs centaines de Mo de RAM). Les variables ci-dessous ont des valeurs par défaut dans le code et ne sont pas explicitées dans `.env.example`. | Variable | Rôle | Par défaut | Exemple | |---|---|---|---| | `VECTOR_SEARCH` | `on`/`off` — active la sémantique et la fusion hybride. En l'absence de la stack native, `on` bascule vers la recherche plein texte — sans erreur. | `on` (code), `off` (image publiée) | `VECTOR_SEARCH=on` | | `EMBED_MODEL` | L'identifiant du modèle d'embeddings (transformers.js/ONNX). À définir **conjointement** avec `EMBED_DIMENSIONS`. | `Xenova/bge-m3` | `EMBED_MODEL=Xenova/multilingual-e5-small` | | `EMBED_DIMENSIONS` | La largeur du vecteur ; elle **doit** correspondre au modèle (bge-m3 — 1024, e5-small — 384). Une divergence est fail-closed : la note reste en FTS uniquement. | `1024` | `EMBED_DIMENSIONS=384` | | `EMBED_DTYPE` | Quantification du modèle : `fp32` / `fp16` / `q8` / `q4`. | `q8` | `EMBED_DTYPE=fp16` | | `EMBED_THREADS` | Le nombre de threads ONNX intra-op par worker d'indexation en arrière-plan (un pool de `EMBED_WORKERS` workers). | `1` par worker (fallback sans pool — la moitié des cœurs) | `EMBED_THREADS=2` | | `EMBED_WORKERS` | La taille du pool `worker_threads` d'embeddings = le parallélisme de l'indexation en arrière-plan sur les cœurs. Chaque worker conserve sa propre copie du modèle (cela impacte la RAM). | `max(1, min(cores−2, 4))` | `EMBED_WORKERS=8` | | `EMBED_QUERY_PREFIX` / `EMBED_PASSAGE_PREFIX` | Préfixes pour les modèles asymétriques (e5). Pour le bge-m3 symétrique, **ne les définissez pas** — sinon la qualité se dégrade sans que vous vous en aperceviez. | non définies | `EMBED_QUERY_PREFIX="query: "` | | `EMBED_CPU_MEM_ARENA` | `on`/`off`. `off` maintient la consommation stable à ~1,9 Go de RAM pour le bge-m3 — une protection contre l'OOM sur une machine à mémoire serrée et sans swap (avec `on`, l'arena peut grimper jusqu'à plusieurs Go). | `on` | `EMBED_CPU_MEM_ARENA=off` | | `GRAPH_BOOST` | `on`/`off` — un troisième canal RRF (un graph boost sur les liens, wiki-link à 1 saut). Inerte lorsque `VECTOR_SEARCH=off`. | `off` | `GRAPH_BOOST=on` | > [!warning] Deux interrupteurs indépendants > Pour que la sémantique fonctionne en local, il faut les **deux** : la stack native **installée** (`make deps-vector` ; le `make deps` par défaut ne l'installe pas, l'image publiée l'embarque toujours) **et** `VECTOR_SEARCH=on`. Si la stack est absente, `on` bascule vers la recherche lexicale plein texte — sans erreur. Plus de détails dans les sections [Recherche](/docs/concepts/search/) et [Configuration de la recherche](/docs/self-hosting/search-setup/). ## Sauvegarde et restauration Les commandes intégrées `backup`, `backup verify` et `restore` fonctionnent sans aucune configuration. Les variables ci-dessous n'entrent en jeu que si la racine du conteneur est montée en lecture seule ou si vos données sont nettement plus volumineuses que la normale. Plus de détails dans [Sauvegarde et restauration](/docs/self-hosting/backup/). | Variable | Rôle | Par défaut | Exemple | |---|---|---|---| | `NOTARIUM_BACKUP_TMPDIR` | Le répertoire des fichiers intermédiaires d'une sauvegarde, d'une vérification ou d'une restauration. Définissez-le si la racine du conteneur est en lecture seule ou si `/tmp` manque de place : une sauvegarde en flux peut avoir temporairement besoin de la place nécessaire pour l'archive plus deux étapes décompressées. | `/tmp` | `NOTARIUM_BACKUP_TMPDIR=/mnt/scratch` | | `NOTARIUM_BACKUP_MAX_BYTES` | Le plafond de taille — pour l'entrée compressée comme pour la charge utile décompressée. Une protection contre les zip-bombs ; seules les grosses installations de confiance le relèvent. | 64 Gio | `NOTARIUM_BACKUP_MAX_BYTES=137438953472` | | `NOTARIUM_BACKUP_MAX_ENTRIES` | Le plafond du nombre d'entrées dans l'archive. | `1000000` | `NOTARIUM_BACKUP_MAX_ENTRIES=2000000` | | `NOTARIUM_BACKUP_MAX_METADATA_BYTES` | Un plafond de mémoire distinct pour les noms, les structures internes du ZIP et `manifest.json`. | 32 Mio | `NOTARIUM_BACKUP_MAX_METADATA_BYTES=67108864` | ## Docker et build | Variable | Rôle | Par défaut | Exemple | |---|---|---|---| | `IMAGE` / `TAG` | La référence d'image pour `docker compose` / `make up`. La voie d'installation principale est l'image publique `docouno/notarium:latest` ; redéfinissez la coordonnée pour utiliser votre propre registre ou un tag spécifique. | `docouno/notarium:latest` | `IMAGE=docouno/notarium` `TAG=latest` | | `GIT_SHA` / `BUILD_TIME` | Build-args ; intégrés dans `GET /api/about` et l'onglet **Settings → About**. Sans eux — `null`. | vide | `GIT_SHA=$(git rev-parse --short HEAD)` | > [!important] L'image et la construction depuis les sources > `docouno/notarium:latest` est l'image publique et la voie d'installation principale ; `IMAGE` / `TAG` définissent quelle image `docker compose` / `make up` va récupérer. Si l'image n'a pas encore été récupérée depuis le registre — construisez depuis les sources du dépôt principal : `make up` (le comportement est identique). ## Voir aussi - [Configuration de l'auto-hébergement](/docs/self-hosting/configuration/) — installation, volumes, configuration de production. - [Recherche](/docs/concepts/search/) — lexicale, sémantique, fusion hybride et bascule vers la recherche plein texte sans erreur. - [Référence des raccourcis clavier](/docs/reference/keyboard-shortcuts/) — dispositions et préréglages.