セルフホスティング (自前の runner プロジェクト)

自前の runner プロジェクトで api イメージを作り、web フロントエンドまで結線して本番デプロイする手順

このページは、公式の full / slim イメージでは要件を満たせない場合に、自前の runner プロジェクトを作って本番デプロイする 運用者向けの手順です。具体的には次のようなケースを想定しています。

公式イメージに同梱されない 独自プラグイン（社内 npm レジストリのものなど）を読み込みたい
ストレージ / 検索 / メール / レンダラのドライバを 任意の組み合わせ で固定したい
イメージの依存を必要最小限に絞り、ビルドパイプラインを自社で管理したい

公開されている full / slim イメージで足りる場合は、公式イメージで動かすだけで十分です。ここではその一歩先、runner プロジェクトを一から作る 場合を扱います。

Crowi の本番構成は「api（Hono）+ web（Next.js）+ MongoDB（+ 任意で Redis / Elasticsearch / S3）」です。@crowi/api は プラグインを同梱しない ため、どのドライバを使うかは runner プロジェクトが所有します。この前提は設定の「プラグインの解決方法」で詳説しています。

全体像

web と api は別コンテナで、いずれもコンテナ内ポート 3000 で待ち受けます。ブラウザにはその前段に置いたリバースプロキシの 1 オリジンだけを見せ、/api・/files とリアルタイムの WebSocket を api へ振り分けます。プロキシの設定例 (Caddy / nginx)、WebSocket の Upgrade 透過、アップロードの body size 上限はデプロイ構成にまとめてあります。本番投入前に必ず読んでください。

runner プロジェクトを作る

プロジェクトディレクトリと `package.json`

任意の場所にディレクトリを作り、@crowi/api と 使いたいプラグイン を依存に宣言します。下記は S3 ストレージ + Elasticsearch 検索 + PlantUML/KaTeX レンダラを使う例です。

package.json

{
  "name": "my-crowi-runner",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "crowi-api"
  },
  "dependencies": {
    "@crowi/api": "2.0.0-alpha.17",
    "@crowi/plugin-storage-aws-s3": "2.0.0-alpha.17",
    "@crowi/plugin-search-elasticsearch": "2.0.0-alpha.17",
    "@crowi/plugin-renderer-plantuml": "2.0.0-alpha.17",
    "@crowi/plugin-renderer-katex": "2.0.0-alpha.17"
  }
}

バージョンは 実際に使う Crowi のリリースに揃えてください。@crowi/api と @crowi/plugin-* は同一バージョンで足並みを揃えるのが安全です（リリースは linked group として同時にバージョンが上がります）。

暗黙のデフォルトプラグイン（@crowi/plugin-storage-local / @crowi/plugin-search-mongo / @crowi/plugin-mail-smtp）は宣言しなくても読み込まれます。ローカルストレージ + MongoDB 検索 + SMTP のままでよければ、 @crowi/api だけを依存にすれば動きます（= slim 相当を自前で組む形）。

`crowi.config.json`

読み込むプラグインと有効ドライバを宣言します。プラグインごとの設定値（バケット名や認証情報など）は ここには書かず、起動後に管理画面（/admin/plugins）から設定します。

crowi.config.json

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

フィールドの意味とドライバ名の対応は crowi.config.json を参照してください。

`.env`

api が起動時に読む環境変数を用意します。最低限 MONGO_URI、本番では CROWI_ENCRYPTION_KEY と WS_TOKEN_SECRET を必ず設定してください。

.env

MONGO_URI=mongodb://mongodb:27017/crowi
REDIS_URL=redis://redis:6379          # 複数レプリカ運用では必須
CROWI_ENCRYPTION_KEY=...               # openssl rand -base64 32
WS_TOKEN_SECRET=...

各変数の意味は環境変数を参照してください。

ローカルで起動確認

依存をインストールし、runner プロジェクトのディレクトリを作業ディレクトリにして 起動します。

pnpm install   # または npm install
pnpm start     # = crowi-api。api がコンテナ内ポート 3000 で待ち受ける

api は起動時にこのプロジェクトの node_modules/ からプラグインを解決します。プラグインの追加・削除に api の再ビルドは不要 です。

api の Docker イメージを作る

runner プロジェクトをそのままイメージ化します。公式イメージと同じく、 WORKDIR を runner プロジェクトのルートにし、 node_modules/@crowi/api/dist/app.js を実行します。

Dockerfile

FROM node:24-bookworm-slim
WORKDIR /app

# runner プロジェクトのマニフェストを先に入れて依存だけ先に解決（キャッシュ効率）
COPY package.json pnpm-lock.yaml* package-lock.json* ./
RUN corepack enable && pnpm install --prod || npm install --omit=dev

# 設定とソースを配置
COPY crowi.config.json ./
# .env はイメージに焼き込まず、コンテナ env / env_file で渡すことを推奨

ENV NODE_ENV=production
ENV PORT=3000
EXPOSE 3000
CMD ["node", "node_modules/@crowi/api/dist/app.js"]

社内レジストリのプラグインを使う場合は、pnpm install の前に .npmrc を COPY してレジストリ / 認証を設定してください。crowi.config.json をコンテナ外からマウントすれば、再ビルドなしでドライバ選択を差し替えられます（公式 compose もこの方式です）。

機密値（CROWI_ENCRYPTION_KEY / WS_TOKEN_SECRET など）は イメージに焼き込まず、デプロイ時のコンテナ環境変数か env_file で渡します。

web フロントエンドを結線する

web は公開されている crowi/crowi-web イメージをそのまま使います。これは 描画専任 の Next サーバで、絶対 API URL を一切焼き込みません。ブラウザは自分のオリジンの相対パス /api・/files を叩き、 WebSocket URL は window.location から導出します。よって 1 つのイメージが任意の api 先で動きますが、それらのパスを api へ振る 前段リバースプロキシが必要 です。

web サーバを直接公開して /api の proxy を任せないでください。web に内蔵の proxy は宛先を ビルド時に焼き込み (CROWI_API_URL を実行時に読まない)、直接公開した web サーバは build 時の既定先に proxy してしまい api に届きません。前段にリバースプロキシを置いてください。

推奨構成は web と api の前段に 同一オリジン + リバースプロキシ を置く形です。プロキシの振り分け(/api・/files、およびリアルタイムの /collab・/presence・ /notifications の WebSocket アップグレード)の Caddy / nginx 最小例と、クロスオリジン・Vercel / PaaS の各バリエーションはデプロイ構成にまとめてあります。本番投入前に必ず読んでください。

デプロイ構成 — リバースプロキシと公開オリジン
設定 — 設定レイヤーとプラグインの解決方法
環境変数 — 変数名・既定値・意味の一覧
crowi.config.json — フィールドとドライバ名の一覧
機密設定の暗号化 — CROWI_ENCRYPTION_KEY のセットアップ
ストレージ設定 — storage.driver の切り替え
検索バックエンドのセットアップ — Elasticsearch の設定
プラグインの導入と設定 — プラグインの追加・有効化
バージョンアップ — 版ごとの入れ替え手順
v1 からの移行 — 既存 Crowi からの移行

セルフホスティング (自前の runner プロジェクト)

全体像

runner プロジェクトを作る

プロジェクトディレクトリと `package.json`

`crowi.config.json`

`.env`

ローカルで起動確認

api の Docker イメージを作る

web フロントエンドを結線する

起動順とヘルスチェック

ミドルウェアを先に起動

マイグレーションを適用

api → web の順で起動

次のステップ

On this page