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.
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:<DATA_DIR>/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 <DATA_DIR>/spaces par défaut, ne la définissez que si vos notes se trouvent en dehors de la racine des données. | <DATA_DIR>/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 <DATA_DIR>/engine par défaut, définissez-la pour déplacer les index sur un autre disque. | <DATA_DIR>/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 <DATA_DIR>/jobs par défaut, définissez-la pour le déplacer sur un autre disque. | <DATA_DIR>/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 |
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.
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 |
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 et Configuration de la recherche.
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.
| 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) |
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 — installation, volumes, configuration de production.
- Recherche — lexicale, sémantique, fusion hybride et bascule vers la recherche plein texte sans erreur.
- Référence des raccourcis clavier — dispositions et préréglages.