coolify-compose

Coolify Docker Compose

標準の Docker Compose ファイルを Coolify 互換のテンプレートに変換します。認証情報の自動生成、動的 URL、ワンクリックデプロイに対応しています。

2 つのデプロイモード

Coolify では、機能が異なる 2 つの方法で Compose ファイルをデプロイできます。

1. Raw Compose（コンテンツを貼り付け）

Compose YAML を Coolify の UI に直接貼り付けます。利用できる機能は限られています。

機能	対応
image:	✅ はい
build:	❌ いいえ — 事前ビルド済みイメージを使用する必要があります
外部設定ファイル	❌ いいえ — インラインの content: を使用する必要があります
YAML アンカー（&、*）	✅ はい — YAML パーサーによって解決されます
Coolify マジック変数	✅ はい
インラインファイル用の content:	✅ はい

使用する場面： 素早いデプロイ、シンプルなサービス、カスタムイメージが不要な場合。

2. Repository モード（Git URL）

Compose ファイルを含む Git リポジトリを Coolify に指定します。Docker Compose の全機能を利用できます。

機能	対応
image:	✅ はい
build:	✅ はい — リポジトリ内の Dockerfile からビルドします
外部設定ファイル	✅ はい — 相対パスを使用できます
Coolify マジック変数	✅ はい
インラインファイル用の content:	✅ はい

使用する場面： カスタムイメージが必要な場合、複数ファイルを使う複雑な構成、リポジトリ内に既存の docker-compose.yml がある場合。

リポジトリのセットアップ：

my-service/
├── compose.yml          # or docker-compose.yml
├── custom-image/
│   ├── Dockerfile
│   └── config.sql
└── other-files/

# compose.yml - can use build:
services:
  app:
    build:
      context: ./custom-image
      dockerfile: Dockerfile

どちらのモードを使うべきですか？

元の Compose に含まれるもの	推奨モード
image: の指定のみ	どちらでも可
build: ディレクティブ	Repository モード
マウントする外部設定ファイル	Repository モード（または Raw モードで content: を使用）
シンプルな単一サービス	Raw モードのほうが高速

クイックスタート

Coolify テンプレートには、ヘッダーとマジック変数が必要です。

# documentation: https://example.com/docs
# slogan: Brief description of the service
# category: backend
# tags: api, database, docker
# logo: svgs/myservice.svg
# port: 3000

services:
  app:
    image: myapp:latest
    environment:
      - SERVICE_URL_APP_3000           # Generates URL, routes proxy to port 3000
      - DATABASE_URL=postgres://${SERVICE_USER_POSTGRES}:${SERVICE_PASSWORD_POSTGRES}@db:5432/mydb
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
      interval: 5s
      timeout: 10s
      retries: 10

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=$SERVICE_USER_POSTGRES
      - POSTGRES_PASSWORD=$SERVICE_PASSWORD_POSTGRES
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER}"]
      interval: 5s
      timeout: 10s
      retries: 10

変換チェックリスト

標準の docker-compose.yml を変換する場合：

0. build: ディレクティブを確認する

Compose に build: の項目がある場合：

• Repository モード： そのまま残します。Coolify が Dockerfile からビルドします。
• Raw モード： 事前ビルド済みの image: 指定に置き換えるか、同等のイメージを探します。

# Original with build:
services:
  custom-db:
    build: ./custom-postgres

# Raw mode: find or create pre-built image
  custom-db:
    image: your-registry.com/custom-postgres:latest

# Repository mode: keep build:, include Dockerfile in repo
  custom-db:
    build:
      context: ./custom-postgres
      dockerfile: Dockerfile

1. ヘッダーメタデータを追加する

# documentation: https://...    # Required: URL to official docs
# slogan: ...                   # Required: One-line description  
# category: ...                 # Required: backend, cms, monitoring, etc.
# tags: ...                     # Required: Comma-separated search terms
# logo: svgs/....svg            # Required: Path in Coolify's svgs/ folder
# port: ...                     # Recommended: Main service port

2. ハードコードされた認証情報を置き換える

# ❌ Before
POSTGRES_PASSWORD=mysecretpassword
POSTGRES_USER=admin

# ✅ After  
POSTGRES_PASSWORD=$SERVICE_PASSWORD_POSTGRES
POSTGRES_USER=$SERVICE_USER_POSTGRES

3. URL をマジック変数に置き換える

# ❌ Before
APP_URL=https://myapp.example.com

# ✅ After
- SERVICE_URL_APP_3000    # Declares URL + proxy routing
- APP_URL=$SERVICE_URL_APP  # References it

4. プロキシ経由のサービスでは ports: を削除する

Coolify の Traefik プロキシがルーティングを処理します。ports: は、SSH、UDP、またはプロキシを経由しない接続にのみ残します。

# ❌ Before
ports:
  - "3000:3000"

# ✅ After
environment:
  - SERVICE_URL_APP_3000  # Proxy routes to container port 3000
# No ports: needed

5. ヘルスチェックを追加する

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 5s
  timeout: 10s
  retries: 10

6. 条件付きの depends_on を使用する

depends_on:
  db:
    condition: service_healthy

マジック変数リファレンス

Coolify は SERVICE_<TYPE>_<IDENTIFIER> を使用して値を生成します。

タイプ	例	結果
PASSWORD	SERVICE_PASSWORD_DB	ランダムなパスワード
PASSWORD_64	SERVICE_PASSWORD_64_KEY	64 文字のパスワード
USER	SERVICE_USER_ADMIN	ランダムな 16 文字の文字列
BASE64_64	SERVICE_BASE64_64_SECRET	ランダムな 64 文字の文字列
REALBASE64_64	SERVICE_REALBASE64_64_JWT	実際に Base64 エンコードされた文字列
HEX_32	SERVICE_HEX_32_KEY	64 文字の 16 進数文字列
URL	SERVICE_URL_APP_3000	https://app-uuid.example.com + プロキシ
FQDN	SERVICE_FQDN_APP	app-uuid.example.com（スキームとポートの接尾辞なし）

宣言と参照（重要）

SERVICE_URL では、ポートの接尾辞でプロキシのルーティングを設定しますが、変数名には含まれません。

# Declare WITH port suffix (configures proxy to route to port 3000)
- SERVICE_URL_MYAPP_3000

# Reference WITHOUT port suffix (gets the URL value)
- APP_URL=$SERVICE_URL_MYAPP
- WEBHOOK_URL=${SERVICE_URL_MYAPP}/webhooks

SERVICE_URL を宣言すると SERVICE_FQDN も自動的に使用できるため、別途宣言する必要はありません。

# This single declaration...
- SERVICE_URL_MYAPP_3000

# ...makes BOTH of these available:
- FULL_URL=$SERVICE_URL_MYAPP           # https://myapp-uuid.example.com
- HOSTNAME=${SERVICE_FQDN_MYAPP}        # myapp-uuid.example.com

⚠️ 重要： ポート番号の前にはアンダースコアではなくハイフンを使用してください。

SERVICE_URL_MY_SERVICE_3000  # ❌ Breaks parsing
SERVICE_URL_MY-SERVICE_3000  # ✅ Works

一覧については、references/magic-variables.md を参照してください。

Coolify 固有の拡張機能

ディレクトリを作成する

volumes:
  - type: bind
    source: ./data
    target: /app/data
    is_directory: true  # Coolify creates this

コンテンツを含むファイルを作成する

外部ファイルを参照できないRaw モードで便利です。Repository モードでは、通常どおりファイルをマウントできます。

# Raw mode: embed file content inline
volumes:
  - type: bind
    source: ./config.json
    target: /app/config.json
    content: |
      {"key": "${SERVICE_PASSWORD_APP}"}

# Repository mode: reference actual file in repo
volumes:
  - ./config/settings.json:/app/config.json:ro

ヘルスチェックの対象から除外する

実行後に終了する移行／初期化用コンテナの場合：

services:
  migrate:
    command: ["npm", "run", "migrate"]
    exclude_from_hc: true

よくあるパターン

データベース接続

environment:
  - DATABASE_URL=postgres://${SERVICE_USER_POSTGRES}:${SERVICE_PASSWORD_POSTGRES}@db:5432/${POSTGRES_DB:-myapp}

共有認証情報

同じ SERVICE_PASSWORD_* 識別子には、すべてのサービスで同じ値が使われます。

services:
  app:
    environment:
      - DB_PASS=$SERVICE_PASSWORD_POSTGRES
  db:
    environment:
      - POSTGRES_PASSWORD=$SERVICE_PASSWORD_POSTGRES  # Same value

複数サービスの URL

services:
  frontend:
    environment:
      - SERVICE_URL_FRONTEND_3000
      - API_URL=$SERVICE_URL_API
  api:
    environment:
      - SERVICE_URL_API_8080=/api  # Path suffix

ヘルスチェックのパターン

# HTTP
test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080"]

# PostgreSQL
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]

# MySQL/MariaDB  
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]

# Redis
test: ["CMD", "redis-cli", "ping"]

# Always pass (use sparingly)
test: ["CMD", "echo", "ok"]

環境変数の構文

environment:
  - NODE_ENV=production           # Hardcoded, hidden from UI
  - API_KEY=${API_KEY}            # Editable in UI (empty)
  - LOG_LEVEL=${LOG_LEVEL:-info}  # Editable with default
  - SECRET=${SECRET:?}            # Required - blocks deploy if empty

トラブルシューティング

問題	解決策
「No Available Server」エラー	docker ps で異常なコンテナーがないか確認し、ヘルスチェックが通ることを確認します
Coolify の UI に変数が表示されない	${VAR} 構文を使います。ハードコードされた VAR=value は表示されません
マジック変数が生成されない	スペルを確認し、SERVICE_ プレフィックスが付いていること、および Coolify v4.0.0-beta.411+ を使っていることを確認します
ポートルーティングが機能しない	SERVICE_URL_NAME_PORT を使います。ポートの前にアンダースコアを入れないでください。また、ports: を削除します

例

まず、公式テンプレートがないか確認してください。 多くの人気サービスには、github.com/coollabsio/coolify/tree/main/templates/compose に Coolify の公式テンプレートがあります。テンプレートがある場合は、適切なパターンを確認するための参考として使用してください。

公式テンプレートがない compose ファイルを変換する場合は、内容を分析し、該当する例を使用してください。

Compose ファイルの内容	使用する例
1 つのサービス、データベースなし	examples/simple/
2 つのサービス：アプリ＋データベース（postgres/mysql/mariadb）	examples/with-database/
3 つ以上のサービス、またはマウントされた設定ファイル、または複数のデータベース	examples/multi-service/

簡単な分析：

• services: の数を数えます。1 つだけなら simple/ を使います
• postgres、mysql、mariadb、mongo のイメージを探します。データベースが 1 つなら with-database/ を使います
• マウントされた .xml、.json、.yml の設定ファイルを探します。ある場合は multi-service/ を使います
• clickhouse、redis、複数のデータベースを探します。該当する場合は multi-service/ を使います

参考資料

• references/magic-variables.md — 変数の種類に関する完全なリファレンス
• references/categories.md — 有効なカテゴリ値
• Coolify の公式 Compose ドキュメント — 信頼できる公式ドキュメント
• 公式サービステンプレート — 適切なパターンのリファレンス実装