Umgebungsvariablen
Notarium wird über Umgebungsvariablen konfiguriert. Die Standardwerte funktionieren so, wie sie sind — für einen lokalen Start musst du nichts ausfüllen: Kopiere .env.example nach .env und passe nur die Zeilen an, die du wirklich brauchst. Der Docker-Stack reicht .env unverändert in den Container durch (die Werte werden nicht ins Image eingebacken), deshalb beschreibt dieselbe Datei sowohl deine lokale als auch deine Produktionsinstanz.
cp .env.example .env # die Standardwerte funktionieren — ändere nur, was nötig ist
Nachfolgend die vollständige Referenz. Ein Teil der Variablen wird direkt in .env.example gesetzt, ein anderer (die Feinabstimmung der Suche) hat Standardwerte im Code und ist im Beispiel nicht aufgeführt — diese sind gesondert gekennzeichnet.
Kern
Die Grundlagen: Port, Authentifizierungsmodus sowie der Ort von Metadaten-Datenbank und Spaces.
| Variable | Zweck | Standard | Beispiel |
|---|---|---|---|
DATA_DIR | Die einzige Daten-Stellschraube: die Wurzel, aus der alles Übrige abgeleitet wird — Metadaten-Datenbank, Indizes, Notizen, Artefakte. Nicht gesetzt → es greift ein sinnvoller Standard. | /data (Docker); ~/.local/share/notarium (Host) | DATA_DIR=/srv/notarium |
PORT | Der Port, auf dem das Backend lauscht; ein einziger Fastify-Listener bedient /api, /mcp und die statischen Assets der SPA. | 3000 | PORT=3000 |
AUTH_MODE | Authentifizierungsmodus: password (Login plus Setup-Bildschirm beim ersten Start, erfordert die Metadaten-Datenbank) oder none (ein einzelner All-Access-Principal für Desktop/Dev/vertrauenswürdiges Intranet, ohne Login-UI). | password | AUTH_MODE=none |
META_DB_URL | Die Metadaten-Datenbank: Identität, Revisionsprotokoll, Space-Registry, Authentifizierung, Projekte. Standardmäßig SQLite unter DATA_DIR, deshalb funktioniert der password-Modus ohne Einrichtung. Optional: nur setzen, um den Metadaten-Zustand in ein externes Postgres zu verlagern (gemeinsamer Zustand, HA). | sqlite:<DATA_DIR>/meta.db | META_DB_URL=postgres://user:pass@db:5432/notarium |
SPACES_ROOT | Die Wurzel, in der jeder Space ein Ordner ist; ermöglicht das Anlegen von Spaces aus der Oberfläche zur Laufzeit. Optional: standardmäßig <DATA_DIR>/spaces — nur setzen, wenn deine Notizen außerhalb des Datenverzeichnisses liegen. | <DATA_DIR>/spaces | SPACES_ROOT=/mnt/notes |
SPACES_CONFIG | Explizite Space-Topologie: Inline-JSON oder ein Pfad zu einer JSON-Datei. Überschreibt die Single-Space-Variablen. | nicht gesetzt | SPACES_CONFIG=/data/spaces.json |
ENGINE_DATA_DIR | Wo die Engine die abgeleiteten Indizes ablegt — eine Datei pro Space. Der Dateiname folgt dem Ordnernamen des Spaces und ändert sich beim Umbenennen des Spaces nicht. Verzeichnis gelöscht → Reindizierung beim Start; der Index ist wiederherstellbar. Optional: standardmäßig <DATA_DIR>/engine — setzen, um die Indizes auf eine andere Platte auszulagern. | <DATA_DIR>/engine | ENGINE_DATA_DIR=/mnt/ssd/engine |
JOBS_DATA_DIR | Das Job-Verzeichnis: Artefakte asynchroner Exporte (abgeleitet, werden per TTL bereinigt) und die hochgeladenen Dateien eines unfertigen Imports — diese leben genau so lange wie ihr Job und gehören deshalb ins Backup. Optional: standardmäßig <DATA_DIR>/jobs — setzen, um es auf eine andere Platte auszulagern. | <DATA_DIR>/jobs | JOBS_DATA_DIR=/mnt/ssd/jobs |
SPACE_IDLE_EVICT_SECONDS | Das Read-Model eines inaktiven Spaces aus dem Speicher räumen. 0 — warm halten; Spaces mit einer aktiven SSE-Verbindung werden nie geräumt. | 0 | SPACE_IDLE_EVICT_SECONDS=900 |
SYNC_POLL_SECONDS | Das Abfrageintervall für externe Änderungen auf der Platte (jede Abfrage ist ein vollständiger Rescan des Spaces). 0 — Abfrage abschalten. Für nicht überwachbare Mounts (Netzwerk-Volume, In-Memory) ist das effektive Intervall nach oben auf 60 s begrenzt. | 120 | SYNC_POLL_SECONDS=0 |
PUBLIC_BASE_URL | Die kanonische externe Adresse der Instanz hinter einem Reverse-Proxy — für die OAuth-Metadaten der MCP-Connectors. Ohne sie wird die Adresse aus den Forwarded-Headern des Proxys abgeleitet. | nicht gesetzt | PUBLIC_BASE_URL=https://notes.example.com |
TRUST_PROXY | Eine kommagetrennte Liste der IPs/CIDRs der unmittelbar vorgelagerten Proxys — daraus wird die echte Client-IP für Login-Rate-Limits und für die Zulassung neuer OAuth-Clients abgeleitet. Nicht gesetzt heißt: sicherer Standard, X-Forwarded-For wirkt sich nicht auf die Limits aus. Boolesche Werte, Hop-Zähler, benannte Bereiche und Bereiche über alle Adressen (/0) werden beim Start abgelehnt. | nicht gesetzt | TRUST_PROXY=172.18.0.0/16 |
Auf der Platte liegen zwei verschiedene Dinge. SPACES_ROOT ist die Markdown-Wahrheit (deine Notizen, ein Ordner pro Space). META_DB_URL ist die Metadaten-Datenbank: das, was sich nicht aus den Dateien ableiten lässt (Benutzer, Zugriffe, Versionsverlauf). Mehr im Abschnitt Self-Hosting.
Single-Space (Bare-Host, ohne Docker)
Für den Betrieb eines einzelnen Spaces ohne SPACES_CONFIG und ohne SPACES_ROOT (zum Beispiel ein lokaler Bare-Run ohne Docker).
| Variable | Zweck | Standard | Beispiel |
|---|---|---|---|
ENGINE | Die Engine eines einzelnen Spaces. Der einzige Wert ist notarium; du kannst die Variable weglassen. | notarium | ENGINE=notarium |
NOTES_DIR | Absoluter Pfad zum Notizordner eines einzelnen Spaces (Single-Space-Modus). | nicht gesetzt | NOTES_DIR=/home/me/notes |
Semantische Suche
Die lexikalische Volltextsuche (FTS) funktioniert immer und ohne Konfiguration. Semantische (Vektor-) und hybride Suche musst du ausdrücklich aktivieren: ein schwerer nativer Stack (onnxruntime + sqlite-vec, ~660 MB auf der Platte) plus das Embedding-Modell bge-m3 (~600 MB auf der Platte, Hunderte MB RAM). Die Variablen unten haben Standardwerte im Code und sind in .env.example nicht aufgeführt.
| Variable | Zweck | Standard | Beispiel |
|---|---|---|---|
VECTOR_SEARCH | on/off — schaltet Semantik und hybride Fusion ein. Fehlt der native Stack, fällt on auf die Volltextsuche zurück — ohne Fehler. | on (Code), off (veröffentlichtes Image) | VECTOR_SEARCH=on |
EMBED_MODEL | Die ID des Embedding-Modells (transformers.js/ONNX). Zusammen mit EMBED_DIMENSIONS setzen. | Xenova/bge-m3 | EMBED_MODEL=Xenova/multilingual-e5-small |
EMBED_DIMENSIONS | Die Vektorbreite; sie muss zum Modell passen (bge-m3 — 1024, e5-small — 384). Eine Abweichung ist fail-closed: Die Notiz bleibt FTS-only. | 1024 | EMBED_DIMENSIONS=384 |
EMBED_DTYPE | Quantisierung des Modells: fp32 / fp16 / q8 / q4. | q8 | EMBED_DTYPE=fp16 |
EMBED_THREADS | Die Anzahl der ONNX-Intra-op-Threads pro Worker der Hintergrundindizierung (ein Pool aus EMBED_WORKERS Workern). | 1 pro Worker (Fallback ohne Pool — die Hälfte der Kerne) | EMBED_THREADS=2 |
EMBED_WORKERS | Die Größe des worker_threads-Pools für Embeddings = Parallelität der Hintergrundindizierung über die Kerne. Jeder Worker hält seine eigene Kopie des Modells (das schlägt auf den RAM durch). | max(1, min(Kerne−2, 4)) | EMBED_WORKERS=8 |
EMBED_QUERY_PREFIX / EMBED_PASSAGE_PREFIX | Präfixe für asymmetrische Modelle (e5). Für das symmetrische bge-m3 nicht setzen — sonst sinkt die Qualität, ohne dass du es merkst. | nicht gesetzt | EMBED_QUERY_PREFIX="query: " |
EMBED_CPU_MEM_ARENA | on/off. off hält den Verbrauch konstant bei ~1,9 GB RAM für bge-m3 — ein Schutz gegen OOM auf einer knappen Maschine ohne Swap (mit on kann die Arena auf mehrere GB anwachsen). | on | EMBED_CPU_MEM_ARENA=off |
GRAPH_BOOST | on/off — ein dritter RRF-Kanal (ein Graph-Boost über Links, 1-Hop-Wiki-Link). Wirkungslos, wenn VECTOR_SEARCH=off. | off | GRAPH_BOOST=on |
Damit die Semantik lokal funktioniert, brauchst du beides: den nativen Stack installiert (make deps-vector; das standardmäßige make deps installiert ihn nicht, das veröffentlichte Image bringt ihn immer mit) und VECTOR_SEARCH=on. Fehlt der Stack, fällt on auf die lexikalische Volltextsuche zurück — ohne Fehler. Mehr in den Abschnitten Suche und Suche einrichten.
Backup und Wiederherstellung
Die eingebauten Befehle backup, backup verify und restore funktionieren ohne Konfiguration. Die Variablen unten brauchst du nur, wenn die Container-Wurzel schreibgeschützt eingehängt ist oder deine Datenmenge deutlich über dem Üblichen liegt. Mehr unter Backup und Wiederherstellung.
| Variable | Zweck | Standard | Beispiel |
|---|---|---|---|
NOTARIUM_BACKUP_TMPDIR | Das Verzeichnis für die Zwischendateien von Backup, Verifizierung und Wiederherstellung. Setz es, wenn die Container-Wurzel read-only ist oder unter /tmp der Platz knapp wird: Ein Streaming-Backup kann zeitweise Raum für das Archiv plus zwei entpackte Stages brauchen. | /tmp | NOTARIUM_BACKUP_TMPDIR=/mnt/scratch |
NOTARIUM_BACKUP_MAX_BYTES | Die Größenobergrenze — sowohl für die komprimierte Eingabe als auch für die entpackten Nutzdaten. Ein Schutz gegen Zip-Bomben; nur große, vertrauenswürdige Installationen heben sie an. | 64 GiB | NOTARIUM_BACKUP_MAX_BYTES=137438953472 |
NOTARIUM_BACKUP_MAX_ENTRIES | Die Obergrenze für die Anzahl der Einträge im Archiv. | 1000000 | NOTARIUM_BACKUP_MAX_ENTRIES=2000000 |
NOTARIUM_BACKUP_MAX_METADATA_BYTES | Eine gesonderte Speicherobergrenze für Namen, die internen Strukturen des ZIP und manifest.json. | 32 MiB | NOTARIUM_BACKUP_MAX_METADATA_BYTES=67108864 |
Docker und Build
| Variable | Zweck | Standard | Beispiel |
|---|---|---|---|
IMAGE / TAG | Die Image-Referenz für docker compose / make up. Der Haupt-Installationspfad ist das öffentliche Image docouno/notarium:latest; überschreib die Koordinate, um deine eigene Registry oder einen bestimmten Image-Tag zu verwenden. | docouno/notarium:latest | IMAGE=docouno/notarium TAG=latest |
GIT_SHA / BUILD_TIME | Build-Args; werden in GET /api/about und den Tab Settings → About eingebettet. Ohne sie — null. | leer | GIT_SHA=$(git rev-parse --short HEAD) |
docouno/notarium:latest ist das öffentliche Image und der Haupt-Installationspfad; IMAGE / TAG legen fest, welches Image docker compose / make up zieht. Wenn das Image noch nicht aus der Registry gezogen wurde — bau es aus dem Quellcode des Hauptrepositorys: make up (das Verhalten ist identisch).
Siehe auch
- Self-Hosting-Konfiguration — Installation, Volumes, Produktionskonfiguration.
- Suche — lexikalisch, semantisch, hybride Fusion und der Fallback auf die Volltextsuche ohne Fehler.
- Referenz der Tastenkürzel — Layouts und Presets.