--- title: "環境変数" description: "インスタンスの環境変数の全一覧: モードとポート、スペースとメタデータデータベース、セマンティック検索、Dockerイメージ。" --- # 環境変数 Notariumは環境変数で設定します。デフォルトのままで問題なく動くので、ローカル実行なら何も記入する必要はありません。`.env.example` を `.env` にコピーし、必要な行だけを編集してください。Dockerスタックは `.env` をそのままコンテナに渡すため(値がイメージに焼き込まれることはありません)、同じ1つのファイルがローカルインスタンスと本番インスタンスの両方を記述します。 ```bash cp .env.example .env # デフォルトで動く — 必要なものだけ編集する ``` 以下は全リファレンスです。一部の変数は `.env.example` に直接記載されていますが、それ以外(検索の細かなチューニング)はコード内にデフォルトがあり、`.env.example` には書き出されていません。そうした変数は個別に印を付けています。 ## コア 基本となる変数: ポート、認証モード、そしてメタデータデータベースとスペースの配置場所。 | 変数 | 用途 | デフォルト | 例 | |---|---|---|---| | `DATA_DIR` | データに関する唯一のつまみ。ここを起点に他のすべて — メタデータデータベース、インデックス、ノート、アーティファクト — が導かれます。未設定 → 妥当なデフォルトが使われます。 | `/data`(Docker)、`~/.local/share/notarium`(ホスト) | `DATA_DIR=/srv/notarium` | | `PORT` | バックエンドが待ち受けるポート。単一のFastifyリスナーが `/api`、`/mcp`、そしてSPAの静的アセットを配信します。 | `3000` | `PORT=3000` | | `AUTH_MODE` | 認証モード: `password`(ログインと初回起動時のセットアップ画面。メタデータデータベースが必要)または `none`(デスクトップ/開発/信頼できるイントラネット向けの、すべてにアクセスできる単一プリンシパル。ログインUIなし)。 | `password` | `AUTH_MODE=none` | | `META_DB_URL` | メタデータデータベース: アイデンティティ、リビジョンログ、スペースレジストリ、認証、プロジェクト。デフォルトでは `DATA_DIR` 配下のsqliteなので、`password` モードは設定なしで動きます。任意: メタデータの状態を外部のPostgres(状態の共有、HA)へ移すときだけ設定します。 | `sqlite:/meta.db` | `META_DB_URL=postgres://user:pass@db:5432/notarium` | | `SPACES_ROOT` | 各スペースが1つのフォルダとなるルート。実行時にUIからスペースを作成できるようにします。任意: デフォルトは `/spaces` で、ノートがデータルートの外にある場合だけ設定します。 | `/spaces` | `SPACES_ROOT=/mnt/notes` | | `SPACES_CONFIG` | スペーストポロジーの明示指定: インラインJSONまたはJSONファイルへのパス。単一スペース用の各変数を上書きします。 | 未設定 | `SPACES_CONFIG=/data/spaces.json` | | `ENGINE_DATA_DIR` | エンジンが派生インデックスを保持する場所 — スペースごとに1ファイルです。ファイル名はスペースのフォルダ名に従い、スペースをリネームしても変わりません。ディレクトリを削除 → 起動時に再インデックスが走り、インデックスは復元可能です。任意: デフォルトは `/engine` で、インデックスを別ディスクへ移すときに設定します。 | `/engine` | `ENGINE_DATA_DIR=/mnt/ssd/engine` | | `JOBS_DATA_DIR` | ジョブのディレクトリ: 非同期エクスポートのアーティファクト(派生物であり、TTLで片付けられます)**と**、未完了のインポートでアップロードされたファイル。後者はそのジョブが生きているあいだだけ存在するため、バックアップに含めるべきものです。任意: デフォルトは `/jobs` で、別ディスクへ移すときに設定します。 | `/jobs` | `JOBS_DATA_DIR=/mnt/ssd/jobs` | | `SPACE_IDLE_EVICT_SECONDS` | アイドル状態のスペースの読み取りモデルをメモリからアンロードします。`0` — 温めたまま保持します。ライブのSSE接続があるスペースは決してアンロードされません。 | `0` | `SPACE_IDLE_EVICT_SECONDS=900` | | `SYNC_POLL_SECONDS` | ディスク上の外部変更をポーリングする間隔(各ポーリングはスペース全体の再スキャン)。`0` — ポーリングを無効化します。監視できないマウント(ネットワークボリューム、インメモリ)では、実効間隔は上限60秒に抑えられます。 | `120` | `SYNC_POLL_SECONDS=0` | | `PUBLIC_BASE_URL` | リバースプロキシ背後にあるインスタンスの正規の外部アドレス — MCPコネクタのOAuthメタデータ用。指定しない場合、アドレスはプロキシの転送ヘッダから導かれます。 | 未設定 | `PUBLIC_BASE_URL=https://notes.example.com` | | `TRUST_PROXY` | **直接接続されている**プロキシのIP/CIDRをカンマ区切りで並べたリスト — ログインのレート制限と新しいOAuthクライアントの受け入れに使う、実際のクライアントIPをここから導きます。未設定なら安全なデフォルト、つまり `X-Forwarded-For` はレート制限に影響しません。真偽値、ホップ数、名前付きの範囲、全アドレスの範囲(`/0`)は起動時に拒否されます。 | 未設定 | `TRUST_PROXY=172.18.0.0/16` | > [!note] メタデータデータベースとファイルの違い > ディスク上には別々の2つのものが存在します。`SPACES_ROOT` は**Markdownの真実**(あなたのノート、スペースごとに1フォルダ)です。`META_DB_URL` はメタデータデータベース、つまりファイルからは導けないもの(ユーザー、アクセス権、バージョン履歴)です。詳しくは [セルフホスト](/docs/self-hosting/) セクションを参照してください。 ## 単一スペース(ベアホスト、Dockerなし) `SPACES_CONFIG` も `SPACES_ROOT` も使わずに単一スペースを動かす場合(たとえば Docker を使わない、ホスト上での直接実行)。 | 変数 | 用途 | デフォルト | 例 | |---|---|---|---| | `ENGINE` | 単一スペースのエンジン。値は `notarium` のみで、未設定のままで構いません。 | `notarium` | `ENGINE=notarium` | | `NOTES_DIR` | 単一スペースのノートフォルダへの絶対パス(単一スペースモード)。 | 未設定 | `NOTES_DIR=/home/me/notes` | ## セマンティック検索 全文検索(字句検索、FTS)は設定なしで常に動きます。セマンティック検索(ベクトル検索)とハイブリッド検索は**オプトイン**です。重量級のネイティブスタック(`onnxruntime` + `sqlite-vec`、ディスク上で約660 MB)に加え、bge-m3埋め込みモデル(ディスク上で約600 MB、数百MBのRAM)が必要になります。以下の変数はコード内にデフォルトがあり、`.env.example` には書き出されていません。 | 変数 | 用途 | デフォルト | 例 | |---|---|---|---| | `VECTOR_SEARCH` | `on`/`off` — セマンティックとハイブリッド融合を有効にします。ネイティブスタックが無い場合、`on` はエラーなしで全文検索へフォールバックします。 | `on`(コード)、`off`(公開イメージ) | `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のみのままになります。 | `1024` | `EMBED_DIMENSIONS=384` | | `EMBED_DTYPE` | モデルの量子化: `fp32` / `fp16` / `q8` / `q4`。 | `q8` | `EMBED_DTYPE=fp16` | | `EMBED_THREADS` | バックグラウンドインデックス作成ワーカー1つあたりのONNX intra-opスレッド数(`EMBED_WORKERS` 個のワーカーからなるプール)。 | ワーカーごとに `1`(プール無しのフォールバックはコアの半分) | `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` はbge-m3の消費を約1.9 GBのRAMで一定に保ちます — スワップなしの余裕のないマシンでのOOMに対する備えです(`on` だとアリーナが数GBまで膨らむことがあります)。 | `on` | `EMBED_CPU_MEM_ARENA=off` | | `GRAPH_BOOST` | `on`/`off` — 3つ目のRRFチャネル(リンク上でのグラフブースト、1ホップのウィキリンク)。`VECTOR_SEARCH=off` のときは不活性です。 | `off` | `GRAPH_BOOST=on` | > [!warning] 独立した2つのスイッチ > ローカルでセマンティックを動かすには**両方**が必要です。ネイティブスタックが**インストール済み**であること(`make deps-vector`。デフォルトの `make deps` はインストールせず、公開イメージには常に同梱されています)、**かつ** `VECTOR_SEARCH=on` であること。スタックが無ければ、`on` はエラーなしで全文検索(字句検索)へフォールバックします。詳しくは [検索](/docs/concepts/search/) と [検索のセットアップ](/docs/self-hosting/search-setup/) のセクションを参照してください。 ## バックアップとリストア 組み込みの `backup`、`backup verify`、`restore` コマンドは設定なしで動きます。以下の変数が要るのは、コンテナのルートが読み取り専用でマウントされている場合や、データ量が一般的な規模より明らかに大きい場合だけです。詳しくは [バックアップとリストア](/docs/self-hosting/backup/) を参照してください。 | 変数 | 用途 | デフォルト | 例 | |---|---|---|---| | `NOTARIUM_BACKUP_TMPDIR` | バックアップ、検証、リストアの中間ファイルを置くディレクトリ。コンテナのルートが読み取り専用の場合や `/tmp` の空き容量が足りない場合に設定します: ストリーミングのバックアップは、アーカイブに加えて展開済み2ステージ分の場所を一時的に必要とすることがあります。 | `/tmp` | `NOTARIUM_BACKUP_TMPDIR=/mnt/scratch` | | `NOTARIUM_BACKUP_MAX_BYTES` | サイズの上限 — 圧縮された入力と展開後のペイロードの両方にかかります。zipボム対策であり、引き上げるのは信頼できる大規模なインストールだけです。 | 64 GiB | `NOTARIUM_BACKUP_MAX_BYTES=137438953472` | | `NOTARIUM_BACKUP_MAX_ENTRIES` | アーカイブ内のエントリ数の上限。 | `1000000` | `NOTARIUM_BACKUP_MAX_ENTRIES=2000000` | | `NOTARIUM_BACKUP_MAX_METADATA_BYTES` | 名前、ZIPの内部構造、`manifest.json` に対する個別のメモリ上限。 | 32 MiB | `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` | ビルド引数。`GET /api/about` と **Settings → About** タブにインライン展開されます。指定しない場合は `null` になります。 | 空 | `GIT_SHA=$(git rev-parse --short HEAD)` | > [!important] イメージとソースからのビルド > `docouno/notarium:latest` は公開イメージであり、主なインストール経路です。`IMAGE` / `TAG` は `docker compose` / `make up` がプルするイメージを指定します。イメージがまだレジストリからプルされていない場合は、メインリポジトリでソースからビルドしてください: `make up`(挙動は同一です)。 ## 関連項目 - [セルフホスト設定](/docs/self-hosting/configuration/) — インストール、ボリューム、本番構成。 - [検索](/docs/concepts/search/) — 字句、セマンティック、ハイブリッド融合、そしてエラーなしの全文検索へのフォールバック。 - [キーボードショートカット リファレンス](/docs/reference/keyboard-shortcuts/) — レイアウトとプリセット。