Compose スクリプト統合

本ページの内容はデジタルヒューマン株式会社の正式サポート対象外です。参考情報としてご利用ください。

Compose マージ: merge-compose.sh スクリプトは、公式のミニプレム（MiniPrem）の compose ファイルとお客様のカスタムサービスを単一の docker-compose.override.yml に統合し、カスタマイズ内容をアップデートに対して安全に保ちます。

概要

merge-compose.sh スクリプトは、公式の MiniPrem Docker Compose ファイルとユーザー定義のカスタムサービスをインテリジェントにマージします。これにより、公式の compose ファイルを更新可能な状態に保ちつつ、追加サービスで MiniPrem を拡張できます。

クイックスタート

1. カスタム compose ファイルを作成する

cd /Users/tyler/Software_Development/miniprem-2025/docker
cp docker-compose.custom.yml.example docker-compose.custom.yml
# Edit docker-compose.custom.yml with your custom services

2. マージスクリプトを実行する

./scripts/merge-compose.sh

これにより、Docker Compose が自動的に利用する docker-compose.override.yml が生成されます。

3. サービスを起動する

# Docker Compose automatically merges docker-compose.yml + docker-compose.override.yml
docker-compose up -d

# Or explicitly specify both files
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d

スクリプトの機能

インテリジェントなマージ

• サービス: カスタムサービスを公式サービスに追記します

• ボリューム: ボリューム定義をマージします（重複なし）

• ネットワーク: ネットワーク定義をマージします

• 環境変数: カスタム環境変数で公式の値を上書きできます（サービス定義内）

競合検出

スクリプトは、カスタムサービスが公式サービスと同じ名前である場合を検出し、複数の解決戦略を提供します。

検証

• マージ前後の YAML 構文検証

• Docker Compose の設定検証（有効な compose ファイルであることを保証）

• 問題がある場合は明確なエラーメッセージを表示

メタデータ

生成された override ファイルには、有用なコメントが含まれます:

• マージタイムスタンプ

• ソースファイル

• 競合解決戦略

• 競合のリスト（存在する場合）

使用例

基本的なマージ（デフォルトの動作）

./scripts/merge-compose.sh

• 入力: docker-compose.yml + docker-compose.custom.yml

• 出力: docker-compose.override.yml

• 戦略: 同名のサービスがある場合、カスタムサービスが公式サービスを上書き

書き込みせずに競合をチェックする

./scripts/merge-compose.sh --check

競合が存在する場合は終了コード 2、競合がなければ 0 を返します。

競合解決戦略の選択

カスタムを優先（デフォルト）

./scripts/merge-compose.sh --prefer-custom

サービス名が競合した場合、カスタム版を保持します。

公式を優先

./scripts/merge-compose.sh --prefer-official

サービス名が競合した場合、公式版を保持します（カスタムサービスは無視されます）。

カスタムサービスをリネーム

./scripts/merge-compose.sh --rename-custom "custom-"

サービス名が競合した場合、指定したプレフィックスでカスタムサービスをリネームします。

例: 両方のファイルに redis サービスがある場合、カスタムは custom-redis になります。

カスタム入出力ファイル

./scripts/merge-compose.sh \
  --file my-services.yml \
  --output my-override.yml

詳細出力

./scripts/merge-compose.sh --verbose

マージ処理に関する詳細なデバッグ情報を表示します。

オプションの組み合わせ

./scripts/merge-compose.sh \
  --file docker-compose.custom.yml \
  --output docker-compose.override.yml \
  --rename-custom "myapp-" \
  --verbose

終了コード

• 0: 成功（競合なし、または競合が解決済み）

• 1: エラー（検証失敗、依存関係不足、構文エラー）

• 2: 競合検出（情報、戦略によっては成功する場合もあり）

競合のシナリオ

シナリオ 1: 競合なし（最良のケース）

公式:

services:
  renny:
    image: facemeproduction/renny:latest
  flowise:
    image: flowiseai/flowise:latest

カスタム:

services:
  postgres:
    image: postgres:15
  custom-api:
    image: mycompany/api:latest

結果: マージ後のファイルに 4 つすべてのサービスが含まれます。競合なし。

シナリオ 2: サービス名の競合

公式:

services:
  redis:
    image: redis:7-alpine

カスタム:

services:
  redis:
    image: redis:6-alpine
    command: redis-server --maxmemory 256mb

解決オプション:

1. --prefer-custom（デフォルト）: カスタムの Redis 設定を使用

2. --prefer-official: 公式の Redis 設定を使用

3. --rename-custom "my-": カスタム設定で my-redis を作成し、公式の redis を保持

シナリオ 3: ボリュームの競合

両方のファイルが同じボリューム名を定義している場合、カスタム定義が優先されます。

公式:

volumes:
  redis_data:

カスタム:

volumes:
  redis_data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /mnt/redis-data

結果: カスタムのボリューム定義が使用されます。

ベストプラクティス

1. 一意のサービス名を使用する

明示的に公式サービスを上書きしたい場合を除き、カスタムサービスに公式サービスと同じ名前を付けることは避けてください。

良い例:

services:
  my-postgres:  # Unique name
  my-api:       # Unique name

リスクのある例:

services:
  redis:  # Conflicts with official redis service

2. 依存関係を正しく使用する

カスタムサービスは公式サービスに依存させることができます:

services:
  my-api:
    depends_on:
      - redis      # Official service
      - flowise    # Official service
      - my-postgres # Custom service

3. カスタムファイルを個別に管理する

docker-compose.custom.yml は公式ファイルとは別にバージョン管理してください。これにより以下が可能になります:

• カスタマイズを失わずに公式 compose ファイルを更新

• チーム間でカスタムサービスを共有

• カスタムサービスの変更を追跡

4. 本番環境にデプロイする前にテストする

マージした設定は必ずテストしてください:

# Check for conflicts
./scripts/merge-compose.sh --check

# Validate merged output
docker-compose -f docker-compose.override.yml config

# Test startup
docker-compose up -d
docker-compose ps

5. カスタムサービスをドキュメント化する

docker-compose.custom.yml に以下を説明するコメントを追加してください:

• 各サービスの役割

• なぜそれが必要か

• 依存関係や設定要件

トラブルシューティング

エラー: 「Missing required tools: yq」

解決方法:

# macOS
brew install yq

# Linux
wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq
chmod +x /usr/local/bin/yq

エラー: 「Invalid YAML syntax」

解決方法: カスタム compose ファイルの構文エラーを確認してください:

yq eval '.' docker-compose.custom.yml

よくある問題:

• 不正なインデント（タブではなく 2 スペースを使用）

• コロンの欠落

• 特殊文字のクォート漏れ

• ポートマッピングのクォート漏れ

エラー: 「docker-compose config validation failed」

解決方法: マージ後のファイルに構造上の問題があります。以下を確認してください:

docker-compose -f docker-compose.override.yml config

よくある問題:

• 不正なサービス依存関係

• サービス間のポート競合

• 無効なボリュームまたはネットワーク参照

警告: 「Conflicts detected」

解決方法: 競合を確認し、適切な戦略を選択してください:

# See what conflicts exist
./scripts/merge-compose.sh --check

# Choose resolution strategy
./scripts/merge-compose.sh --prefer-official
# OR
./scripts/merge-compose.sh --rename-custom "custom-"

高度な使用法

複数のカスタムファイルをマージする

# First merge
./scripts/merge-compose.sh \
  --file custom-databases.yml \
  --output temp-override.yml

# Second merge (merge temp-override.yml with more custom services)
./scripts/merge-compose.sh \
  --file custom-apis.yml \
  --output docker-compose.override.yml

条件付きサービス

カスタムファイルで環境変数を使用します:

services:
  optional-service:
    image: myimage:latest
    environment:
      - ENABLE_FEATURE=${ENABLE_FEATURE:-false}

実行時に制御します:

ENABLE_FEATURE=true docker-compose up -d

CI/CD での自動マージ

#!/bin/bash
set -e

# Merge custom services
./scripts/merge-compose.sh --check || exit 1
./scripts/merge-compose.sh

# Validate
docker-compose config > /dev/null

# Deploy
docker-compose up -d

MiniPrem との統合

デフォルト（Default Install）

MiniPrem のデフォルト docker-compose.yml には以下が含まれます:

• miniprem-monitor: リアルタイムモニタリングダッシュボード

• renny: デジタルヒューマンのレンダラー（開発コード：Renny）

フルインストール（Full Install）

docker-compose.full.yml には以下が含まれます:

• すべてのデフォルトサービス

• vllm: LLM 推論

• flowise: ワークフロー自動化

• redis: メッセージキュー

• prometheus: メトリクス収集

• grafana: メトリクス可視化

• fastwhisper: STT（音声認識）

カスタムサービスの追加

MiniPrem と統合するサービスを追加できます:

services:
  # Custom chatbot backend
  my-chatbot:
    image: mycompany/chatbot:latest
    environment:
      - FLOWISE_URL=http://localhost:3000
      - VLLM_URL=http://localhost:8000
    depends_on:
      - flowise
      - vllm
    network_mode: host

ファイルの配置場所

• スクリプト: /Users/tyler/Software_Development/miniprem-2025/docker/scripts/merge-compose.sh

• 公式 Compose: /Users/tyler/Software_Development/miniprem-2025/docker/docker-compose.yml

• 公式フル: /Users/tyler/Software_Development/miniprem-2025/docker/docker-compose.full.yml

• カスタムテンプレート: /Users/tyler/Software_Development/miniprem-2025/docker/docker-compose.custom.yml.example

• お客様のカスタムファイル: /Users/tyler/Software_Development/miniprem-2025/docker/docker-compose.custom.yml

• 生成された Override: /Users/tyler/Software_Development/miniprem-2025/docker/docker-compose.override.yml

セキュリティに関する考慮事項

デフォルトのセキュリティ設定

スクリプトは公式サービスのセキュリティ設定を保持します:

• security_opt: no-new-privileges:true

• read_only: true（適用可能な場合）

• ロギングの上限

• ヘルスチェック

カスタムサービスのセキュリティ

カスタムサービスには必ずセキュリティ設定を含めてください:

services:
  my-service:
    image: myimage:latest
    # ... other settings ...
    security_opt:
      - no-new-privileges:true
    read_only: true  # If possible
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

シークレット管理

compose ファイルにシークレットをハードコードしないでください:

悪い例:

environment:
  - DB_PASSWORD=mysecretpassword

良い例:

environment:
  - DB_PASSWORD=${DB_PASSWORD}

そのうえで .env ファイルや環境変数を使用してください。

ヘルプの取得

# Show help message
./scripts/merge-compose.sh --help

# Check script version and options
head -20 ./scripts/merge-compose.sh

コントリビュート

バグを見つけた、または機能リクエストがありますか？マージスクリプトは MiniPrem プロジェクトの一部です。Issue の報告や改善のコントリビュートをお願いします。

ライセンス

MiniPrem プロジェクトの一部です。詳細はプロジェクトのライセンスを参照してください。