--- title: "Umgebungsvariablen" description: "Die vollständige Tabelle der Umgebungsvariablen einer Instanz: Modus und Port, Spaces und Metadaten-Datenbank, semantische Suche, Docker-Image." --- # 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. ```bash 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:/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 `/spaces` — nur setzen, wenn deine Notizen außerhalb des Datenverzeichnisses liegen. | `/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 `/engine` — setzen, um die Indizes auf eine andere Platte auszulagern. | `/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 `/jobs` — setzen, um es auf eine andere Platte auszulagern. | `/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` | > [!note] Metadaten-Datenbank vs. Dateien > 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](/docs/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` | > [!warning] Zwei unabhängige Schalter > 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](/docs/concepts/search/) und [Suche einrichten](/docs/self-hosting/search-setup/). ## 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](/docs/self-hosting/backup/). | 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)` | > [!important] Das Image und der Bau aus dem Quellcode > `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](/docs/self-hosting/configuration/) — Installation, Volumes, Produktionskonfiguration. - [Suche](/docs/concepts/search/) — lexikalisch, semantisch, hybride Fusion und der Fallback auf die Volltextsuche ohne Fehler. - [Referenz der Tastenkürzel](/docs/reference/keyboard-shortcuts/) — Layouts und Presets.