設定

Crowi 2.0 の設定は、大きく 3 つのレイヤーに分かれています。

1. 環境変数 (.env / プロセス環境) — 接続先や暗号鍵など、起動時に 必要な値。
2. crowi.config.json — どのプラグインを読み込み、どのドライバを 有効にするか。
3. 管理画面の設定 — アプリのタイトルや OAuth、メール、ストレージの 詳細値。MongoDB の Config コレクションに保存されます。

このページでは 1 と 2 を扱います。3 の設定値については 管理画面 を参照してください。

環境変数

API は起動時に、カレントワーキングディレクトリの .env を dotenv で 読み込みます。開発時のそのディレクトリは リポジトリルート です (pnpm dev の api スクリプトが明示的に読み込みます)。本番では ランナープロジェクトのディレクトリ (api が起動する process.cwd()) に なるか、もしくはファイルの代わりに compose / オーケストレータから変数を 注入します。.env.example をコピーして編集してください。

cp .env.example .env

API は起動時にこれらの環境変数をまとめて検証します。PORT / MONGO_URI (またはエイリアス) / REDIS_URL (またはエイリアス) / CROWI_ENCRYPTION_KEY の形式が不正な場合、検出できた問題をすべて含む 1 つのエラーメッセージと ともに起動が即座に失敗します。CLIENT_URL / CROWI_MULTI_INSTANCE / NODE_ENV / JWT_ACCESS_TOKEN_TTL_SECONDS / JWT_REFRESH_TOKEN_TTL_SECONDS / COLLAB_MAX_EDITORS_PER_PAGE / MIGRATION_PREFLIGHT_UNAPPLIED_POLICY などの形式不正は起動を妨げず、起動ログに 1 箇所へまとめて warning として 出力されます(CLIENT_URL が未設定の場合も、送信メール内のリンクが相対 パスになってしまう旨の warning が同じレポートに含まれます)。

WS_TOKEN_SECRET は例外的に、NODE_ENV の値によって重大度が変わる 唯一の変数です — 値が設定されているものの 32 文字未満のとき、 NODE_ENV=production(未設定時のデフォルトも production 扱い)では 起動が失敗し、それ以外(development / test など)では上記と同じ 1 箇所の warning レポートに含まれます。詳細は下表を参照してください。

CROWI_ / WS_TOKEN_ / JWT_ / COLLAB_ / REDIS / MONGO / MIGRATION_ のいずれかの既知プレフィックスを持つものの、既知の変数名の どれとも完全一致しない環境変数は、タイポの疑いとして同じ warning レポートに含まれます。判定にはレーベンシュタイン距離(編集距離)を使い、 既知の変数名のうち最も近いものとの距離が 2 以下であれば「もしかして XXX では?」という形で warning を出します(fail にはなりません — 誤検知 を許容するヒューリスティックです)。PATH / CI / GITHUB_* / npm_* など上記プレフィックスを持たない一般的な OS/CI 環境変数は対象外です。

主要な環境変数

リアルタイム共同編集まわりの変数

リアルタイム共同編集 (RFC-0003) で使う変数です。詳細は リアルタイム共同編集の運用 を参照してください。

Tip: WS_TOKEN_SECRET と CROWI_ENCRYPTION_KEY はどちらも openssl rand -base64 32 で生成できます。CROWI_ENCRYPTION_KEY は pnpm --filter @crowi/api crypto:gen-key でも生成できます。

Docker での環境変数

docker compose --profile app で全スタックを起動する場合、api サービスは .env を env_file として読み込みます。ただし コンテナネットワーク向けの URI (MONGO_URI / REDIS_URL / CLIENT_URL) は docker-compose.yml 側の environment 指定が .env の値を上書きします。機密値 (CROWI_ENCRYPTION_KEY / WS_TOKEN_SECRET など) は .env に書いておけばそのまま渡ります。

Tip: Web アプリ (@crowi/web) はプラグイン依存ゼロの 独立した デプロイ対象 です。api とは HTTP で通信し、どこにでもデプロイできます (Vercel・コンテナ・api と同居など)。一方 api は長寿命の Node サーバ (Mongoose・Redis・組み込みの Hocuspocus WebSocket エンジン・実行時の プラグインロード) であり、Node ランタイムが必須 です — Node ホスト または Node コンテナ (ECS / EKS / Fly / Render / Cloud Run / Cloudflare Containers)。Cloudflare Workers のような edge/isolate 系のサーバレス 基盤では動作しません。

crowi.config.json

crowi.config.json は ランナープロジェクトのルート に置く JSON ファイルです (モノレポでは、リファレンスのランナープロジェクトは apps/crowi-runner なので、その設定は apps/crowi-runner/crowi.config.json にあります)。どのプラグインを 読み込み、どのドライバを有効にするか を宣言します。プラグインごとの 設定値 (S3 のバケット名、OAuth クライアント ID、メール / ストレージの 認証情報など) はここには書かず、MongoDB の Config コレクションに保存し、 管理画面から編集します。

{
  "plugins": [
    "@crowi/plugin-storage-aws-s3",
    "@crowi/plugin-search-elasticsearch",
    "@crowi/plugin-renderer-plantuml",
    "@crowi/plugin-renderer-emoji",
    "@crowi/plugin-renderer-katex"
  ],
  "storage": {
    "driver": "s3"
  },
  "search": {
    "driver": "elasticsearch"
  }
}

フィールド一覧

ファイルが存在しない場合や項目が省略された場合は、上記のデフォルト値が 適用されます。スキーマに合わない内容を書くと、起動時に明示的なエラーで 失敗します。

プラグインの解決方法

@crowi/api は プラグインを同梱しません。SDK (@crowi/plugin-api) と コアのみを出荷し、ドライバは同梱しません。プラグインはランナープロジェクトが 所有します。plugins に挙げた名前は、起動時にランナープロジェクトの node_modules/ から (createRequire(projectDir) で) 解決されます。 プラグインを追加するには、ランナーの package.json に依存として宣言した うえで crowi.config.json:plugins に名前を追加します。api パッケージ自体を 再ビルドする必要はありません。

3 つのプラグインが 暗黙のデフォルトプラグイン として常に読み込まれ、 設定不要で動作します: @crowi/plugin-storage-local、 @crowi/plugin-search-mongo、@crowi/plugin-mail-smtp。そのため、新規 インストールは ローカルストレージ + MongoDB 検索 + SMTP メール が そのまま動きます — 必須のインフラは MongoDB だけです。

ランナープロジェクトは package.json の "start": "crowi-api" スクリプト (@crowi/api が提供する crowi-api bin) で起動します。process.cwd() が projectDir になるよう、プロジェクトディレクトリから実行します。

プラグインが他のプラグインを requires で宣言している場合、その依存先も 自動で (transitive に) 解決・ロード されます。そのため、依存先を plugins に重ねて書く必要はありません。例えば @crowi/plugin-storage-aws-s3 と @crowi/plugin-mail-aws-ses は共通基盤の @crowi/plugin-aws を requires で宣言しているので、plugins には driver プラグインだけ を列挙すれば @crowi/plugin-aws は自動でロードされます。umbrella の @crowi/plugin-aws を明示列挙する必要はありません (重複ロードを避ける)。AWS 一式を使う通し 手順は AWS Lightsail で動かす を参照してください。

プラグインの追加・有効化の詳しい手順は プラグインの管理、 プラグインの種類は プラグインの概要 を参照して ください。

ドライバ名とプラグインの対応

storage.driver / search.driver に指定できるドライバ名は、読み込んだ プラグインが登録したものです。代表的な対応は次のとおりです。

レンダラ系プラグイン (@crowi/plugin-renderer-emoji / -katex / -plantuml / -crowi-legacy) は plugins に追加するだけで 有効になり、storage / search のようなドライバ選択は不要です。

Tip: crowi.config.json でドライバ名を切り替えても、対応する プラグインが plugins に入っていなければ起動時に警告が出ます。ドライバを 切り替えるときは、プラグインの追加とセットで行ってください。

次のステップ

• 機密設定の暗号化 — CROWI_ENCRYPTION_KEY の詳細
• ストレージドライバ — storage.driver の切り替え手順
• 検索のセットアップ — Elasticsearch の設定
• プラグインの管理 — プラグインの追加・有効化