> 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/docker-deployment.md).

# Docker デプロイ

{% hint style="info" %}
**Docker デプロイ:** Docker Compose を使用してミニプレム（MiniPrem）スタック全体をローカルで実行します。Ubuntu 24.04 LTS、ドライバー 580 以降の NVIDIA GPU、および `cr.uneeq.io` の Harbor レジストリへのアクセスが必要です。
{% endhint %}

## 概要

MiniPrem の Docker デプロイは、必要なすべてのサービスをコンテナ化し、セットアップと管理が容易な完全なローカル開発環境を提供します。本ガイドでは、Docker 固有のデプロイメントプロセス、設定、および管理について説明します。

{% hint style="warning" %}
前提条件を満たす環境の準備はお客様の責任において実施いただきますようお願いいたします。デジタルヒューマン株式会社では前提条件を満たすための環境構築のサポート、ドライバー等の不具合に対する対応作業は提供しておりません。
{% endhint %}

{% hint style="warning" %}
2026年6月現在、デジタルヒューマン株式会社の正式サポート対象はデフォルト（Default Install）の Renny のみです。フルインストール（Full Install）に含まれる Renny 以外のサービス（vLLM、Flowise、RIME AI、NVIDIA RIVA、Whisper など）はサポート対象外です。
{% endhint %}

## 前提条件

* **Ubuntu 24.04 LTS** 以降（WSL は非サポート）
* Docker Engine および Docker Compose v2.0 以降（Docker Desktop は MiniPrem で必要な GPU パススルーをサポートしません）
* [NVIDIA プロプライエタリドライバー（バージョン 580 以降が必須）](/dev/miniprem/nvidia-drivers.md)
* [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
* Harbor レジストリの認証情報（`cr.uneeq.io` 用のロボットアカウント）
* Docker GPU ランタイム対応の NVIDIA GPU（GPU アクセラレーション用）
* 最低 16GB の RAM
* 50GB の空きディスク容量
* ポート 443 (HTTPS) で `cr.uneeq.io` へアクセスできるネットワーク

{% hint style="info" %}
**初回 Docker pull のディスク所要量:** インストーラーは必要な Docker イメージを自動的にダウンロードしますが、フルインストール（Full Install）では合計で **約 80GB** のイメージを取得します。\
回線帯域とストレージ空き容量を事前に確保してください。社内ネットワークでアウトバウンド帯域に制限がある環境では、初回 pull のみ別ネットワークから実施することを推奨します。\
詳細な前提条件は [前提条件チェック](/dev/miniprem/prerequisites.md) を参照してください。
{% endhint %}

## コンテナレジストリへのアクセス

### Harbor レジストリの要件

MiniPrem のコンテナイメージは、`cr.uneeq.io` のプライベート Harbor レジストリにホストされています。MiniPrem をデプロイする前に、Harbor のロボットアカウント認証情報を使用してこのレジストリで認証する必要があります。

トラブルシューティング手順やエンタープライズファイアウォール設定など、Harbor レジストリアクセスに関する詳細は [Harbor レジストリガイド](/dev/miniprem/harbor-registry.md) を参照してください。

### レジストリ認証のクイックスタート

サービスを開始する前に Harbor レジストリで認証します。

```bash
# Log in with your robot account credentials
docker login https://cr.uneeq.io --username 'robot$your-customer-name'

# When prompted, enter your Harbor password/token
```

**期待される出力**:

```
Password:
Login Succeeded
```

### ネットワーク要件

ファイアウォールが Harbor レジストリへのアウトバウンド接続を許可していることを確認してください。

* **レジストリエンドポイント**: `cr.uneeq.io:443`
* **プロトコル**: HTTPS (TLS 1.2 以降)
* **方向**: アウトバウンド

ファイアウォールルールが厳格なエンタープライズ／企業ネットワークでは、ネットワーク管理者が `cr.uneeq.io` をポート 443 でホワイトリストに登録していることを確認してください。

### 認証情報の管理

Docker は Harbor レジストリの認証情報を自動的に暗号化し、`~/.docker/config.json` に保存します。本番デプロイメントでは、以下を確認してください。

* 認証情報が安全に保管されていること
* 認証情報ファイルがバージョン管理にコミットされていないこと
* アクセス認証情報が定期的にローテーションされていること

## インストーラーの入手

デプロイ作業を始める前に、MiniPrem のインストーラー一式を入手します。入手経路は 2 種類あります。

{% tabs %}
{% tab title="デジタルヒューマン配布版（日本国内のお客様向け）" %}

```bash
# インストーラーのダウンロードと解凍
wget hosted-experience.jp/miniprem/miniprem_v1.00.zip
unzip miniprem_v1.00.zip
cd MiniPrem
```

{% hint style="info" %}
デジタルヒューマン配布版は日本国内のお客様向けにデジタルヒューマン株式会社が提供する経路です。ダウンロード URL や認証情報については[サポート窓口](https://support.digitalhumans.jp/)までお問い合わせください。
{% endhint %}
{% endtab %}

{% tab title="UneeQ 公式（GitHub）" %}

```bash
git clone https://github.com/uneeq-digital-humans/miniprem.git
cd miniprem
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**インストールスクリプトのパスの違い:** 本ページのコマンド例は UneeQ 公式（GitHub）版のディレクトリ構成（`./docker/scripts/install_miniprem.sh`）で記載しています。デジタルヒューマン配布版をご利用の場合は、解凍したディレクトリ直下の `./install_miniprem.sh` に読み替えてください。
{% endhint %}

インストール時に必要な設定値（Platform Address・API キー・テナント ID・Azure リージョンなど）の一覧は [はじめに](/dev/miniprem/getting-started.md) の「設定値」を参照してください。

## インストール種別

MiniPrem は 3 種類のインストールプロファイルを提供しています。

⚙

### デフォルト（Default Install）

Renny デジタルヒューマンレンダラー + MiniPrem Monitor。ほとんどのデプロイメントに最適。

⚡

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

完全な AI スタック: Renny、vLLM、Flowise、Grafana/Prometheus、RIME TTS、Whisper STT。

📊

### Monitor のみ

既存デプロイメント向けに、サービスを再インストールせずに独立して動作する MiniPrem Monitor。

### 1. デフォルトインストール

Renny デジタルヒューマンと MiniPrem Monitor を含みます。

```bash
./docker/scripts/install_miniprem.sh
# Select "default" when prompted
```

### 2. フルインストール

全サービスを含む完全な AI スタックです。

```bash
./docker/scripts/install_miniprem.sh
# Select "full" when prompted
```

含まれるもの:

* Renny デジタルヒューマンレンダラー（開発コード：Renny）
* vLLM 推論サーバー
* Flowise ワークフロー自動化
* MiniPrem Monitor ダッシュボード
* Grafana/Prometheus モニタリング
* Redis メッセージキュー
* RIME TTS（音声合成）
* Whisper STT（音声認識）

### 3. Monitor のみ

既存デプロイメント向けのスタンドアロンモニタリング:

```bash
cd docker/
docker compose -f docker-compose.monitor.yml up -d
```

## クイックスタート

### Harbor 認証（必須の最初のステップ）

インストールを実行する前に、Harbor レジストリで認証します。

```bash
# Authenticate with Harbor registry
docker login https://cr.uneeq.io --username 'robot$your-customer-name'

# Enter your Harbor password/token when prompted
```

認証が完了すれば、インストールに進めます。

### インタラクティブインストール

最も簡単に始める方法です。

```bash
# Run interactive installer
./docker/scripts/install_miniprem.sh

# Follow prompts to:
# 1. Choose installation type (default/full)
# 2. Configure Hosted Experience credentials
# 3. Set up services
```

### 手動インストール

プロセスをより細かく制御したい場合に使用します。

```bash
# 1. Configure Hosted Experience credentials
cat > docker/configuration.dat << EOF
{
  "customerJWT": "your-jwt-token",
  "tokenIssuer": "your-issuer-url",
  "tokenIssuerPublicKey": "your-public-key"
}
EOF

# 2. Start services
./miniprem.sh start

# 3. Verify deployment
./miniprem.sh status
```

## サービス管理

### miniprem.sh スクリプトの使用

メインの管理スクリプトは、便利なコマンドを提供します。

```bash
# Start all services
./miniprem.sh start

# Stop all services
./miniprem.sh stop

# Check service status
./miniprem.sh status

# View logs
./miniprem.sh logs

# Restart services
./miniprem.sh restart

# Initial setup
./miniprem.sh setup
```

{% hint style="info" %}
**`./miniprem.sh setup` の内部挙動:** `setup` コマンドは Flowise の Chatflow 初期設定を実行しますが、内部的には次の処理を順番に行います。\\

1. Flowise サービスの稼働確認\\
2. サービスが停止している場合は自動的に起動\\
3. Flowise が完全に起動するまで待機（**最大 5 分**）\\
4. Chatflow の初期設定スクリプトを実行\
   \
   Flowise の初期化には時間がかかるため、コマンドが長時間ハングしているように見えても、最大 5 分は待機してください。途中で中断すると Chatflow が不完全な状態になります。
   {% endhint %}

### 運用上の注意事項

`miniprem.sh` スクリプトを安定して運用するため、以下の点にご注意ください。

* **実行場所**: スクリプトは必ず MiniPrem プロジェクトのルートディレクトリから実行してください（`./docker/scripts/` など下位ディレクトリから実行すると相対パス解決に失敗します）。
* **権限**: サービスの起動・停止には Docker デーモンを操作できる権限（`docker` グループ所属または `sudo`）が必要です。
* **ログローテーション**: Docker のログファイル（コンテナログ）は長期稼働するとディスクを圧迫します。`/etc/docker/daemon.json` に `log-opts` の `max-size` / `max-file` を設定する、もしくは `logrotate` の設定を追加して、定期的なローテーションを行ってください。

```json
// /etc/docker/daemon.json の例
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "5"
  }
}
```

設定変更後は `sudo systemctl restart docker` で Docker を再起動してください。

### Docker Compose コマンドの直接実行

より細かい制御を行いたい場合に使用します。

```bash
# Start specific service
docker compose -f docker/docker-compose.yml up -d renny

# View service logs
docker compose -f docker/docker-compose.yml logs -f flowise

# Restart service
docker compose -f docker/docker-compose.yml restart vllm

# Scale services (if supported)
docker compose -f docker/docker-compose.yml up -d --scale renny=2
```

## 設定ファイル

### 主要な設定ファイルの場所

| ファイル                                | 用途                          |
| ----------------------------------- | --------------------------- |
| `docker/configuration.dat`          | デジタルヒューマン プラットフォームの認証情報     |
| `docker/docker-compose.yml`         | デフォルトサービスの定義                |
| `docker/docker-compose.default.yml` | デフォルト（Default Install）構成の定義 |
| `docker/docker-compose.full.yml`    | フルインストール（Full Install）のサービス |
| `docker/docker-compose.monitor.yml` | Monitor のみのデプロイ             |
| `docker/docker-compose.env`         | TTS / Platform 接続用の環境変数     |
| `.miniprem_install_type`            | 現在のインストールプロファイル             |
| `.env`                              | カスタム環境変数（存在する場合）            |

{% hint style="info" %}
**インストーラーが自動更新するファイル:** `install_miniprem.sh` は初回実行時に `docker/docker-compose.env`、および `docker/docker-compose.default.yml` または `docker/docker-compose.yml` を、入力された設定値に基づいて自動的に書き換えます。\
インストール後にこれらのファイルを手動編集する場合は、再インストール時に変更が失われる可能性があるため、必ずバックアップを取得してください。
{% endhint %}

### 環境変数

カスタム設定用に `.env` ファイルを作成します。

```bash
# GPU Configuration
NVIDIA_VISIBLE_DEVICES=0
CUDA_VISIBLE_DEVICES=0

# Service Ports
FLOWISE_PORT=3000
MONITOR_PORT=3001
GRAFANA_PORT=3002

# Resource Limits
RENNY_MEMORY_LIMIT=4g
VLLM_MEMORY_LIMIT=8g

# Debug Options
DEBUG_MODE=false
LOG_LEVEL=info
```

### docker-compose.env の主要変数

`install_miniprem.sh` の対話入力で指定した値は、`docker/docker-compose.env` に保存され、各コンテナへ環境変数として注入されます。設定ミスやキー漏れがあった場合は本ファイルを確認してください。

```bash
# Platform 設定（デジタルヒューマン プラットフォーム接続）
DHOP_ADDRESS=wss:[URL]
DHOP_PIXELSTREAMING_ADDRESS=wss:[URL]
DHOP_APIKEY=[your-api-key]
DHOP_TENANTID=[your-tenant-id]

# Azure TTS（音声合成）設定（Azure を選択した場合）
AZURE_REGION=[your-region]
AZURE_SPEECH_KEY=[your-speech-key]

# Eleven Labs 設定（Eleven Labs を選択した場合）
ELEVEN_LABS_API_KEY=[your-api-key]
ELEVEN_LABS_MODEL_ID=eleven_flash_v2_5

# RIME 設定（RIME を選択した場合）
RIME_API_KEY=[your-api-key]
```

| 変数名                           | 説明                                            |
| ----------------------------- | --------------------------------------------- |
| `DHOP_ADDRESS`                | デジタルヒューマン プラットフォームのオーケストレーション接続先（wss）         |
| `DHOP_PIXELSTREAMING_ADDRESS` | Pixel Streaming の接続先 URL（未設定だと映像配信が起動しません）    |
| `DHOP_APIKEY`                 | プラットフォーム接続用 API キー                            |
| `DHOP_TENANTID`               | テナント ID                                       |
| `AZURE_REGION`                | Azure Speech Services のリージョン（例: `japaneast`）  |
| `AZURE_SPEECH_KEY`            | Azure Speech Services の API キー                |
| `ELEVEN_LABS_API_KEY`         | Eleven Labs の API キー                          |
| `ELEVEN_LABS_MODEL_ID`        | Eleven Labs のモデル ID（推奨値: `eleven_flash_v2_5`） |
| `RIME_API_KEY`                | RIME の API キー（RIME 利用時のみ、quay.io パスワードも別途必要）  |

{% hint style="warning" %}
`DHOP_PIXELSTREAMING_ADDRESS` や `ELEVEN_LABS_MODEL_ID` が抜けている、または旧い値のままだと、Pixel Streaming や TTS（音声合成）が起動しません。設定ミスは問い合わせの頻発領域のため、変更後は必ず `cat docker/docker-compose.env` で確認してください。
{% endhint %}

## ポートマッピング

| サービス             | デフォルトポート | 説明                |
| ---------------- | -------- | ----------------- |
| Flowise UI       | 3000     | ワークフロー自動化インターフェース |
| MiniPrem Monitor | 3001     | コンテナモニタリングダッシュボード |
| Grafana          | 3002     | メトリクス可視化          |
| vLLM API         | 8000     | LLM 推論エンドポイント     |
| Renny Health     | 8081     | デジタルヒューマンのヘルスチェック |
| RIME API         | 8100     | TTS（音声合成）サービス     |
| Prometheus       | 9090     | メトリクス収集           |
| Whisper API      | 9000     | STT（音声認識）サービス     |
| Redis            | 6379     | メッセージブローカー        |

## 複数の Renny インスタンス

複数の Renny コンテナを同時に実行するには、複数の Renny セットアップガイド を参照してください。

要点:

* 各インスタンスは一意のポートを必要とします
* 環境変数で設定します
* docker-compose のスケーリングまたは個別の設定を使用します

## GPU 設定

### NVIDIA GPU のセットアップ

1. **NVIDIA Container Toolkit のインストール**:

ドライバーの詳しいインストール手順は [NVIDIA ドライバーガイド](/dev/miniprem/nvidia-drivers.md) を参照してください。

```bash
# Add NVIDIA Container Toolkit repository
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
```

2. **GPU アクセスの確認**:

```bash
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
```

3. **サービス用に GPU を設定**:

```yaml
# In docker-compose.yml
services:
  renny:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
```

## モニタリング

### MiniPrem Monitor

モニタリングダッシュボードには <http://localhost:3001> でアクセスできます。

機能:

* リアルタイムのコンテナステータス
* CPU／メモリ／ディスク／ネットワークのメトリクス
* コンテナ操作（開始／停止）
* ライブパフォーマンスグラフ
* 自動インサイトとレコメンデーション

### Grafana ダッシュボード

詳細なメトリクス用（フルインストールのみ）:

* URL: <http://localhost:3002>
* デフォルト認証情報: admin/admin
* すべてのサービス向けに事前設定済みダッシュボード

## トラブルシューティング

### よくある問題

1. **サービスが起動しない場合**:

```bash
# Check logs
docker compose -f docker/docker-compose.yml logs

# Verify Docker daemon
docker ps

# Check disk space
df -h
```

2. **GPU が認識されない場合**:

```bash
# Verify NVIDIA runtime
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

# Check Docker GPU configuration
docker info | grep nvidia
```

3. **ポートの競合**:

```bash
# Find process using port
lsof -i :3000

# Change port in docker-compose.yml or .env
```

4. **権限の問題**:

```bash
# Fix Docker socket permissions
sudo chmod 666 /var/run/docker.sock

# Add user to docker group
sudo usermod -aG docker $USER
```

### ログの確認

```bash
# All services
docker compose -f docker/docker-compose.yml logs

# Specific service
docker logs miniprem-renny

# Follow logs
docker logs -f miniprem-monitor

# Last 100 lines
docker logs --tail 100 miniprem-flowise
```

## サービスの更新

{% hint style="warning" %}
**アップデート前のご注意:**\\

* アップデート前に、設定ファイル（`docker/configuration.dat`・`docker/docker-compose.env`）と重要なデータのバックアップを必ず取得してください。\\
* 本番環境でのアップデートは、事前にテスト環境で動作確認を行ってください。\\
* アップデート中はサービスが一時的に利用できなくなります。事前に利用者へのダウンタイム告知を行ってください。
  {% endhint %}

### 最新イメージの取得

更新されたイメージを取得する前に、Harbor レジストリで認証されていることを確認してください。

```bash
# Verify Harbor authentication
docker login https://cr.uneeq.io --username 'robot$your-customer-name'

# Stop services
./miniprem.sh stop

# Pull updates from Harbor registry
docker compose -f docker/docker-compose.yml pull

# Verify pulled images
docker images

# Restart with new images
./miniprem.sh start
```

`docker images` を実行すると、新しくダウンロードしたイメージと、置き換え前の古いバージョンのイメージが両方表示されます。pull が成功していることを視覚的に確認してから restart に進んでください。

### アップデート後の Healthy 確認

アップデート完了後は、全コンテナが Healthy 状態になっていることを確認します。

```bash
# Check all containers are Healthy
docker compose -f docker/docker-compose.yml ps
```

正常時は `STATUS` 列に `Up X minutes (healthy)` と表示されます。Healthy にならないコンテナがある場合は、以下で個別のログを確認してください。

```bash
# All services logs
docker compose -f docker/docker-compose.yml logs

# Specific container logs
docker compose -f docker/docker-compose.yml logs [コンテナ名]
```

### 特定バージョンへの固定（手動タグ指定）

Harbor レジストリ移行前の旧構成（DockerHub 経由）で運用しているお客様や、特定バージョンへ固定・ダウングレードしたい場合は、`docker/docker-compose.yml` を直接編集してイメージタグを指定できます。

```yaml
# 変更前の例
image: digitalhumansjp/renny:0.1.0-12345

# 変更後の例
image: digitalhumansjp/renny:0.2.0-67890
```

{% hint style="warning" %}
`renny` とバージョンタグの間のコロン（`:`）は必ず残してください。コロンを削除するとイメージ参照のフォーマットが壊れ、`docker compose pull` が失敗します。
{% endhint %}

編集後は以下の手順で反映します。

```bash
# Stop running containers
docker compose -f docker/docker-compose.yml down

# Pull the specified version
docker compose -f docker/docker-compose.yml pull

# Start with the new version
docker compose -f docker/docker-compose.yml up -d
```

### 古いイメージの削除（オプション）

Renny イメージは数 GB クラスで、アップデートを繰り返すとディスク容量を圧迫します。動作確認後に古いイメージを削除する場合は、以下のコマンドを使用します。

```bash
# 未使用イメージをすべて削除
docker image prune -a

# 特定のイメージのみ削除する場合
docker rmi [イメージID]
```

{% hint style="warning" %}
`docker image prune -a` は **使用中でないすべてのイメージ** を削除します。ロールバック用に旧バージョンを残しておきたい場合は、`docker rmi [イメージID]` で個別に削除してください。
{% endhint %}

### コンテナの再ビルド

```bash
# Force rebuild
docker compose -f docker/docker-compose.yml up -d --build

# Clean rebuild
docker compose -f docker/docker-compose.yml down
docker compose -f docker/docker-compose.yml up -d --build --force-recreate
```

## バックアップとリカバリ

### 設定のバックアップ

```bash
# Backup all configuration
tar -czf miniprem-backup-$(date +%Y%m%d).tar.gz \
  docker/configuration.dat \
  .miniprem_install_type \
  .env \
  docker/docker-compose.override.yml
```

### ボリュームのバックアップ

```bash
# List volumes
docker volume ls | grep miniprem

# Backup specific volume
docker run --rm -v miniprem_flowise_data:/data \
  -v $(pwd):/backup alpine \
  tar czf /backup/flowise-data.tar.gz /data
```

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

1. **Harbor レジストリの認証情報**:
   * ロボットアカウントの認証情報を安全に保管してください
   * Harbor の認証情報は決してバージョン管理にコミットしないでください
   * 認証情報は `~/.docker/config.json` で自動的に暗号化されます
   * 推奨に従って認証情報を定期的にローテーションしてください
   * 本番環境では、ローカルの Docker 認証情報ではなく Kubernetes Secrets を使用してください
2. **認証情報の管理**:
   * `configuration.dat` を安全に保管してください
   * 本番環境では Docker secrets を使用してください
   * JWT トークンを定期的にローテーションしてください
3. **ネットワークセキュリティ**:
   * 本番環境では、ファイアウォールで `cr.uneeq.io:443` をホワイトリストに登録してください
   * カスタム Docker ネットワークを使用してください
   * ファイアウォールルールを実装してください
   * 外部アクセスには TLS を有効化してください
4. **リソース制限**:
   * docker-compose.yml でメモリ／CPU の制限を設定してください
   * リソース使用量をモニタリングしてください
   * レート制限を実装してください

## 次のステップ

* [Flowise ワークフローの設定](/dev/miniprem/services/flowise.md)
* [MiniPrem Monitor のセットアップ](/dev/miniprem/services/miniprem-monitor.md)
* 複数の Renny インスタンスのデプロイ
* Kubernetes への移行

## サポート

問題の報告とサポートについて:

* [トラブルシューティングガイド](/dev/miniprem/troubleshooting.md) を確認してください
* コンテナイメージへのアクセスの問題は [Harbor レジストリガイド](/dev/miniprem/harbor-registry.md) を参照してください
* [コンテナログ](/dev/miniprem/api/container-logs.md) を確認してください
* [サポート窓口](https://support.digitalhumans.jp/) までお問い合わせください