開発環境をつくる
モノレポを clone して api / web / プラグインをローカルで動かす
このページは Crowi 自体を開発する ための手順です。Crowi をチームで使うために立てるなら 公式イメージで動かす を、まず触ってみるだけなら クイックスタート を参照してください。
動作環境
| ソフトウェア | バージョン | 用途 |
|---|---|---|
| Node.js | 24.x | api / web の実行ランタイム (.nvmrc と engines で固定) |
| pnpm | ルート package.json の packageManager に従う | パッケージマネージャ (モノレポは pnpm workspaces)。corepack enable を一度実行しておけば、使う版はリポジトリ側が決めます |
| Docker / Docker Compose | 最新 | MongoDB / Redis / Elasticsearch / Mailpit をコンテナで起動 |
依存ミドルウェアをホストへ直接インストールする必要はありません。docker compose up -d でまとめて立ち上がります。nvm を使っているなら、リポジトリのルートで nvm use を実行すると .nvmrc の Node.js に切り替わります。
セットアップ
# 1. リポジトリを取得
git clone https://github.com/crowi/crowi.git
cd crowi
# 2. 依存関係をインストール (lefthook の Git フックもここで入ります)
pnpm install
# 3. 開発用ミドルウェアを起動
docker compose up -d
# 4. 環境変数ファイルを用意
cp .env.example .env
# 5. 必須の署名鍵を生成して .env に設定する (api はこれが無いと起動しない)
openssl rand -base64 32
# 出力値を .env の SECRET_TOKEN= に貼り付ける
# 6. api + web + プラグインを起動
pnpm devブラウザで http://localhost:4304 を開くと Crowi の画面が出ます。初回はインストーラ画面なので、管理者ユーザーを作成してください。
:4304 は api と web を前段でまとめる同一オリジンの reverse proxy です (Caddy があれば Caddy、無ければ依存ゼロの node フォールバック)。dev の正式な入口はここだけ で、素の web ポート :4302 を直接開くとリアルタイム共同編集・プレゼンス・通知の WebSocket がつながりません。
SECRET_TOKEN は .env.example では空のままなので、必ず値を設定してから pnpm dev を実行してください。未設定・空白のみ・既知の placeholder のままだと api は起動に失敗します。CROWI_ENCRYPTION_KEY の設定も推奨します — こちらは未設定でも起動しますが、機密設定が平文で保存され、起動時に警告が出ます。
pnpm --filter @crowi/api crypto:gen-keyで 32 バイトの AES-256 鍵を生成し、出力値を .env に貼り付けてください (機密設定の暗号化)。
ポート
割り当ての一覧は ポートと URL にあります。作業ツリーごとに 4 ポートの区画が割り当たるため、複数の作業ツリーを同時に動かしても衝突しません。
開発用ミドルウェア
docker compose up -d (プロファイル指定なし) が起動するのは依存ミドルウェアだけです。アプリ本体はホスト側の pnpm dev で動かします。公開されるホスト側ポートは ポートと URL にあります。
Elasticsearch イメージは日本語形態素解析プラグイン analysis-kuromoji を同梱したカスタムビルドです (検索バックエンドのセットアップ)。Mailpit は送信されたメールをブラウザで確認するための受信箱です。
片側だけ起動する
pnpm dev:api # api + プラグインのみ (Next.js なし)
pnpm dev:web # Next.js フロントエンドのみ
pnpm dev:site # crowi.wiki の LP + ドキュメント (:4303)全スタックを Docker で動かす
api と web もコンテナで動かしたい場合は app プロファイルを使います。
docker compose --profile app up -d --buildこのとき api / web のイメージはモノレポからビルドされ、前段に Caddy が立ちます。入口は http://localhost:4302 です。api イメージはリファレンスの runner プロジェクト apps/crowi-runner からビルドされ、その crowi.config.json を焼き込みます。compose は同じファイルを再マウントするため、ドライバ選択は再ビルドなしで上書きできます。
ビルド・テスト・型チェック
リポジトリルートで実行します。
pnpm build # 全パッケージをビルド
pnpm test # 全パッケージのテスト (api は Jest)
pnpm type-check # api + web + site の型チェック
pnpm lint # Lint (errors=0 が必須)pnpm install 時に lefthook の Git フックが入り、コミット時に Biome のフォーマット、プッシュ時に pnpm lint が自動で走ります。