> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker

> Docker Compose または Docker Swarm を使ってベアメタルまたは VM ノードに Cartesia をデプロイする

<Note>Docker Compose および Docker Swarm によるデプロイは現在**ベータ版**です。サポートが必要な場合は Cartesia チームにお問い合わせください。</Note>

Docker Compose を使って**単一マシン**上に、または Docker Swarm を使って**マルチノードクラスタ**上に Cartesia TTS をデプロイできます。

|                | Docker Compose                              | Docker Swarm                   |
| -------------- | ------------------------------------------- | ------------------------------ |
| **ノード**        | シングルホスト                                     | 複数ホスト（マネージャー + ワーカー）           |
| **GPU スケーリング** | `WORKER_REPLICAS` 経由で複数ワーカー（GPU 1 つにつき 1 つ） | ラベル付き GPU ノード上にスケジュールされるワーカー   |
| **MIG サポート**   | `--mig` フラグによる自動検出                          | ノードラベルと `--mig` フラグによりノードごとに設定 |
| **ネットワーキング**   | Bridge（デフォルト）                               | Overlay（Swarm 管理）              |

## 前提条件

* Docker がインストールされた 1 台以上のマシン（ユーザーが `docker` グループに所属している必要があります）
* **Compose のみ:** Docker Compose V2（`docker compose`）
* **Swarm のみ:** ノードが Docker の [Swarm ネットワーキング要件](https://docs.docker.com/engine/swarm/networking/)を満たすこと
* ドライバーがインストールされた NVIDIA GPU を 1 つ以上。対応する NVIDIA GPU 上では MIG（Multi-Instance GPU）パーティショニングがサポートされます
* GPU ノードで **NVIDIA Docker ランタイムがデフォルトに設定**されていること（下記参照）
* [cartesia-kube のダウンロード](/self-hosted/getting-started#downloading-kube)で説明されている `cartesia-kube` リポジトリをダウンロード済みであること
* オンボーディング時に提供される Cartesia API キーファイル（`container_key`）と GCS サービスアカウント JSON ファイル

### GPU ランタイムの確認

各 GPU ノードで NVIDIA ランタイムを確認します:

```bash theme={null}
nvidia-smi

docker info | grep "Default Runtime"
# Expected: Default Runtime: nvidia

docker run --rm nvidia/cuda:12.3.1-base-ubuntu22.04 nvidia-smi
```

`nvidia` がデフォルトランタイムでない場合は、[NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) をインストールして次を実行します:

```bash theme={null}
sudo nvidia-ctk runtime configure --runtime=docker --set-as-default
sudo systemctl restart docker
```

**MIG を使用する場合:** ホストで MIG を有効化してインスタンスを作成した後、それらが認識されていることを確認します:

```bash theme={null}
nvidia-smi -L
# Each MIG instance appears as a MIG-... UUID line beneath its parent GPU.
# The deploy script reads these UUIDs automatically — no manual configuration required.
```

<Note>デプロイ前に、ホスト側で MIG を有効化してインスタンスを作成する必要があります。MIG インスタンスを再作成すると新しい UUID が生成されるため、その場合はスタックを再デプロイしてください。</Note>

***

## ステップ 1 — シークレットの準備

以下のファイルを、ホスト（Compose）または**マネージャーノード**（Swarm）に配置します:

* `container_key` — Cartesia API キーを含むファイル
* `service-account.json` — `roles/artifactregistry.reader`（イメージ取得）および `roles/storage.objectViewer`（GCS 同期）を持つ GCS サービスアカウント JSON

デプロイスクリプトを実行可能にします:

<Tabs>
  <Tab title="Compose">
    ```bash theme={null}
    chmod +x local/scripts/deploy-compose.sh
    ```
  </Tab>

  <Tab title="Swarm">
    ```bash theme={null}
    chmod +x local/scripts/deploy-swarm.sh
    ```
  </Tab>
</Tabs>

***

## ステップ 2 — クラスタの初期化（Swarm のみ）

Docker Compose を使用する場合はこのステップをスキップしてください。

**マネージャーノード**で:

```bash theme={null}
docker swarm init --advertise-addr <MANAGER_IP>
```

出力された `docker swarm join` コマンドをコピーします。**各追加ノード**で次を実行します:

```bash theme={null}
docker swarm join --token <TOKEN> <MANAGER_IP>:2377
```

マネージャーから各ノードにラベル付けします。`docker node ls` でノード ID を一覧表示できます:

```bash theme={null}
docker node update --label-add cpu=true <node-id>   # CPU services (API, NATS, etc.)
docker node update --label-add gpu=true <node-id>   # Standard GPU workers
```

**MIG を使用する場合:** MIG が有効なノードに `mig=true` ラベルと、MIG インスタンスの UUID（そのノード上の `nvidia-smi -L` から取得）をカンマ区切りで指定したリストを付与します。MIG ノードには `gpu=true` を**付けないでください**。

```bash theme={null}
docker node update --label-add mig=true <node-id>
docker node update --label-add 'mig.uuids=MIG-<uuid1>,MIG-<uuid2>' <node-id>
```

標準 GPU ノードと MIG ノードが混在するクラスタもサポートされており、デプロイスクリプトが両方のスケジューリングを自動的に処理します。

***

## ステップ 3 — 環境の設定

デプロイ前に [環境変数](#configuration) を設定します。`local/` 配下の `.env` ファイル（`local/.env.example` 参照）を使用するか、シェルでエクスポートします。

```bash theme={null}
export IMAGE_REGISTRY="YOUR_IMAGE_REGISTRY"
export RELEASE_TAG="YOUR_RELEASE_TAG"
export MODEL_NAME="YOUR_MODEL_NAME"

export CONTAINER_KEY_FILE=/path/to/cartesia-api-key
export GCS_SA_FILE=/path/to/service-account.json

# Optional
export WORKER_REPLICAS=1
export WORKER_CAPACITY=4
export BUCKET_NAME=""
export CLUSTER_NAME="cartesia-compose"   # or "cartesia-swarm"
export USE_MIG=0                         # set to 1 to enable MIG mode (or pass --mig to the deploy script)
```

各変数の詳細は [設定](#configuration) を参照してください。

***

## ステップ 4 — デプロイ

<Tabs>
  <Tab title="Compose">
    リポジトリのルートから:

    ```bash theme={null}
    # Standard deployment
    ./local/scripts/deploy-compose.sh

    # With MIG support (auto-detects MIG instances via nvidia-smi)
    ./local/scripts/deploy-compose.sh --mig
    ```

    `--mig` を使用すると、スクリプトは `nvidia-smi` から MIG インスタンスの UUID を自動検出し、スライスごとのワーカー設定を生成し、標準ワーカーをゼロにスケールします。
  </Tab>

  <Tab title="Swarm">
    **マネージャーノード**で:

    ```bash theme={null}
    # Standard deployment
    ./local/scripts/deploy-swarm.sh

    # With MIG support (reads UUIDs from node labels)
    ./local/scripts/deploy-swarm.sh --mig
    ```

    このスクリプトは以下を行います:

    1. ノードがラベル付けされていることを確認します（されていない場合は手順を示して失敗します）。
    2. キーファイルとサービスアカウントファイルから暗号化された Swarm シークレットを作成します。
    3. すべてのサービスをデプロイします。`--mig` を使用した場合、MIG インスタンスごとに専用のワーカーサービスが作成され、それぞれが対応するノードに固定されます。
  </Tab>
</Tabs>

<Warning>
  TTS ワーカーは GPU メモリへのモデルロードに数分かかります。この間、コンテナが healthy 表示でも TTS リクエストはエラーを返します。ready シグナルを待ってください:

  <Tabs>
    <Tab title="Compose">
      ```bash theme={null}
      cd local && docker compose -f docker-compose.base.yaml -f docker-compose.yaml logs -f tts-worker 2>&1 | grep -i "ready"
      ```
    </Tab>

    <Tab title="Swarm">
      ```bash theme={null}
      docker service logs cartesia_tts-worker -f 2>&1 | grep -i "ready"
      ```
    </Tab>
  </Tabs>
</Warning>

***

## ステップ 5 — 検証

サービスが稼働しているか確認します:

<Tabs>
  <Tab title="Compose">
    ```bash theme={null}
    cd local && docker compose -f docker-compose.base.yaml -f docker-compose.yaml ps
    ```

    MIG を有効にしてデプロイした場合、各ワーカーが正確に 1 つの MIG デバイスを認識していることを確認します:

    ```bash theme={null}
    # List all running services (MIG workers appear as tts-worker-mig-0, tts-worker-mig-1, etc.)
    cd local && docker compose -f docker-compose.base.yaml -f docker-compose.yaml -f docker-compose.mig.generated.yaml ps
    ```
  </Tab>

  <Tab title="Swarm">
    ```bash theme={null}
    docker stack services cartesia
    ```

    MIG を有効にしてデプロイした場合、MIG ワーカーサービスがスケジュールされて動作しているか確認します:

    ```bash theme={null}
    docker stack ps cartesia --filter 'name=cartesia_tts-worker-mig'
    ```
  </Tab>
</Tabs>

API をテストします:

```bash theme={null}
curl http://localhost:5000/status
```

TTS をテストします:

```bash theme={null}
curl -s -X POST "http://localhost:5000/tts/bytes" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Cartesia-Version: 2024-06-10" \
  -d '{
    "model_id": "sonic-3.5",
    "transcript": "Hello from Cartesia.",
    "voice": {"mode": "id", "id": "00510a15-4216-4fdc-a0ab-05d74cd9f795"},
    "language": "en",
    "output_format": {"container": "mp3", "sample_rate": 44100, "bit_rate": 128000}
  }' --output test.mp3
```

***

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

<Tabs>
  <Tab title="Compose">
    ```bash theme={null}
    cd local

    docker compose -f docker-compose.base.yaml -f docker-compose.yaml logs api
    docker compose -f docker-compose.base.yaml -f docker-compose.yaml logs tts-worker

    # Restart everything
    docker compose -f docker-compose.base.yaml -f docker-compose.yaml down
    docker compose -f docker-compose.base.yaml -f docker-compose.yaml up -d
    ```

    API が `no servers available for connection`（NATS が未準備）で終了した場合は、スタック起動後に API を再起動します:

    ```bash theme={null}
    cd local && docker compose -f docker-compose.base.yaml -f docker-compose.yaml up -d && docker compose -f docker-compose.base.yaml -f docker-compose.yaml restart api
    ```
  </Tab>

  <Tab title="Swarm">
    ```bash theme={null}
    docker stack ps cartesia --no-trunc

    docker service logs cartesia_api
    docker service logs cartesia_tts-worker

    # Restart the stack
    docker stack rm cartesia
    sleep 10
    cd local && docker stack deploy --with-registry-auth -c docker-compose.base.yaml -c docker-compose.swarm.yaml cartesia
    ```
  </Tab>
</Tabs>

***

## 設定

デプロイスクリプト実行前に以下の環境変数を設定します。`IMAGE_REGISTRY`、`RELEASE_TAG`、`MODEL_NAME` はオンボーディング時に Cartesia から提供されます。イメージを自身のレジストリにミラーリングしている場合は、`IMAGE_REGISTRY` にミラーの URL を指定してください。

### 必須

| 変数                   | 説明                                        |
| -------------------- | ----------------------------------------- |
| `IMAGE_REGISTRY`     | コンテナイメージレジストリの URL（Cartesia レジストリまたはミラー）。 |
| `RELEASE_TAG`        | デプロイ対象リリースのイメージタグ（リリースごとに更新）。             |
| `MODEL_NAME`         | ワーカーイメージ用の TTS モデル識別子。                    |
| `CONTAINER_KEY_FILE` | Cartesia API キーを含むファイルへのパス。               |
| `GCS_SA_FILE`        | GCS サービスアカウント JSON ファイルへのパス。              |

### オプション

| 変数                  | デフォルト                                 | 説明                                                                         |
| ------------------- | ------------------------------------- | -------------------------------------------------------------------------- |
| `WORKER_REPLICAS`   | `1`                                   | TTS ワーカーコンテナの数。Compose では、ホスト上の GPU 数に設定します。Swarm では、GPU ノード数に合わせてスケールします。 |
| `WORKER_CAPACITY`   | `4`                                   | ワーカーあたりの最大同時 TTS リクエスト数。GPU メモリ不足の場合は下げてください。                              |
| `BUCKET_NAME`       | *(空)*                                 | マイグレーション／LoRA 用の GCS バケット。空のままにすると同期が無効になります。                              |
| `CLUSTER_NAME`      | `cartesia-compose` / `cartesia-swarm` | ログとメトリクス用の識別子。                                                             |
| `GCS_SYNC_INTERVAL` | `300`                                 | GCS 同期間隔（秒）。                                                               |
| `USE_MIG`           | `0`                                   | `1` に設定すると MIG モードを有効化します。                                                 |