> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/dev/miniprem/services/merge-compose-script.md).

# Compose スクリプト統合

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

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

## 概要

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

## クイックスタート

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

```bash
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. マージスクリプトを実行する

```bash
./scripts/merge-compose.sh
```

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

### 3. サービスを起動する

```bash
# 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 ファイルには、有用なコメントが含まれます:

* マージタイムスタンプ
* ソースファイル
* 競合解決戦略
* 競合のリスト（存在する場合）

## 使用例

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

```bash
./scripts/merge-compose.sh
```

* 入力: `docker-compose.yml` + `docker-compose.custom.yml`
* 出力: `docker-compose.override.yml`
* 戦略: 同名のサービスがある場合、カスタムサービスが公式サービスを上書き

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

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

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

### 競合解決戦略の選択

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

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

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

#### 公式を優先

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

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

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

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

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

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

### カスタム入出力ファイル

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

### 詳細出力

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

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

### オプションの組み合わせ

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

## 終了コード

* **0**: 成功（競合なし、または競合が解決済み）
* **1**: エラー（検証失敗、依存関係不足、構文エラー）
* **2**: 競合検出（情報、戦略によっては成功する場合もあり）

## 競合のシナリオ

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

**公式:**

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

**カスタム:**

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

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

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

**公式:**

```yaml
services:
  redis:
    image: redis:7-alpine
```

**カスタム:**

```yaml
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: ボリュームの競合

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

**公式:**

```yaml
volumes:
  redis_data:
```

**カスタム:**

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

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

## ベストプラクティス

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

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

**良い例:**

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

**リスクのある例:**

```yaml
services:
  redis:  # Conflicts with official redis service
```

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

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

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

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

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

* カスタマイズを失わずに公式 compose ファイルを更新
* チーム間でカスタムサービスを共有
* カスタムサービスの変更を追跡

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

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

```bash
# 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」

**解決方法:**

```bash
# 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 ファイルの構文エラーを確認してください:

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

よくある問題:

* 不正なインデント（タブではなく 2 スペースを使用）
* コロンの欠落
* 特殊文字のクォート漏れ
* ポートマッピングのクォート漏れ

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

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

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

よくある問題:

* 不正なサービス依存関係
* サービス間のポート競合
* 無効なボリュームまたはネットワーク参照

### 警告: 「Conflicts detected」

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

```bash
# 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-"
```

## 高度な使用法

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

```bash
# 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
```

### 条件付きサービス

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

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

実行時に制御します:

```bash
ENABLE_FEATURE=true docker-compose up -d
```

### CI/CD での自動マージ

```bash
#!/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 と統合するサービスを追加できます:

```yaml
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`（適用可能な場合）
* ロギングの上限
* ヘルスチェック

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

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

```yaml
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 ファイルにシークレットをハードコードしないでください:

**悪い例:**

```yaml
environment:
  - DB_PASSWORD=mysecretpassword
```

**良い例:**

```yaml
environment:
  - DB_PASSWORD=${DB_PASSWORD}
```

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

## ヘルプの取得

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

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

## コントリビュート

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

## ライセンス

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