dokploy-docker-compose

Dokploy Docker Compose デプロイメントスキル

概要

Dokploy は、VPS 上の Docker コンテナを管理するセルフホスト可能なデプロイメントプラットフォームです。2 つの Compose モード（Docker Compose と Docker Stack）をサポートしており、確実に動作させるには特定のパターンに従う必要があります。

クイック判断フロー：

• Dockerfile を含む単一リポジトリのアプリ？ → Application（Git） デプロイメント
• 事前ビルド済みイメージまたは複数サービスのスタック？ → Compose デプロイメント
• パブリック HTTPS ドメインが必要？ → Domains タブ（Dokploy が Traefik ラベルを自動挿入します）
• アプリごとにネットワークを分離したい？ → UI で Isolated Deployments を有効化
• SSH なしで設定ファイルが必要？ → Advanced → Mounts の File Mounts
• 設定ファイルの生成とバイナリのダウンロードが必要な複雑なスタック？ → Init Containers パターン

---

パート 1：サービスの種類

Compose（Docker Compose モード）

最適な用途：事前ビルド済みイメージを使う複数サービスのスタック。標準的な docker compose up の動作です。

ローカルで実行する場合と比べた主な制約：

• AutoDeploy による各デプロイでは git clone が実行され、リポジトリディレクトリが消去されます。そのため、./config.yaml のような相対パスは最初のプッシュ後に空になるか、存在しなくなります
• サービスに container_name: を使用しないでください。Dokploy のログ、メトリクス、監視機能が動作しなくなります
• 相対バインドマウント（./data）が機能するのは初回デプロイ時のみです。代わりに ../files/ または名前付きボリュームを使用してください

Stack（Docker Swarm モード）

オーケストレーションされたデプロイメント向けの Docker Stack モードです。Compose モードとの主な違い：

• build: ディレクティブは使用できません。レジストリの事前ビルド済みイメージを使用する必要があります
• Traefik ラベルは labels ではなく、deploy.labels の下に指定する必要があります
• レプリカでプライベートレジストリを使用する場合は、Advanced → Command で --with-registry-auth フラグを追加します

Application（Git）デプロイメント

最適な用途：Dockerfile からビルドするソースコードです。

手順：Create Service → Application → Source: Git → Build Type: Dockerfile を選択し、Advanced で Volumes と Ports を設定します。

---

パート 2：ボリューム戦略

⚠️ Dokploy の重要なルール： 絶対ホストパス（例：/opt/myapp/）はデプロイ時にクリーンアップされます。絶対に使用しないでください。代わりに ../files/ フォルダーまたは名前付きボリュームを使用してください。

名前付きボリューム（データベースや大容量データに最適）

services:
  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

これらは Docker が管理します。Dokploy の Volume Backups 機能を使った自動バックアップに対応しています。データベースや大規模なデータセットに最適です。

../files/ バインドマウント（設定ファイルや少量のデータに最適）

Dokploy は、デプロイ後も維持される ../files/ フォルダーを提供します。

volumes:
  - ../files/my-config:/etc/myapp/config    ✅ persists across deploys
  - ../files/my-database:/var/lib/mysql     ✅ persists across deploys
  - ./config.yaml:/app/config.yaml          ❌ wiped on each AutoDeploy (git clone)
  - /opt/myapp/data:/app/data               ❌ absolute paths are cleaned up by Dokploy

ホスト上のファイルに直接アクセスする必要はありません。設定ファイルや小規模なデータセットに最適です。バックアップには対応していません。

VPS 上のホストパス： ../files/ は、ホスト上の Dokploy プロジェクトディレクトリ内にある files/ フォルダーに対応します。初回デプロイ後に正確なパスを確認するには、SSH で接続して次を実行します。

# Step 1: find your container name (Dokploy names them <stack>-<service>-1)
docker ps --format "table {{.Names}}\t{{.Image}}" | grep <service-keyword>

# Step 2: inspect that container to see where ../files/ maps on the host
docker inspect <container-name> | grep -A2 '"Source"'

または、Dokploy UI の Docker タブを確認してください。コンテナ名がそこに直接表示されます。

File Mounts（Dokploy UI — 設定内容を直接貼り付ける場合）

Advanced → Mounts → Add Mount → File Mount で設定します。

• Content：ファイルのテキストを貼り付けます
• File Path：ファイル名のみ（例：config.yaml）
• Mount Path：コンテナ内の完全なパス（例：/app/config/config.yaml）

✅ 最適な用途：Dokploy UI ですべて管理したい設定ファイル ❌ 適さない用途：バイナリファイル、実行時に生成する必要があるファイル、数 KB を超えるファイル

Init Container パターン（設定ファイルの生成が必要な複雑なスタック向け）

実行時に複数の設定ファイルを書き込む必要がある場合や、バイナリをダウンロードする必要がある場合は、メインサービスの起動前に共有の名前付きボリュームへファイルを書き込む alpine 初期化コンテナを使用します。

services:
  my-conf:
    image: alpine:3.20
    command:
      - /bin/sh
      - -lc
      - |
        cat > /config/app.yaml <<'YAML'
        key: value
        YAML
        apk add --no-cache wget && wget -O /scripts/tool "https://..."
    volumes:
      - app-config:/config
      - app-scripts:/scripts
    restart: "no"   # MUST exit after running

  app:
    depends_on:
      my-conf:
        condition: service_completed_successfully
    volumes:
      - app-config:/etc/app/
      - app-scripts:/usr/local/scripts/

シェルのエスケープ： Compose のヒアドキュメント内では $$ を使用します。$(uname -s) ではなく $$(uname -s) としてください。

完全な例については references/init-container-patterns.md を参照してください。

適切なボリューム方式の選択

必要なもの	方式
データベースデータ	名前付きボリューム
S3 への自動バックアップ	名前付きボリューム（唯一の選択肢）
設定ファイル — UI で管理	ファイルマウント
設定ファイル — 大規模または複雑	../files/ バインドマウント
生成された設定ファイルとバイナリ	初期化コンテナ → 名前付きボリューム
❌ 使用しないでください	絶対ホストパス、./ 相対パス

---

パート 3：環境変数

Dokploy における環境変数の扱い

Environment タブで設定した変数は、docker-compose.yml と同じディレクトリにある .env ファイルに書き込まれます。コンテナに自動的に注入されるわけではありません。以下のいずれかの方法で、compose YAML に明示的に読み込む必要があります。

方法 A — すべての変数を読み込む（変数が多い場合に簡単です）：

services:
  app:
    env_file:
      - .env        # loads every variable from Dokploy's Environment tab

方法 B — 特定の変数を選択する：

services:
  app:
    environment:
      - JWT_SECRET=${JWT_SECRET}
      - DATABASE_URL=${DATABASE_URL}
      - PORT=3000                   # hardcoded values also work

⚠️ environment: で変数を明示的に指定した場合、渡されるのはリストに記載された変数のみです。UI で設定されていても、ここに記載されていない変数は通知なく無視されます。

推奨事項： 多くのシークレットを使うスタック（LibreChat など）では、必要な各サービスに env_file: - .env を指定してください。サービスごとに必要な変数が異なるスタックでは、明示的に ${VAR} を参照してください。

セキュアな値の生成

openssl rand -hex 32    # 64-char hex string (for keys like CREDS_KEY)
openssl rand -hex 16    # 32-char hex string (for IVs like CREDS_IV)

---

パート 4：ドメインと Traefik ルーティング

Dokploy は Traefik をリバースプロキシとして使用します。ドメイン経由でサービスを公開する方法は 2 つあります。

方法 1：Dokploy の Domains UI（推奨 — v0.7.0 以降）

サービスを開き、→ Domains タブ → Add Domain を選択します。Dokploy はデプロイ時に、適切な Traefik ラベルを compose ファイルへ自動的に挿入します。ラベルを手動で編集する必要はありません。

⚠️ 先にデプロイし、その後でドメインを追加してください。 Domains タブを使うにはサービスが起動している必要があるため、初回デプロイ前にドメインを追加することはできません。

• ドメイン経由でルーティングする場合は、compose YAML で ports: ではなく expose: を使用します
• Preview Compose ボタンで、自動挿入されたラベルを含む最終的な compose ファイルを確認できます
• HTTPS：DNS を直接設定する場合（A レコード → VPS）は有効にします。Cloudflare プロキシ経由の場合は無効にし、Cloudflare の SSL/TLS を「Full」に設定します

services:
  app:
    image: myapp:latest
    expose:
      - 3000    # container-only; Traefik routes via domain, no host port needed

方法 2：Traefik ラベルを手動で設定（上級者向け）

細かく制御するには、compose ファイルにラベルを直接追加します。これには、共有 Traefik ネットワークである dokploy-network への接続が必要です。

services:
  frontend:
    image: myapp:latest
    expose:
      - 3000
    networks:
      - dokploy-network
    labels:
      - traefik.enable=true
      - traefik.http.routers.my-unique-name.rule=Host(`app.yourdomain.com`)
      - traefik.http.routers.my-unique-name.entrypoints=websecure
      - traefik.http.routers.my-unique-name.tls.certResolver=letsencrypt
      - traefik.http.services.my-unique-name.loadbalancer.server.port=3000

networks:
  dokploy-network:
    external: true

Docker Stack の場合 — ラベルは deploy.labels の下に指定します。

services:
  frontend:
    image: myapp:latest
    deploy:
      labels:
        - traefik.enable=true
        - traefik.http.routers.my-app.rule=Host(`app.yourdomain.com`)
        - traefik.http.services.my-app.loadbalancer.server.port=3000
    networks:
      - dokploy-network

分離デプロイ

Dokploy UI でこれを有効にすると（Compose サービスページのトグルをオンにします）、スタックは dokploy-network を共有せず、専用のプライベートネットワークを使用します。これは次の点で有用です。

• 複数のインスタンス（例：2 つの WordPress サイト）を実行する場合に必須です
• より安全です。サービスがほかのスタックから見えなくなります
• 自動で設定されます。Dokploy がネットワークの作成と Traefik との接続をすべて処理します

分離デプロイが有効な場合、dokploy-network を手動で追加する必要はありません。 Dokploy に同梱されているすべてのオープンソーステンプレートでは、デフォルトで有効になっています。

⚠️ 分離デプロイを使用しない場合、ドメインの宛先となるサービスにのみ dokploy-network が自動的に追加されます。スタック内のほかのサービスは、手動で追加しない限り、このネットワークに接続されません。

---

パート 5：ネットワークと DNS（EAI_AGAIN の修正）

複数サービス構成で最もよく発生するエラー：

getaddrinfo EAI_AGAIN mongodb

コンテナが別のサービスのホスト名を解決できません。原因：競合状態または DNS の混乱です。

修正 1 — ヘルスチェックと適切な depends_on（競合状態を防止）：

services:
  api:
    depends_on:
      mongodb:
        condition: service_healthy    # waits until healthy, not just started
  mongodb:
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
      interval: 10s
      retries: 5
      start_period: 10s

修正 2 — 明示的なカスタムネットワーク（サービス間の DNS を保証）：

networks:
  app-net:
    driver: bridge

services:
  api:
    networks: [app-net]
  mongodb:
    networks: [app-net]

⚠️ DNS の回避策として container_name: を使用しないでください。Dokploy の監視機能が動作しなくなります。コンテナ間通信にはサービス名を使用してください。

---

パート 6：ヘルスチェック

すべての依存サービス（データベース、キャッシュ、キュー）に healthcheck を追加します。これらを必要とするサービスには depends_on: condition: service_healthy を指定してください。これにより、依存サービスの準備が整う前にサービスが起動する競合状態を防止できます。

例：

services:
  postgres:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
  app:
    depends_on:
      postgres:
        condition: service_healthy

---

パート 7：デプロイ済みサービスの更新

手動更新（所有していない公開リポジトリ）

1. Deployments タブに移動 → Deploy をクリックします
2. Docker キャッシュが古い場合：「Redeploy without Cache」を探すか、System Settings で Build Cache をクリアします

Webhook による自動更新

1. Deployments タブから Webhook URL をコピーします
2. GitHub/GitLab/Gitea リポジトリの Settings → Webhooks に追加します
3. ブランチへのプッシュごとに、自動デプロイが実行されます

---

Part 8: よくあるエラーと修正方法

エラー	原因	修正方法
getaddrinfo EAI_AGAIN <hostname>	競合状態／DNS	ヘルスチェックと condition: service_healthy を追加します。カスタムネットワークを使用します
再デプロイ後に設定ファイルが空になる	./ 相対パスが git clone によって消去された	../files/ バインドマウントまたは UI の File Mount を使用します
JwtStrategy requires a secret or key	JWT 環境変数が注入されていない	env_file: - .env または明示的な - JWT_SECRET=${JWT_SECRET} を追加します。再起動ではなく再デプロイします
ENOENT: no such file or directory	設定ファイルがマウントされていない	Advanced → Mounts の File Mount、または ../files/ バインドマウントを使用します
ボリュームで permission denied が発生する	別のユーザーが作成した古いボリューム	ボリューム名を変更し（例：data-v2）、新規作成を強制します
コンテナが is unhealthy になる	イメージに適さないヘルスチェック	ヘルスチェックコマンドをイメージの種類に合わせます。Part 6 を参照してください
Dokploy でログ／メトリクスが表示されない	サービスに container_name: が設定されている	container_name: を削除します。Dokploy の監視が機能しなくなります
ドメイン追加後にサービス同士が通信できない	同じネットワークに接続されていない	Isolated Deployments を使用するか、すべてのサービスに dokploy-network を手動で追加します

---

Part 9: 参考ファイル

• references/sop-compose-deployment.md — 任意のマルチサービス Compose スタックをデプロイする手順を説明した SOP
• references/sop-git-deployment.md — Dockerfile を使用して Git からデプロイする方法
• references/librechat-example.md — LibreChat：JWT シークレット、MongoDB DNS、librechat.yaml のマウント
• references/signoz-example.md — SigNoz：初期化コンテナ、ClickHouse、Zookeeper の移行
• references/init-container-patterns.md — heredoc とバイナリダウンロードを使用した初期化コンテナのパターン
• references/healthchecks.md — 一般的なサービス向けのヘルスチェックの例

---

クイックチェックリスト：任意の docker-compose.yml を Dokploy 用に調整する

• すべての container_name: を削除します — Dokploy のログとメトリクスが機能しなくなります
• ./ 相対バインドマウントを ../files/ または名前付きボリュームに置き換えます
• 絶対ホストパス（/opt/...）は使用しません — デプロイ時に削除されます
• user: "${UID}:${GID}" を削除します — Dokploy で権限エラーが発生します
• env_file: - ./.env を削除します — ファイルが存在しません。env_file: - .env（./ なし）または ${VAR} 構文を使用します
• すべてのシークレットに対して env_file: - .env または明示的な ${VAR} 参照を追加します — 環境変数は自動注入されません
• すべてのデータベース／依存サービスにヘルスチェックを追加します
• depends_on を更新し、サービス名だけでなく condition: service_healthy を使用します
• ドメインの場合：カスタム Traefik 設定が必要でない限り、Dokploy の Domains タブ（Method 1）を使用します
• Traefik ドメイン経由でルーティングするサービスには（ports: ではなく）expose: を使用します
• すべての名前付きボリュームをファイルの末尾で宣言します