Переменные окружения
Notarium конфигурируется через переменные окружения. Дефолты рабочие — для локального запуска заполнять ничего не нужно: скопируйте .env.example в .env, при необходимости поправьте нужные строки. Docker-стек прокидывает .env в контейнер как есть (в образ значения не запекаются), поэтому один и тот же файл описывает и локальный, и продакшн-инстанс.
cp .env.example .env # дефолты рабочие — правьте только то, что нужно
Ниже — полная справка. Часть переменных задаётся напрямую в .env.example, часть (тонкая настройка поиска) имеет дефолты в коде и в примере не выписана — они помечены отдельно.
Ядро
Базовые переменные: порт, режим аутентификации, расположение служебной БД и пространств.
| Переменная | Назначение | Дефолт | Пример |
|---|---|---|---|
DATA_DIR | Единственная ручка данных: корень, из которого выводится всё остальное — служебная БД, индексы, заметки, артефакты. Не задан → берётся рабочий дефолт. | /data (Docker); ~/.local/share/notarium (host) | DATA_DIR=/srv/notarium |
PORT | Порт, который слушает бэкенд; один Fastify-листенер отдаёт /api, /mcp и статику SPA. | 3000 | PORT=3000 |
AUTH_MODE | Режим аутентификации: password (логин + setup-экран первого запуска, требует служебную БД) или none (единственный all-access принципал для desktop/dev/доверенного интранета, без login-UI). | password | AUTH_MODE=none |
META_DB_URL | Служебная БД: идентичность, журнал ревизий, реестр пространств, аутентификация, проекты. По дефолту — sqlite под DATA_DIR, поэтому режим password работает без настройки. Опционально: задавайте, только чтобы перенести служебное состояние во внешний Postgres (общее состояние, HA). | sqlite:<DATA_DIR>/meta.db | META_DB_URL=postgres://user:pass@db:5432/notarium |
SPACES_ROOT | Корень, где каждое пространство — это папка; включает создание пространств из UI в рантайме. Опционально: по дефолту это <DATA_DIR>/spaces, задавайте, только если заметки лежат вне корня данных. | <DATA_DIR>/spaces | SPACES_ROOT=/mnt/notes |
SPACES_CONFIG | Явная топология пространств: inline-JSON или путь к JSON-файлу. Перекрывает single-space-переменные. | не задан | SPACES_CONFIG=/data/spaces.json |
ENGINE_DATA_DIR | Где движок держит производные индексы — по файлу на пространство. Имя файла следует за именем папки пространства и при переименовании пространства не меняется. Удаление каталога → реиндекс при старте, индекс восстановим. Опционально: по дефолту <DATA_DIR>/engine, задавайте, чтобы вынести индексы на другой диск. | <DATA_DIR>/engine | ENGINE_DATA_DIR=/mnt/ssd/engine |
JOBS_DATA_DIR | Каталог задач: артефакты async-экспорта (производное, чистится по TTL) и загруженные файлы незавершённого импорта — эти живут ровно столько, сколько живёт их задача, и потому попадают в бэкап. Опционально: по дефолту <DATA_DIR>/jobs, задавайте, чтобы вынести на другой диск. | <DATA_DIR>/jobs | JOBS_DATA_DIR=/mnt/ssd/jobs |
SPACE_IDLE_EVICT_SECONDS | Выгрузка read-model простаивающего пространства. 0 — держать тёплым; пространства с живым SSE-соединением не выгружаются. | 0 | SPACE_IDLE_EVICT_SECONDS=900 |
SYNC_POLL_SECONDS | Период опроса внешних изменений на диске (каждый опрос — полный рескан пространства). 0 — отключить опрос. Для неотслеживаемых mount'ов (сетевой том, in-memory) эффективный интервал сверху ограничен 60 с. | 120 | SYNC_POLL_SECONDS=0 |
PUBLIC_BASE_URL | Канонический внешний адрес инстанса за reverse proxy — для OAuth-метаданных MCP-коннекторов. Без него адрес выводится из forwarded-заголовков прокси. | не задан | PUBLIC_BASE_URL=https://notes.example.com |
TRUST_PROXY | Список IP/CIDR непосредственных прокси через запятую — по нему выводится настоящий IP клиента для лимитов входа и допуска новых OAuth-клиентов. Не задан — безопасный дефолт: X-Forwarded-For на лимиты не влияет. Булевы значения, счётчики хопов, именованные диапазоны и всеадресные диапазоны (/0) отклоняются при старте. | не задан | TRUST_PROXY=172.18.0.0/16 |
На диске лежат две разные вещи. SPACES_ROOT — это Markdown-истина (ваши заметки, по папке на пространство). META_DB_URL — служебная БД: то, что из файлов не выводится (пользователи, доступы, история версий). Подробнее — в разделе Self-host.
Single-space (bare-host, без Docker)
Для запуска одного пространства без SPACES_CONFIG и без SPACES_ROOT (например, локальный bare-run без Docker).
| Переменная | Назначение | Дефолт | Пример |
|---|---|---|---|
ENGINE | Движок одного пространства. Единственное значение — notarium; можно не задавать. | notarium | ENGINE=notarium |
NOTES_DIR | Абсолютный путь к папке заметок одного пространства (single-space режим). | не задан | NOTES_DIR=/home/me/notes |
Семантический поиск
Лексический полнотекстовый поиск (FTS) работает всегда и без настройки. Семантический (векторный) и гибридный поиск — включается по желанию: тяжёлый нативный стек (onnxruntime + sqlite-vec, ~660 МБ на диске) плюс модель эмбеддингов bge-m3 (~600 МБ на диске, сотни МБ RAM). Переменные ниже имеют дефолты в коде и в .env.example не выписаны.
| Переменная | Назначение | Дефолт | Пример |
|---|---|---|---|
VECTOR_SEARCH | on/off — включает семантику и гибридное слияние. При отсутствии нативного стека on откатывается на полнотекстовый поиск — без ошибки. | on (код), off (published-образ) | VECTOR_SEARCH=on |
EMBED_MODEL | Id модели эмбеддингов (transformers.js/ONNX). Задаётся вместе с EMBED_DIMENSIONS. | Xenova/bge-m3 | EMBED_MODEL=Xenova/multilingual-e5-small |
EMBED_DIMENSIONS | Ширина вектора; обязана совпадать с моделью (bge-m3 — 1024, e5-small — 384). Несовпадение fail-closed: заметка остаётся FTS-only. | 1024 | EMBED_DIMENSIONS=384 |
EMBED_DTYPE | Квантизация модели: fp32 / fp16 / q8 / q4. | q8 | EMBED_DTYPE=fp16 |
EMBED_THREADS | Число ONNX intra-op потоков на воркер фонового индексирования (пул из EMBED_WORKERS воркеров). | 1 на воркер (fallback без пула — половина ядер) | EMBED_THREADS=2 |
EMBED_WORKERS | Размер пула worker_threads эмбеддинга = параллелизм фонового индексирования по ядрам. Каждый воркер держит свою копию модели (влияет на RAM). | max(1, min(ядра−2, 4)) | EMBED_WORKERS=8 |
EMBED_QUERY_PREFIX / EMBED_PASSAGE_PREFIX | Префиксы для асимметричных моделей (e5). Для симметричной bge-m3 не задавать — иначе качество незаметно просядет. | не заданы | EMBED_QUERY_PREFIX="query: " |
EMBED_CPU_MEM_ARENA | on/off. off удерживает потребление на постоянном уровне ~1.9 ГБ RAM для bge-m3 — против OOM на тесной swapless-машине (с on арена может доползти до нескольких ГБ). | on | EMBED_CPU_MEM_ARENA=off |
GRAPH_BOOST | on/off — третий RRF-канал (буст по связям, 1-hop wikilink). Инертен при VECTOR_SEARCH=off. | off | GRAPH_BOOST=on |
Чтобы семантика заработала локально, нужны оба: нативный стек установлен (make deps-vector; дефолтный make deps его не ставит, published-образ несёт всегда) и VECTOR_SEARCH=on. Если стека нет — on откатывается на лексический полнотекстовый поиск, без ошибки. Подробнее — в разделе Поиск и Настройка поиска.
Бэкап и восстановление
Встроенные команды backup, backup verify и restore работают без настройки. Переменные ниже нужны, только когда корень контейнера смонтирован на чтение или данных заметно больше типового. Подробнее — Бэкап и восстановление.
| Переменная | Назначение | Дефолт | Пример |
|---|---|---|---|
NOTARIUM_BACKUP_TMPDIR | Каталог под промежуточные файлы бэкапа, проверки и восстановления. Задавайте, если корень контейнера read-only или под /tmp не хватает места: потоковому бэкапу может временно понадобиться архив плюс два развёрнутых стейджа. | /tmp | NOTARIUM_BACKUP_TMPDIR=/mnt/scratch |
NOTARIUM_BACKUP_MAX_BYTES | Потолок объёма — и сжатого входа, и развёрнутой полезной нагрузки. Защита от zip-бомбы; поднимают только доверенные крупные инсталляции. | 64 ГиБ | NOTARIUM_BACKUP_MAX_BYTES=137438953472 |
NOTARIUM_BACKUP_MAX_ENTRIES | Потолок числа записей в архиве. | 1000000 | NOTARIUM_BACKUP_MAX_ENTRIES=2000000 |
NOTARIUM_BACKUP_MAX_METADATA_BYTES | Отдельный потолок памяти под имена, служебные структуры ZIP и manifest.json. | 32 МиБ | NOTARIUM_BACKUP_MAX_METADATA_BYTES=67108864 |
Docker и сборка
| Переменная | Назначение | Дефолт | Пример |
|---|---|---|---|
IMAGE / TAG | Ссылка на образ для docker compose / make up. Основной путь установки — публичный образ docouno/notarium:latest; переопределите координату, чтобы взять свой реестр или конкретный тег. | docouno/notarium:latest | IMAGE=docouno/notarium TAG=latest |
GIT_SHA / BUILD_TIME | Build-args сборки; инлайнятся в GET /api/about и вкладку Settings → About. Без них — null. | пусто | GIT_SHA=$(git rev-parse --short HEAD) |
docouno/notarium:latest — публичный образ и основной путь установки; IMAGE / TAG задают, какой образ подтянет docker compose / make up. Если образ ещё не подтянулся из реестра — соберите из исходников основного репозитория: make up (поведение идентично).
Смотрите также
- Конфигурация self-host — установка, тома, продакшн-конфигурация.
- Поиск — лексика, семантика, гибридное слияние и откат на полнотекстовый поиск без ошибки.
- Справочник горячих клавиш — раскладки и пресеты.