zeabur-template

Zeabur テンプレートナレッジベース

Zeabur CLI の実行には、必ず npx zeabur@latest を使用してください。 zeabur を直接実行したり、ほかのインストール方法を使用したりしないでください。npx が利用できない場合は、先に Node.js をインストールしてください。

このスキルでは、Zeabur テンプレートの作成、デバッグ、公開に関する包括的な知識を提供します。リファレンスドキュメントと、実際のテンプレート開発で検証されたパターンを組み合わせています。

外部ドキュメント

最新のスキーマや詳細なドキュメントについては、https://raw.githubusercontent.com/zeabur/zeabur-template-doc/main/ から取得してください。

ユーザーのニーズ	取得するドキュメント	パス
テンプレートをゼロから作成する	ステップごとのガイド	docs/GUIDE.md
docker-compose.yml を変換する	移行ガイド	docs/DOCKER_COMPOSE_MIGRATION.md
YAML フィールドや組み込み変数を調べる	技術リファレンス	docs/REFERENCE.md
命名、設計パターン、ベストプラクティスを確認する	ベストプラクティス	docs/BEST_PRACTICES.md
テンプレートのエラーをデバッグする	トラブルシューティング	docs/TROUBLESHOOTING.md
デプロイ前チェックリストを確認する	チェックリスト	docs/CHECKLIST.md
簡潔なオールインワンの概要を確認する	包括的なプロンプト	prompt.md

テンプレートの YAML スキーマは https://schema.zeabur.app/template.json に、ビルド済みサービスのスキーマは https://schema.zeabur.app/prebuilt.json にもあります。

---

基本原則

0. すべてのサービスで Docker イメージを使用した PREBUILT_V2 を必須とします

テンプレート内のすべてのサービスは、Docker イメージをソースとする template: PREBUILT_V2 でなければなりません。 template: GIT、ARBITRARY_GIT、GITHUB のソースはテンプレートでサポートされていないため、使用しないでください。

プロジェクトに公開済みの Docker イメージ（Docker Hub、GHCR など）がない場合は、テンプレートを作成する前に Docker イメージをビルドして公開する必要があることをユーザーに伝えてください。回避策を試みてはいけません。

ユーザーからイメージのビルドを依頼された場合は、次の手順に従ってください。

1. プロジェクトのリポジトリをクローンし、Dockerfile を探します（通常はリポジトリのルートにあります）。
2. Dockerfile を調べてビルドステージを把握し、本番ステージ（多くの場合、runner または production という名前）を使用します。
3. docker-compose.yml または docker-compose.fullapp.yml を調べて、正しい起動コマンド、環境変数、ボリュームを確認します。これが実環境で検証された本番用設定です。
4. amd64 向けにビルドします（Zeabur のサーバーは amd64、ローカルの Mac は arm64 です）。

   docker buildx build --platform linux/amd64 --target runner -t org/image:tag --push .
   

5. プッシュ後、Docker Hub のリポジトリが公開されていることを確認します。

   curl -s "https://hub.docker.com/v2/repositories/ORG/IMAGE/" | grep is_private
   

   組織アカウントで新しく作成したリポジトリは、初期設定で非公開になっていることがよくあります。is_private: true の場合、ユーザーは Docker Hub で公開に設定する必要があります。

1. ゼロから始めない

テンプレートの作成を依頼された場合は、まず既存の設定を必ず探してください。

• 最初に Docker イメージがあるか確認します。Docker Hub、GHCR（ghcr.io/org/repo）、またはプロジェクトの CI/CD を調べて、公開済みのイメージを探します。見つからない場合は、そこで作業を止めてユーザーに伝えてください。
• プロジェクトの docker-compose.yml、docker-compose.yaml、または compose.yml を探します。
• Helm チャート（Chart.yaml、values.yaml）を探します。
• プロジェクトの GitHub リポジトリで、デプロイ用の YAML ファイルがないか確認します。
• これらは参考として軽く扱うのではなく、Zeabur テンプレートを構築する際の土台として使用してください。実環境で検証された環境変数、ポートマッピング、ボリュームマウント、サービス依存関係が含まれています。

2. 実行時ログを見ながら反復する — 一度で成功するとは限りません

経験豊富な人でも、動作するテンプレートを一度で作成することはできません。作業は反復的なループになります。

1. テンプレートの YAML を作成または更新します。
2. テンプレートをデプロイします。
3. 多くの場合、失敗します。実行時ログを確認して原因を特定します。
4. テンプレートの問題を修正します。
5. プロジェクトを削除し、最初から再デプロイします。
6. テンプレートがワンクリックで正常にデプロイできるようになるまで繰り返します。

これは通常の手順であり、失敗を意味するものではありません。デプロイ前にすべてを完璧にしようとせず、早めにデプロイしてログを確認し、反復してください。

3. 既存のテンプレートから再利用する — 共通サービスを一から作成しない

テンプレートで一般的なサービス（PostgreSQL、Redis、MySQL、MongoDB など）が必要な場合は、サービス定義を自分で記述しないでください。代わりに、次の手順を行います。

1. そのサービスをすでに使用している既存のテンプレートを検索します。

   npx zeabur@latest template search postgres
   

2. 必要なサービスを含むテンプレートを見つけます。
3. テンプレートの生の YAML を取得し、サービス定義の正確な内容を確認します。

   npx zeabur@latest template get -c TEMPLATE_CODE --raw
   

4. そのテンプレートからサービス定義を直接コピーして、自分のテンプレートに貼り付けます。

テンプレートの信頼性を判断する方法：

• 多くのテンプレートは一般ユーザーが作成したもので、正しく動作しない場合があります。
• デプロイ数の多いテンプレートを優先してください — デプロイ数が多いほど、実環境での検証が進んでいます。
• ユーザー投稿のテンプレートより公式テンプレートを優先してください — 公式テンプレートは Zeabur チームによって審査されています。

---

イテレーションループ用の CLI コマンド

テンプレートをデプロイする：

npx zeabur@latest template deploy -f YOUR_TEMPLATE.yaml

非対話モード（自動化）の場合：

npx zeabur@latest template deploy -i=false \
  -f YOUR_TEMPLATE.yaml \
  --project-id PROJECT_ID \
  --var PUBLIC_DOMAIN=myapp

サービスを一覧表示する（SERVICE_ID を取得するため）：

npx zeabur@latest service list --project-id PROJECT_ID

実行時のログを確認する：

npx zeabur@latest deployment log --service-id SERVICE_ID

実行中のサービス内でコマンドを実行する（docker exec のように）：

npx zeabur@latest service exec --id SERVICE_ID -- SHELL_COMMAND

デバッグに非常に役立ちます — ファイルパスや環境変数の確認、接続テスト、ファイルシステムの調査などに利用できます。例：

npx zeabur@latest service exec --id SERVICE_ID -- ls /app
npx zeabur@latest service exec --id SERVICE_ID -- env | grep DATABASE
npx zeabur@latest service exec --id SERVICE_ID -- nc -z localhost 5432

サービスを再起動する（ImagePullBackOff の解消や、イメージの再取得に便利です）：

npx zeabur@latest service restart --id SERVICE_ID -i=false -y

プロジェクトを削除して最初からやり直す：

npx zeabur@latest project delete --id PROJECT_ID

危険な操作 — プロジェクトを削除する前に、必ずユーザーに明示的な確認を求め、Project ID、Name、createdAt のタイムスタンプをはっきりと伝えてください。確認なしに削除してはいけません。

新しいテンプレートを公開する：

npx zeabur@latest template create -f YOUR_TEMPLATE.yaml

これにより、テンプレートコードを含む https://zeabur.com/templates/XXXXXX のようなテンプレート URL が返されます。

既存のテンプレートを更新する：

npx zeabur@latest template update -c TEMPLATE_CODE -f YOUR_TEMPLATE.yaml

---

クイックリファレンス：テンプレートのスケルトン

# yaml-language-server: $schema=https://schema.zeabur.app/template.json
apiVersion: zeabur.com/v1
kind: Template
metadata:
  name: ServiceName
spec:
  description: |
    English description (1-3 sentences)
  icon: https://raw.githubusercontent.com/zeabur/service-icons/main/marketplace/service.svg
  coverImage: https://example.com/cover.webp
  tags:
    - Category
  variables: []
  readme: |
    # Service Name
    English documentation...
  services:
    - name: service-name
      icon: https://raw.githubusercontent.com/zeabur/service-icons/main/marketplace/service.svg
      template: PREBUILT_V2
      spec:
        source:
          image: image:tag
          command:              # MUST be inside source, alongside image
            - /bin/sh
            - -c
            - /opt/app/startup.sh
        ports:
          - id: web
            port: 8080
            type: HTTP
        portForwarding:
          enabled: true        # Auto-expose TCP/UDP ports externally (default: true)
        healthCheck:              # ensures port is ready before dependents start
          type: TCP
          port: web               # references the port ID above
        volumes:
          - id: data
            dir: /path/to/data
        configs:
          - path: /opt/app/startup.sh
            permission: 493     # 0755
            envsubst: false
            template: |
              #!/bin/sh
              exec node server.js
        env:
          VAR_NAME:
            default: value
            expose: true
localization:
  zh-TW:
    description: ...
    variables: []
    readme: |
      # ...
  zh-CN:
    description: ...
    variables: []
    readme: |
      # ...
  ja-JP:
    description: ...
    variables: []
    readme: |
      # ...
  es-ES:
    description: ...
    variables: []
    readme: |
      # ...
  id-ID:
    description: ...
    variables: []
    readme: |
      # ...

クイックリファレンス：組み込み変数

変数	用途
${PASSWORD}	自動生成される安全なパスワード
${ZEABUR_WEB_URL}	完全な公開 URL（例：https://app.zeabur.app）
${ZEABUR_WEB_DOMAIN}	ドメインのみ（例：app.zeabur.app）
${CONTAINER_HOSTNAME}	サービス間通信に使用する内部ホスト名
${[PORTID]_PORT}	ポート ID に対応するポート値（例：${DATABASE_PORT}）
${PORT_FORWARDED_HOSTNAME}	ポート転送用の外部ホスト名（有効にすると自動設定され、環境変数や instructions で使用可能）
${[PORTID]_PORT_FORWARDED_PORT}	外部に転送されるポート番号（有効にすると自動設定され、環境変数や instructions で使用可能）

ZEABUR_<PORT_ID>_URL の形式：ポート名が web の場合は ${ZEABUR_WEB_URL} に、console の場合は ${ZEABUR_CONSOLE_URL} になります。

クイックリファレンス：command の配置場所

重要：command は spec レベルではなく、image と同じ階層の source 内に必ず配置してください。

# WRONG -- command at spec level (will be IGNORED, container uses default CMD)
spec:
  source:
    image: python:3.12-slim
  command:
    - /bin/sh
    - -c
    - /opt/app/start.sh

# CORRECT -- command inside source
spec:
  source:
    image: python:3.12-slim
    command:
      - /bin/sh
      - -c
      - /opt/app/start.sh

注： 外部ドキュメントでは command が spec レベルに配置されている場合がありますが、これは誤りです。schema.zeabur.app/prebuilt.json の JSON スキーマで確認されているとおり、command は必ず source 内に配置してください。

クイックリファレンス：YAML の注意点

# RISKY -- @ at start of value is a YAML reserved indicator (may cause parse errors)
description: @BotFather token

# SAFE -- quote the value or avoid @ at start
description: "Token from @BotFather for Telegram bot"
description: Telegram bot token from BotFather

クイックリファレンス：Docker イメージの ENTRYPOINT

一部のベースイメージでは ENTRYPOINT が設定されており、command と競合します。

イメージ	ENTRYPOINT	問題
ghcr.io/astral-sh/uv:python3.12-*	uv	command が uv の引数になり、コンテナに uv help が表示されて終了します
node:*	なし	安全に使用できます
python:*	なし	安全に使用できます

ENTRYPOINT が設定されたイメージを使用する場合は、プレーンなベースイメージ（例：python:3.12-slim-bookworm）か、ENTRYPOINT のないイメージに切り替えてください。

クイックリファレンス：TCP サービス（プロキシ、データベース、ゲームサーバーなど）

HTTP プロキシ（Tinyproxy、Squid）、データベース、ゲームサーバー、VPN サーバーなど、クライアントが TCP/UDP 経由で直接接続する Web アプリではないサービスでは、HTTP ポートタイプや domainKey を使用しないでください。代わりに、次のようにします。

1. type: TCP（または UDP）を使用する — これにより、Zeabur のリバースプロキシ（Ingress）がトラフィックをインターセプトしなくなります。
2. portForwarding: enabled: true を設定する — ポートが自動的に外部公開され、クライアントが直接接続できるようになります。
3. domainKey を使用しない — TCP サービスにドメインは不要です。ユーザーは転送されたホスト名とポートを使って接続します。

# CORRECT -- TCP service (e.g. HTTP proxy, database, game server)
spec:
  source:
    image: some/tcp-service:latest
  ports:
    - id: proxy
      port: 8888
      type: TCP          # NOT HTTP — clients connect directly
  portForwarding:
    enabled: true        # Auto-expose this port externally
  env:
    # ...

# WRONG -- using HTTP type for a TCP proxy
spec:
  ports:
    - id: proxy
      port: 8888
      type: HTTP         # Zeabur's Ingress will intercept CONNECT requests
  # Missing portForwarding — users must manually enable in Dashboard

HTTP を使わない理由： Zeabur の HTTP ポートタイプは、TLS を終端し、Host ベースのルーティングを行うリバースプロキシ（Ingress/Envoy）経由でトラフィックをルーティングします。これにより、HTTP CONNECT（プロキシで使用）、生の TCP ストリーム（データベース）、カスタムバイナリプロトコル（ゲームサーバー）などのプロトコルが動作しなくなります。

ポートフォワーディングの変数（instructions または readme で使用）：

• ${PORT_FORWARDED_HOSTNAME} — 外部ホスト名
• ${PROXY_PORT_FORWARDED_PORT} — 外部ポート（パターン：${[PORTID]_PORT_FORWARDED_PORT}）

TCP サービスのデプロイ後のテスト：

TCP サービスのデプロイ後、ポートフォワーディングが機能していることを確認します。

1. まず、内部接続を確認します（コンテナ内から実行）：

   npx zeabur@latest service exec --id SERVICE_ID -- curl -x http://127.0.0.1:8888 https://ifconfig.co
   

2. ダッシュボードのNetworkingタブから転送先のホストとポートを取得するか、次のコマンドを使用します：

   npx zeabur@latest service network --id SERVICE_ID
   

3. 外部接続をテストします：

   curl -x http://FORWARDED_HOST:FORWARDED_PORT https://ifconfig.co
   

ポートフォワーディングが DISABLED と表示される場合は、有効にします：

npx zeabur@latest service port-forward --id SERVICE_ID --enable

クイックリファレンス：ヘッドレスサービス（HTTP なし）

サービスがどの HTTP ポートでもリッスンしていない場合（502 Bad Gateway）、修正方法については zeabur-port-mismatch スキルを参照してください。

クイックリファレンス：重要なルール

# WRONG -- using :latest tag (may serve cached/stale image)
image: rajnandan1/kener:latest

# CORRECT -- pin to specific version
image: rajnandan1/kener:4.0.16

# WRONG -- hardcoded password
POSTGRES_PASSWORD:
  default: mypassword123

# CORRECT -- use ${PASSWORD}
POSTGRES_PASSWORD:
  default: ${PASSWORD}
  expose: true

# WRONG -- PUBLIC_DOMAIN gives incomplete URL
APP_URL:
  default: https://${PUBLIC_DOMAIN}

# CORRECT -- ZEABUR_WEB_URL gives full URL
APP_URL:
  default: ${ZEABUR_WEB_URL}
  readonly: true

# WRONG -- other services can't reference without expose
POSTGRES_HOST:
  default: ${CONTAINER_HOSTNAME}

# CORRECT -- expose + readonly for connection info
POSTGRES_HOST:
  default: ${CONTAINER_HOSTNAME}
  expose: true
  readonly: true

# WRONG -- referencing variables without declaring dependency
- name: app
  spec:
    env:
      DB: ${POSTGRES_HOST}

# CORRECT -- declare dependency first
- name: app
  dependencies:
    - postgresql
  spec:
    env:
      DB: ${POSTGRES_HOST}

# WRONG -- HTTP type for a TCP proxy/database/game server
ports:
  - id: proxy
    port: 8888
    type: HTTP

# CORRECT -- TCP type + portForwarding for non-web services
ports:
  - id: proxy
    port: 8888
    type: TCP
portForwarding:
  enabled: true

---

ドメインのバインド

パブリックドメインが必要なサービスで domainKey を使用します。これは type: DOMAIN を持つ spec.variables 内の変数に対応します。

単一ドメイン：

domainKey: PUBLIC_DOMAIN

複数ドメイン（ポートが異なる場合）：

domainKey:
    - port: web
      variable: ENDPOINT_DOMAIN
    - port: console
      variable: ADMIN_ENDPOINT_DOMAIN

---

よく使うデータベース設定

コピーして使える PostgreSQL、MySQL/MariaDB、Redis の設定と標準的なボリュームパスについては、references/database-configs.md を参照してください。

---

テンプレートの複雑さのレベル

5 段階の複雑さのガイド（単一サービスから大規模なマルチサービスプラットフォームまで）については、references/complexity-levels.md を参照してください。

---

name、description、readme、icon、coverImage の作成

情報収集先（優先順位順）：

1. プロジェクトのGitHub リポジトリの README
2. プロジェクトの公式ウェブサイト
3. その他の公開情報源（ブログ記事、ドキュメントサイトなど）

重要なルール：

1. 元の README をコピー＆ペーストしないでください。 プロジェクト自体ではなく、このプロジェクトの Zeabur テンプレートを紹介する内容を書いてください。readme には次の内容を含めます。
   • プロジェクトの概要を簡潔に紹介する
   • このテンプレートの使い方（デプロイ手順、設定、ドメインのバインド）に重点を置く
   • Zeabur へのデプロイに固有の重要な注意事項やトラブルシューティングのヒントを含める
2. ライセンスと帰属表示を必ず含めてください。 元のプロジェクトが MIT、Apache、またはその他のライセンスを採用している場合：
   • readme にライセンスを記載する
   • 元のリポジトリへのリンクを含める
   • 利用可能な場合は公式ウェブサイトへのリンクを含める
   • これは法的に必須です。省略しないでください。
3. icon と coverImage： GitHub リポジトリまたは公式ウェブサイトからプロジェクトのロゴを探します。画像（SVG、PNG、WebP）への直接 URL を使用します。URL が HTTP 200 を返すことを必ず確認してください：

   curl -s -o /dev/null -w "%{http_code}" "URL"
   

   よくある落とし穴：raw.githubusercontent.com の URL でブランチ名（develop、main、master）を間違えること。

ローカライズ要件

必須の言語は 6 つです：en-US（spec 内）、zh-TW、zh-CN、ja-JP、es-ES、id-ID。

翻訳対象： description、variables[].name、variables[].description、readme

翻訳しない項目： key、type、${VARIABLE_NAMES}、URL

---

実践から得た教訓

実運用で検証されたパターン（wait-for-db、初回起動時の初期化マーカー、OOM からの復旧、ImagePullBackOff など）については、references/hard-won-lessons.md を参照してください。