DifyをローカルDockerでセルフホスト：7ステップで構築と対処法

### 主題と目的 本調査は「Dify をローカルの Docker（Docker Compose）でセルフホストする手順」を、初心者にも分かりやすく整理・解説することを目的としています。フォーカスは以下です。 - 必要な前提ソフト・リソース（Docker / Docker Compose のバージョン、推奨メモリ等）を明確にする - 実際の手順（リポジトリ取得 → .env 準備 → docker compose 起動 → ブラウザで初期セットアップ）をコマンド付きで示す - よくあるつまずき（ポート競合、.env の設定ミス、ベクタDB のリソース問題、CORS、ファイルアップロード制限等）と対処法を提示する - 運用（バックアップ・アップデート・ベクタDB／ローカルLLM 連携）の注意点をまとめる 出典の主な参考は Dify 公式ドキュメントやコミュニティのハンズオン記事（Qiita、yanai-ke、Milvus チュートリアル 等）です（例: https://docs.dify.ai/en/getting-started/install-self-hosted/docker-compose、https://qiita.com/Misshii/items/b23adc1612019568149c、https://yanai-ke.com/dify001/、https://milvus.io/blog/hands-on-tutorial-build-rag-power-document-assistant-in-10-minutes-with-dify-and-milvus.md）。 --- ### 回答 以下は「やさしい手順書＋実務的注意点」です。まずは最小構成で動かして挙動を確認し、その後拡張（Weaviate/Milvus、ローカルLLM、S3 など）する流れを推奨します。 1. 事前準備（確認すべきこと） - 必須ソフト： - Docker（推奨: 19.03 以降）および Docker Compose（推奨: 1.28 以降）。公式手順に従います（参考: https://docs.dify.ai/en/getting-started/install-self-hosted/docker-compose）。 - Git（クローンする場合）。または GitHub の「Download ZIP」を使って取得可能。 - ホストリソース（目安）： - 最低: CPU 2コア、RAM 4 GiB（ただし macOS の Docker VM は 8 GiB 割当を推奨する記事あり）。Weaviate やローカルLLMを追加するとメモリ/CPU 要件は上がります。 - OS 特有の注意： - Windows では Docker Desktop + WSL2、もしくは権限制約がある場合は Rancher Desktop が回避策（参考: https://yanai-ke.com/dify001/）。 2. リポジトリ取得とディレクトリ移動 - Git を使える場合（推奨）: - git clone https://github.com/langgenius/dify.git - cd dify - ZIP でダウンロードした場合は展開して dify フォルダへ移動（GitHub ボタンの「Download ZIP」を利用可）。 3. .env の作成と主要設定（必須） - docker ディレクトリへ移動して .env を作成: - macOS / Linux: - cd dify/docker - cp .env.example .env - Windows (PowerShell): - cd dify\docker - copy .env.example .env - 特に確認・編集すべき変数（チェックリスト）: - SECRET_KEY（セッション／暗号用） - DB 関連（Postgres のユーザー名、パスワード、DB 名） - REDIS 接続情報 - VECTOR_STORE（Weaviate 等を使うか）およびその接続先（例: MILVUS_URI／Weaviate のエンドポイント）※Milvus 使用時は host.docker.internal を使う事例あり（参考: Milvus チュートリアル） - ストレージ（ローカル or S3/minio） - CONSOLE_API_URL / APP_WEB_URL（フロント ⇄ API の URL、CORS やログインに影響） - UPLOAD_FILE_SIZE_LIMIT（アップロード上限。413 エラー対策） - 注意点：.env.example と差分を必ず確認し、.env のバックアップをとること（アップデート時のトラブル回避）。 4. Docker Compose で起動（最短コマンド） - 起動: - docker compose up -d - 動作確認: - docker compose ps - docker ps - ログ確認: - docker compose logs -f <service> - 主要コンテナ（例）: - api / web / worker / db (Postgres) / redis / weaviate (または milvus/qdrant 等) / nginx / ssrf_proxy / sandbox - サービスとよく使われるポート（代表例） | サービス | 役割 | 代表ポート（.env/docker-composeで異なる場合あり） | |---:|---|---| | web | フロントエンドUI | 3000 等 | | api | バックエンド API | 端末による（docker-compose参照） | | db | Postgres（永続化） | - | | redis | キャッシュ / キュー | - | | weaviate/milvus | ベクトルDB（RAG用） | - | - ブラウザアクセス: - 多くの事例では http://localhost:3000 または http://localhost/install を開いて初期管理者アカウントを作成します（docker-compose のポート設定を確認してください）。 5. 初回セットアップとモデル接続 - ブラウザで初期管理者アカウントを作成 → Settings 等からモデルプロバイダ（OpenAI 等）の API キーを登録可能（UI 操作）。 - ローカルLLM を使う場合は、外部の OpenAI 互換 API（LMStudio や ollama を経由）を用意し、そのエンドポイントを .env または UI 側で設定する運用が多い（参考: Zenn の実践メモ）。 6. よくあるトラブルと対処（即効チェックリスト） - コンテナがすぐ落ちる／立ち上がらない: - docker compose logs -f <service> を確認。多くは .env の接続情報ミスやリソース不足が原因（参考: https://yanai-ke.com/dify001/）。 - ポート競合でブラウザに何も出ない: - .env と docker-compose.yaml のポートマッピングを確認し、必要なら変更。 - 管理者パスワードを忘れた: - docker compose exec -it api flask reset-password（コンテナ名は環境により異なる）で再設定可能（参考: legacy FAQ / Qiita）。 - 秘密鍵紛失によるエラー: - flask reset-encrypt-key-pair で再生成。ただし元の鍵は復元不可（注意）。 - 413 Request Entity Too Large（アップロードエラー）: - .env の UPLOAD_FILE_SIZE_LIMIT を上げ、さらに Nginx 側の client_max_body_size を同等以上に設定してから再起動（docker compose down → up -d）。 - 502 Bad Gateway: - nginx の設定やコンテナ間のネットワーク（IP / ホスト名参照）を確認。docker inspect でコンテナ情報をチェック。 - CORS エラー（ブラウザの「許可されていません」）: - フロントと API のオリジンを合わせるか、リバースプロキシ（Nginx）で Access-Control-Allow-* ヘッダを付与するのが現実的な対応（Dify 固有の CORS 設定記載は見つからず、プロキシでの制御が推奨されている）。 7. バックアップとアップデート（運用のキモ） - 常時実施すべき： - Postgres のダンプ（アプリの重要データ）を定期的に取得。 - Docker ボリューム（特に DB / Weaviate の永続化領域）のバックアップ（tar 化等）を保存。 - dify/docker/.env のバックアップ（.env.example と差分を確認してから更新）。 - アップデート手順（推奨フロー）： 1. フルバックアップ（DB ダンプ + ボリューム + .env） 2. git pull で最新を取得 3. .env.example と自分の .env を比較して差分を反映 4. docker compose down → docker compose up -d → 動作確認（/install 等） （参考: https://yanai-ke.com/dify001/） 8. ベクタDB / ローカルLLM 連携の実務的注意 - ベクタDB（Weaviate / Milvus 等）: - ローカルに置くとメモリ・I/O 負荷が高まる。小規模検証なら良いが、本格運用なら外部ベクタDBに分離する設計を検討（参考: Milvus チュートリアル、Zenn ノート）。 - Weaviate 等は永続化・スナップショットの運用設計が必要。 - ローカルLLM（LMStudio / ollama 等）: - 接続は OpenAI 互換 API を経由することが多く、Dify 側は外部プロバイダとして扱う。 - トークン長やコンテキスト制約に注意。長文は事前にチャンク化・要約してからモデルに投げる設計が安全（参考: Zenn）。 - GPU メモリの不足や量子化設定による挙動差があるため、別ノードに切り出すアーキテクチャが安定化に有効。 9. 便利な監視・デバッグコマンド（まとめ） - コンテナ確認: docker compose ps / docker ps - ログ: docker compose logs -f <service> - 再起動: docker compose down && docker compose up -d - パスワード再作成: docker compose exec -it api flask reset-password - 鍵再生成（注意）: flask reset-encrypt-key-pair 10. 手順の俯瞰（簡易フロー） ```mermaid flowchart LR A["準備: Docker/Git/端末"] --> B["リポジトリ取得 (git clone or ZIP)"] B --> C["dify/docker に移動して cp .env.example .env"] C --> D["docker compose up -d で起動"] D --> E["ブラウザで初期セットアップ (localhost:3000 or /install)"] E --> F["動作確認・ログ確認"] F --> G["運用: バックアップ・.env 差分管理・バージョンアップ"] ``` 補足・参考リンク（調査で参照した資料） - Dify 公式ドキュメント（Docker Compose デプロイ）: https://docs.dify.ai/en/getting-started/install-self-hosted/docker-compose - Qiita ハンズオン: https://qiita.com/Misshii/items/b23adc1612019568149c - Windows / 運用メモ: https://yanai-ke.com/dify001/ - Milvus チュートリアル（Dify と Milvus の連携例）: https://milvus.io/blog/hands-on-tutorial-build-rag-power-document-assistant-in-10-minutes-with-dify-and-milvus.md - docker-compose サンプル（リポジトリ内）: https://github.com/langgenius/dify/blob/main/docker/docker-compose.yaml - その他：USAVPS の導入例、Zenn のローカルLLM 実践メモ等（参照: 調査結果内の参照先） --- ### 結果と結論 主な結果（要点まとめ）： - Dify のローカルセルフホストは「準備 → リポジトリ取得 → .env 編集 → docker compose 起動 → ブラウザで初期セットアップ」の流れで比較的短時間に開始できます（公式ドキュメントに準拠）。ただし、Weaviate や Milvus、ローカルLLM を追加するとリソース要件（特にメモリ／I/O）が急増します。 - 最も多い失敗原因は .env の設定ミス（DB/Redis/ポート/ベクタDB 設定）とホストのリソース不足です。ログを見て因果を辿る習慣（docker compose logs 等）が最短の問題解決ルートになります。 - 運用で特に重要なのはボリューム／DB のバックアップと .env の差分管理です。アップデート前に必ずバックアップを取り、.env.example の変更を差分反映してください。 推奨する初動アクション（すぐにできること）： 1. Docker と Docker Compose のバージョン確認・必要ならアップデート。 2. ホストに最低でも 4 GiB（できれば 8 GiB）割当て。macOS では Docker Desktop の VM 設定を確認。 3. git clone して dify/docker で cp .env.example .env → 必要最低限の値（DB パスワード等）を編集。 4. docker compose up -d → docker compose ps / logs で起動確認 → ブラウザで初期セットアップ。 5. 初回成功後、DB ダンプとボリュームのバックアップを取得してから拡張（Weaviate / Milvus / ローカルLLM）を行う。 もしよければ、あなたの環境情報（OS, Docker Desktop の有無, 割当メモリ量, 個人 PC か社内 PC か）を教えてください。環境に合わせた .env の最小編集例、Windows と macOS/Linux の具体的なコマンド差分、Milvus を使う場合の MILVUS_URI 設定例などを作成してお渡しします。

### 調査の本質 目的と背景の理解 - ユーザーは「DifyをローカルのDockerでセルフホストする手順を優しく解説してほしい」と求めています。表面的には「起動手順」を求めていますが、成功させるには「環境準備」「.env設定」「トラブルシュート」「運用・バックアップ設計」まで含めた実務的なナビゲーションが必要です。 - 価値提供の方向性：初心者が確実に「動かせる」こと＋運用段階で詰まらないための「事前チェックリスト」「よくある落とし穴の回避策」「復旧手順」を提示すること。さらに、将来的な拡張（ベクタDB分離、ローカルLLM連携、公開時のセキュリティ）まで見据えた実践的示唆を与えることが重要です。 期待されるアウトプット（本回答で提供するもの） - 起動前のプレフライトチェックリスト、実行コマンド例（git → .env → docker compose 起動）、主要トラブルと対処コマンド、運用上の必須作業（バックアップ・アップデート手順）、拡張/公開時の設計上の判断指針。 - 公式とコミュニティ情報を根拠に、なぜ躓きやすいかを因果で説明し、優先度つきアクションを提示します（出典例: 公式ドキュメント https://docs.dify.ai/en/getting-started/install-self-hosted/docker-compose 、コミュニティ手順等）。 --- ### 分析と発見事項 主要な発見（要点と根拠） 1. 起動失敗の主原因は「環境リソース不足」と「.env設定ミス」 - 証拠: Difyは複数サービス（api/web/worker/db/redis/weaviate等）をComposeで起動するためメモリ・CPUを消費する（公式ドキュメント）(https://docs.dify.ai/en/getting-started/install-self-hosted/docker-compose)。 - 実務示唆: macOS等ではDocker VMに 2 vCPU・8GB 程度の割当を推奨する事例がある（コミュニティ）(https://yanai-ke.com/dify001/)。 2. .env の不整合が最も致命的（起動やCORS・API接続不良の原因に） - 重要変数例: SECRET_KEY、VECTOR_STORE、MILVUS_URI、CONSOLE_API_URL、APP_WEB_URL、UPLOAD_FILE_SIZE_LIMIT 等（調査結果）(https://docs.dify.ai/en/getting-started/install-self-hosted/docker-compose)。 - 実務示唆: .env.example と自分の .env を差分比較して反映することが必須（アップデート時の失敗を防ぐ）。 3. ドキュメント間でポートやアクセスURL表記がバラつくため「ブラウザで何も見えない」障害が起きやすい - 例: /install、:3000、:8080 など複数の表記がある（Qiita 等の導入記事）。起動後は docker-compose のポートマッピングを必ず確認すること(https://qiita.com/Misshii/items/b23adc1612019568149c)。 4. Weaviate／Milvus 等のベクタDBやローカルLLMを同居すると I/O とメモリ負荷が急増する - 対処例: 軽量化するか外部化（別ホスト・マネージド）を検討（Zenn、Milvusチュートリアル）(https://zenn.dev/kesin11/scraps/3984fe4f5313fd)、(https://milvus.io/blog/hands-on-tutorial-build-rag-power-document-assistant-in-10-minutes-with-dify-and-milvus.md)。 5. よくあるトラブルと短絡対応 - 管理者パスワードリセット: docker compose exec -it api flask reset-password（コンテナ名は環境による）(https://legacy-docs.dify.ai/learn-more/faq/install-faq)。 - 暗号化キー喪失: flask reset-encrypt-key-pair（ただし元キーは復元不可）(https://legacy-docs.dify.ai/learn-more/faq/install-faq)。 - アップロードの413エラー: .env の UPLOAD_FILE_SIZE_LIMIT と Nginx の client_max_body_size を合わせて調整する必要がある（コミュニティ事例）(https://qiita.com/hara2dev/items/a04b9724de9e7a1d4867)。 短い対比表：よくある障害と初動対応 | 障害 | 主因（想定） | まずやること | |---|---:|---| | コンテナが起動しない | .env設定ミス、ポート衝突、リソース不足 | docker compose ps / logs を確認（.env とポート） | | UIが見えない | ポート誤認、CORS | docker compose ps でポート確認、DevToolsでCORSヘッダ確認 | | 大きなファイルで413 | Nginx client_max_body_size / UPLOAD_FILE_SIZE_LIMIT | .env と nginx.conf を調整して再起動 | | 管理者ログイン不可 | パスワード忘れ、メール未設定 | docker compose exec -it api flask reset-password | （出典: 公式ドキュメント、Qiita、yanai-ke、Milvus チュートリアル等） --- ### より深い分析と解釈 「なぜ失敗するか」を3段階掘り下げ（例：初回起動失敗） 1. レベル1（表面）: コンテナが起動しない／UIが表示されない - 観察: docker compose up -d で複数コンテナが立ち上がらない、または立ち上がってもUIが見えない。 2. レベル2（中間）: 主要な原因は .env の不整合、ポート競合、あるいはリソース不足 - .env不整合 → API/フロントのURLやDB接続が壊れる。 - ポート競合 → ホスト側の別プロセスが同ポートを占有。 - リソース不足 → Postgres/Weaviate/LLMがメモリ不足でクラッシュする。 3. レベル3（根本）: なぜ .env の不整合やリソース不足が発生するか？ - .envの多様な設定項目と頻繁なアップデート（.env.example の変更）が原因で差分管理が追いつかない。 - ローカルで「全部入り構成」をそのまま動かす文化（手軽さ優先）により、ベクタDBやローカルLLMなど負荷の高い機能を同居させてしまう。 - 結果、ユーザーは「とりあえず動かす」段階で運用面（バックアップ、監視、差分管理）に手を付けておらず、一度の障害で復旧が難しくなる。 矛盾・弁証法的解釈 - 「Docker Composeで簡単に動く」と「複数サービスでリソースを逼迫する」は両立する。つまり「起動のハードルは低いが、安定運用のハードルは高い」。そのため、まずは小さく検証→段階的に外部化・分離するアプローチが合理的。 シナリオ分析（意思決定のための簡易モデル） - シナリオA（検証目的）: ローカルで最小構成を立てる（ローカルファイルストレージ、Weaviateを省略または外部利用） - 目的: 迅速にUI／基本機能を確認する。 - 推奨: VMに 4〜8GB を割当、.envは最小限で起動。 - シナリオB（開発/社内利用）: ベクタDBやローカルLLMを統合して検証 - 目的: RAGなどの挙動を再現。 - 推奨: Weaviate を別ホストか外部サービスに分離、ベンチマークでI/Oとメモリ確認。 - シナリオC（公開/本番相当）: 外部公開や多数ユーザーにサービス提供 - 目的: 安定とセキュリティ。 - 推奨: HTTPS、リバースプロキシ（Nginx）でヘッダ制御、S3等でオブジェクトを外部化、監視とバックアップ必須。 意思決定フロー（簡易） ```mermaid flowchart LR A[目的を決める] --> B{開発 or 検証 or 本番} B -->|検証| C[最小構成で起動] B -->|開発| D[Weaviate外部化 or 別ホスト] B -->|本番| E[HTTPS/Firewall/監視/バックアップ] ``` --- ### 戦略的示唆（実践的アクションプラン） 優先度付き実行プラン（短期 → 中期 → 長期） 短期（24時間〜数日で「動かす」） 1. プレフライト（必ず確認） - Docker (>=19.03) / Docker Compose (>=1.28) のバージョンチェック（https://docs.dify.ai/en/getting-started/install-self-hosted/docker-compose）。 - ホストのメモリ割当確認（macOSなら Docker Desktop に2 vCPU・8GBを割当てるのが実務的に良い）(https://yanai-ke.com/dify001/)。 2. ソース取得と.env準備 - git clone https://github.com/langgenius/dify.git - cd dify/docker - cp .env.example .env（.env.example と差分比較する習慣を付ける）(https://qiita.com/Misshii/items/b23adc1612019568149c)。 3. 起動と基本確認（コマンド） - docker compose up -d - docker compose ps / docker ps - docker compose logs -f <service> - ブラウザで http://localhost:3000 または http://localhost/install にアクセス（ポートは環境依存なので docker-compose.yaml を確認）(https://qiita.com/Misshii/items/b23adc1612019568149c)。 中期（安定運用を目指す） 1. バックアップ体制 - PostgreSQL のダンプ（pg_dump）と Docker ボリュームの定期バックアップを設定（バックアップ前に停止不要の場合の手順も検討）。 2. .env の運用管理 - .env を安全に保管し、アップデート時は .env.example と差分を必ずマージするワークフローを文書化(https://yanai-ke.com/dify001/)。 3. ログ収集/監視 - docker logs、docker stats、必要ならホストの監視ツールを導入。ローカルLLMを使う場合は GPU / メモリ監視も必須(https://zenn.dev/kesin11/scraps/3984fe4f5313fd)。 長期（公開・拡張） 1. アーキテクチャ分離 - ベクタDB（Weaviate / Milvus / Qdrant）や推論（ローカルLLM）は別ホストへ切出す。重い推論は別GPUサーバに任せる(https://zenn.dev/kesin11/scraps/3984fe4f5313fd)。 2. セキュリティ - 外部公開時はHTTPS、ファイアウォール、リバースプロキシ（Nginx）でヘッダ制御、APIキー管理を徹底(https://yanai-ke.com/dify001/)。 3. 自動化 - バックアップ・アップデート（git pull → .env 差分検査 → docker compose down/up）をスクリプト化する。 すぐ使えるコマンド集（抜粋） - git clone https://github.com/langgenius/dify.git - cd dify/docker - cp .env.example .env - docker compose up -d - docker compose ps / docker ps - docker compose logs -f <service> - docker compose exec -it api flask reset-password - docker compose exec -it api flask reset-encrypt-key-pair 安全性を担保するための具体的小ワークフロー（例） 1. 起動前: バックアップ（ボリュームと .env のコピー） 2. 更新: git pull → .env.example と比較 → docker compose down → docker compose up -d 3. 問題対応: docker compose logs -f で原因解析 → 必要ならバックアップから復元 参考となる変数例（注意: リポジトリの .env.example を必ず確認してください） - SECRET_KEY=（ランダムな文字列） - VECTOR_STORE=weaviate（または milvus / qdrant 等） - MILVUS_URI=host.docker.internal:19530（Milvusをホストで動かす場合の例） - CONSOLE_API_URL=http://localhost:3001 - APP_WEB_URL=http://localhost:3000 - UPLOAD_FILE_SIZE_LIMIT=50 （上は「よく見られる設定例」であり、実際の変数名・値は dify/docker/.env.example と照合して下さい）（出典: 公式ドキュメント、Milvus チュートリアル、コミュニティ記事） --- ### 今後の調査（優先度つき提案） 以下は、この構築を継続的に安定化・拡張するために追加で調査・作成すべき項目です。必要であれば各テーマごとに具体的手順やサンプルを作成します。 高優先度（すぐ必要） - .env の最小サンプル（OS別: macOS / Windows(WSL2 / Rancher) / Linux）を作成して提供する。 - Nginx のリバースプロキシ設定テンプレート（CORS ヘッダと client_max_body_size の設定例）を用意する（コミュニティ事例で413対応が必要になるため）(https://qiita.com/hara2dev/items/a04b9724de9e7a1d4867)。 中優先度（運用で有効） - ベクタDB（Weaviate/Milvus/Qdrant）のローカル性能ベンチマークと「外部化」コスト比較。Milvus チュートリアル参照(https://milvus.io/blog/hands-on-tutorial-build-rag-power-document-assistant-in-10-minutes-with-dify-and-milvus.md)。 - バックアップ自動化スクリプト（Postgres pg_dump + Docker ボリューム tar 化）と復元手順のテンプレート。 低〜中優先度（将来に備える） - ローカルLLM（LMStudio / ollama 等）とDify連携の具体的設定例（ホスト名、ポート、OpenAI互換APIのエンドポイント例、メモリ管理の指針）(https://zenn.dev/kesin11/scraps/3984fe4f5313fd)。 - セキュリティチェックリスト（公開時のTLS、ファイアウォール、APIキー管理、.envの扱い）(https://yanai-ke.com/dify001/)。 - CI/CD の簡易化（アップデート時の .env 差分検知、無停止デプロイを想定した手順）。 お願い（次のアクション） - あなたの実環境情報を教えてください：OS・Docker Desktopの有無・割当メモリ・目的（検証/社内利用/公開）・使いたいベクタDBやローカルLLMの有無。 - これらを頂ければ、OS別の具体的な .env 最低限編集例、nginx 設定テンプレート、あるいはトラブル時のログ解析手順（ログ抜粋の添付をいただければ個別対応）を作成します。 参照（主要） - Dify 公式ドキュメント (Docker Compose): https://docs.dify.ai/en/getting-started/install-self-hosted/docker-compose - Windows/macOS 実践メモ: https://yanai-ke.com/dify001/ - Qiita ハンズオン（手順例）: https://qiita.com/Misshii/items/b23adc1612019568149c - Milvus + Dify チュートリアル（RAG 連携例）: https://milvus.io/blog/hands-on-tutorial-build-rag-power-document-assistant-in-10-minutes-with-dify-and-milvus.md - トラブルシュート事例（アップロード上限等）: https://qiita.com/hara2dev/items/a04b9724de9e7a1d4867 必要であれば、あなたの環境を教えてください。環境に合わせた最短の「.env 最小編集例」と、nginx の設定テンプレートを作ってお渡しします。