Docker Build Guide

[!NOTE] 最新の実装状況は機能実装ステータス (Remaining Functionality) を参照してください。

EvoSpikeNet-Core の主要な Docker ビルドと起動パターンをまとめたガイドです。

対象

統合 Compose: docker-compose.yml
NGC GPU 構成: docker-compose.ngc.yml
RAG 単体構成: rag-system/docker-compose.yml
RAG backend-only 構成: rag-system/backend/docker-compose.yml

前提条件

Docker Engine
docker compose v2
GPU を使う場合は NVIDIA Container Toolkit

確認コマンド:

docker --version
docker compose version

重要な build 変数

ルートの Dockerfile では主に次の build 引数を使います。

BUILD_TARGET: 通常は development
ENABLE_GPU: true または false
INSTALL_JUPYTER: notebook イメージに Jupyter を含めるかどうか

NGC 系では追加で次を使います。

NGC_PYTORCH_TAG: 例 26.01-py3

環境ファイルについて

このリポジトリには .env.example を同梱しています。初回は次の手順で .env を作成してください。

cp .env.example .env

最小構成例（CPU）:

cat > .env <<'EOF'
BUILD_TARGET=development
ENABLE_GPU=false
EVOSPIKENET_API_KEY=test-api-key
EVOSPIKENET_API_KEYS=test-api-key
EVOSPIKENET_ALLOW_NO_AUTH=true
EOF

GPU を使う場合は ENABLE_GPU=true に変更してください。

1. 統合 Docker システムをビルドする

標準構成です。frontend、api、rag-api、PostgreSQL、Redis、OPA、Zenoh Router、Milvus、Elasticsearch などをまとめて使う前提です。

イメージのみビルド:

docker compose build

ビルドして起動:

docker compose up --build -d

開発用サービスも含めて起動:

docker compose --profile full up --build -d

キャッシュを使わずに再ビルド:

docker compose build --no-cache
docker compose up -d

2. Notebook / Jupyter の扱い

注: 現行の docker-compose.yml では既に notebook サービスは削除されています。過去の手順や INSTALL_JUPYTER 前提の記述は古く、当該手順のまま実行すると失敗します。

Jupyter を使いたい場合は次のいずれかを推奨します。

開発用の dev コンテナを使い、コンテナ内で Jupyter を起動する。
1. docker compose --profile full build --no-cache dev
2. docker compose --profile full run --service-ports --rm dev bash
3. コンテナ内で pip install jupyterlab して jupyter lab --ip=0.0.0.0 --port=8888 --no-browser を実行
特定のノートブックイメージが必要な場合は独立した Compose サービス（例: jupyter/base-notebook）を一時的に追加して起動する。

自動化注意点: ドキュメントと Compose の齟齬を防ぐため、リポジトリ内の Compose 定義からサービス/プロファイルの一覧を自動生成するスクリプトを tools/generate_compose_services_md.py として用意しています。CI でこのスクリプトを実行し、ドキュメントに含める一覧を検証することを推奨します。

3. NGC ベース構成をビルドする

GPU 最適化イメージを使う場合の構成です。

NGC notebook を起動:

docker compose -f docker-compose.ngc.yml up --build -d ngc-notebook

NGC フルスタックを起動:

docker compose -f docker-compose.ngc.yml --profile full up --build -d

主な環境変数:

export NGC_PYTORCH_TAG=26.01-py3

直接 Dockerfile からビルドする例:

docker build -f Dockerfile.ngc -t evospikenet:ngc .
docker build -f Dockerfile.ngc.public -t evospikenet:ngc-public .

4. RAG 単体構成をビルドする

rag-system には 2 つのモードがあります。

full: rag-api、frontend-rag、Milvus、Elasticsearch、MinIO、etcd を起動
ragapi: rag-api のみ起動し、共有ネットワーク milvus 上の既存サービスへ接続

フル構成:

cd rag-system
docker compose --profile full up --build -d

共有基盤に接続する API 単体モード:

cd rag-system
RAG_API_PORT=18101 docker compose --profile ragapi up --build -d rag-api

ポート競合時の例:

cd rag-system
RAG_API_PORT=18101 FRONTEND_RAG_PORT=18060 ES_HTTP_PORT=19200 docker compose --profile full up --build -d

5. RAG backend-only 構成をビルドする

UI を含めずに RAG API と依存サービスだけを使いたい場合の構成です。

フル構成:

cd rag-system/backend
docker compose --profile full up --build -d

共有基盤に接続する API 単体モード:

cd rag-system/backend
RAG_API_PORT=18201 docker compose --profile ragapi up --build -d rag-api

6. テスト用 Compose をビルドする

テスト専用 compose を使う場合:

docker compose -f docker-compose.test.yml build

キャッシュなし:

docker compose -f docker-compose.test.yml build --no-cache

6.1. microservices 構成を fail-closed で起動する

docker-compose.microservices.yml では一部の危険な疑似処理を既定で無効化しています。運用時は .env でも同じ値を明示してください。

最小例:

cat > .env <<'EOF'
DEVICE=cpu
VIDEO_ANALYSIS_ASR_BACKEND=whisper_real
VIDEO_ANALYSIS_FAIL_CLOSED=true
ALLOW_SIMULATED_TRAINING=false
ENABLE_EXPERIMENTAL_DNA_ENCODING=false
EOF

起動:

docker compose -f docker-compose.microservices.yml up --build -d

重要な変数:

VIDEO_ANALYSIS_FAIL_CLOSED=true: video-analysis が real backend 不足時に stub/fallback 成功へ倒れないようにします。
ALLOW_SIMULATED_TRAINING=false: training サービスの simulation ベース完了応答を禁止します。
ENABLE_EXPERIMENTAL_DNA_ENCODING=false: model-registry の実験的 DNA encode API を無効化します。

7. よく使う Dockerfile

Dockerfile: ルート統合構成
Dockerfile.ngc: NGC GPU 構成
Dockerfile.ngc.public: 公開向け NGC 構成
Dockerfile.test: テスト用途
Dockerfile.train.cpu: CPU 学習用途
Dockerfile.train.gpu: GPU 学習用途
Dockerfile.services: 補助サービス用途

8. トラブルシューティング

`.env` の初期化

テンプレートから作成します。

cp .env.example .env

`ragapi` で Milvus / Elasticsearch に接続できない

ragapi は依存サービスを自動起動しません。先に共有基盤を起動してください。

docker compose up -d milvus-standalone elasticsearch etcd minio
docker network inspect milvus

Elasticsearch や Milvus が起動途中で失敗する

一度設定だけ確認する場合は config を使います。

docker compose config
docker compose -f docker-compose.ngc.yml --profile full config
cd rag-system && docker compose --profile full config
cd rag-system/backend && docker compose --profile full config

ビルドキャッシュを捨てたい

docker compose build --no-cache