セルフホスティング（カスタムランナープロジェクト）

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

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

公式イメージ（モノレポ同梱の apps/crowi-runner / apps/crowi-runner-slim から ビルドするもの）で足りる場合は、インストール の「公式 Docker イメージのビルド」で十分です。ここではその一歩先、ランナープロジェクトを一から 作る 場合を扱います。

全体像

単一ドメイン + リバースプロキシ構成（推奨）の場合、リクエストは次のように 振り分けます。

                         ┌──────────────────────────────┐
  ブラウザ ──HTTPS──▶ リバースプロキシ (nginx / Caddy 等)
                         │  /            → web  :3000     │
                         │  /api/*       → api  :3000     │
                         │  /collab/*    → api  :3000 (WS) │
                         └──────────────────────────────┘
                                   │            │
                              ┌────▼───┐   ┌────▼───┐
                              │  web   │   │  api   │──▶ MongoDB / Redis / ...
                              └────────┘   └────────┘

web と api は別コンテナで、いずれもコンテナ内ポート 3000 で待ち受けます。 /collab/* は WebSocket なので、プロキシ側で Upgrade ヘッダの引き渡し を 有効にしてください。

ランナープロジェクトを作る

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

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

MONGO_URI=mongodb://mongodb:27017/crowi
REDIS_URL=redis://redis:6379          # 複数レプリカ運用では必須
CROWI_ENCRYPTION_KEY=...               # openssl rand -base64 32
WS_TOKEN_SECRET=...                    # 全 api レプリカで同一値にする

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

api の Docker イメージを作る

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

FROM node:24-bookworm-slim
WORKDIR /app

# ランナープロジェクトのマニフェストを先に入れて依存だけ先に解決（キャッシュ効率）
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"]

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

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

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

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

起動順とヘルスチェック

次のステップ

• 設定 — 環境変数と crowi.config.json の全体像
• 機密設定の暗号化 — CROWI_ENCRYPTION_KEY のセットアップ
• ストレージドライバ — storage.driver の切り替え
• 検索のセットアップ — Elasticsearch の設定
• プラグインの管理 — プラグインの追加・有効化
• v1 からのアップグレード — 既存 Crowi からの移行