haloy-config

Haloy の設定

haloy でアプリケーションをデプロイするための haloy.yaml 設定ファイルを作成します。

Dockerfile が存在せず、ユーザーがデプロイ可能な公開済みイメージも持っていない場合は、次のように伝えてください。

"このプロジェクトには Dockerfile が見つからず、デプロイ可能な既存のイメージも見当たりません。Haloy は Dockerfile からのビルドにも、公開済みイメージのデプロイにも対応しています。dockerize スキルを使って Dockerfile を作成しましょうか？"

仕組み

1. Dockerfile または既存の公開済みイメージを確認する - Haloy のデフォルトのローカルビルドフローを使うか、明示的なイメージ設定を使うかを判断します
2. 設定済みの haloy サーバーを確認する - 既存のサーバー設定を探します
3. プロジェクトの種類を検出する - 次のファイルを調べます。
   • フレームワークの依存関係が記載された package.json（Next.js、TanStack Start、Express など）
   • pyproject.toml、requirements.txt、Pipfile（Python/Django/FastAPI）
   • go.mod（Go）
   • Cargo.toml（Rust）
   • Gemfile（Ruby/Rails）
   • composer.json（PHP/Laravel）
4. データベースの依存関係を検出する（Prisma、Drizzle、pg、SQLAlchemy など）
5. アプリ名、ポート、ヘルスチェックパス、イメージ戦略のデフォルト値を推定する
6. サーバー（設定済みリストから選択、または手動入力）とドメインをユーザーに確認する
7. 明示的なイメージ設定が必要な場合は、追加で必要な最小限のイメージ情報を収集します
8. データベースが検出された場合は、セルフホストにするか外部サービスにするかを確認します
9. 適切な設定を含む haloy.yaml を生成する
10. 検証とデプロイの次の手順を提示する

プロジェクトの検出

フレームワークを検出し、デフォルトのポートを判断します。

フレームワーク	判定条件	デフォルトポート
Next.js	package.json の依存関係に next がある	3000
TanStack Start	package.json に @tanstack/react-start がある	3000
Express/Node.js	package.json に express がある、または汎用 Node	3000
Vite	package.json に vite がある	5173（開発）／3000（本番）
Django	requirements.txt または pyproject.toml に django がある	8000
FastAPI	requirements.txt または pyproject.toml に fastapi がある	8000
Flask	requirements.txt または pyproject.toml に flask がある	5000
Go	go.mod が存在する	8080
Rust	Cargo.toml が存在する	8080
Ruby/Rails	Gemfile に rails がある	3000
PHP/Laravel	composer.json に laravel がある	8000
デフォルト	不明なフレームワーク	8080

Dockerfile に EXPOSE ディレクティブがある場合も確認します。これらはフレームワークのデフォルト値より優先されます。

データベースの検出

データベースの依存関係を調べ、プロジェクトでデータベースが使われているかを判断します。

判定条件	データベースの種類
package.json に @prisma/client、prisma がある	スキーマでプロバイダーを確認
package.json に drizzle-orm がある	設定でドライバーを確認
package.json に pg、postgres がある	PostgreSQL
package.json に mysql2 がある	MySQL
package.json に better-sqlite3、sqlite3 がある	SQLite（サービス不要）
package.json に sequelize、typeorm がある	設定で方言を確認
requirements.txt に psycopg2、asyncpg がある	PostgreSQL
requirements.txt に sqlalchemy がある	設定でドライバーを確認
requirements.txt に django がある	設定でデータベースを確認
prisma/schema.prisma ファイルが存在する	datasource ブロックの provider を確認

Prisma スキーマの例 - プロバイダーを確認します。

datasource db {
  provider = "postgresql"  // or "mysql", "sqlite"
  url      = env("DATABASE_URL")
}

判断フロー

重要な値が不足している場合を除き、デフォルト値を使います。必要な場合にのみユーザーに確認します。

アプリ名

• 第一候補：package.json の name フィールド
• 第二候補：プロジェクトフォルダー名
• 確認が必要な場合：名前に無効な文字が含まれる場合、または汎用的な名前（例：「app」、「project」）の場合

イメージの方針

ユーザーの環境に適した、最もシンプルで有効なイメージ設定を優先します。

1. デフォルトのローカルビルド：

   • プロジェクトのルートに Dockerfile があり、ユーザーが公開済みイメージ、レジストリ認証、カスタム Dockerfile パス、カスタムビルドコンテキスト、またはターゲットごとに異なる複数のイメージを求めていない場合は、最小限の Haloy 設定を使用し、image は完全に省略します。
   • これは Haloy のデフォルトのフローに沿っています。同じディレクトリにある Dockerfile を探してローカルでビルドし、サーバーにアップロードします。

2. 必要な場合にのみイメージの詳細を確認する：

   • Dockerfile が存在しない
   • ユーザーが既存のイメージ、公開済みイメージ、Docker Hub、GHCR、ECR、またはプライベートレジストリについて言及している
   • Dockerfile が設定ディレクトリにない、またはプロジェクトがモノレポでカスタムビルドコンテキストが必要
   • ターゲットごとに異なるイメージが必要（例：web と worker）
   • ユーザーがレジストリへのプッシュ動作、またはロールバック／履歴設定を明示的に希望している

3. 既存のイメージを使用する単一イメージのデプロイの場合：

   • リポジトリ／タグだけが必要な場合は、文字列形式の省略記法を使用します：

     image: "ghcr.io/acme/my-app:v1.2.3"
     

   • tag、registry、history、または build_config が必要な場合にのみ、オブジェクト形式を使用します。
   • Haloy がリポジトリのホストから推測できない場合を除き、registry.server は省略します。

4. 明示的なイメージ設定が必要なローカルビルドの場合：

   • Dockerfile またはビルドコンテキストがデフォルトでない場合は、image.build_config を使用します。
   • ドキュメントに記載されている現在のフィールド名を使用します：

     image:
       build_config:
         context: "."
         dockerfile: "Dockerfile"
     

   • パスは haloy.yaml を含むディレクトリからの相対パスです。
   • Haloy は一般的な server と registry のケースを自動検出するため、build_config.push は省略することを優先します。
   • 同じ値を実行時とビルド引数の両方で使用する必要がある場合は、build_config.args に重複して指定するよりも、env[].build_arg: true を優先します。

5. マルチターゲット構成の場合：

   • すべてのターゲットが同じイメージのデフォルト設定を継承する場合は、ルートの image を使用します。
   • ターゲットごとに異なるイメージが必要な場合は、ルートの images とターゲットの image_key を使用します。
   • ターゲットで定義できるのは image または image_key のどちらか一方で、両方は指定できません。
   • 解決の優先順位は、ターゲットの image -> ターゲットの image_key -> ルートの image です。

6. Dockerfile も公開済みイメージもない場合：

   • イメージ設定を推測して作成するのではなく、代わりに dockerize スキルを推奨します。

サーバー URL

~/.config/haloy/client.yaml で設定済みのサーバーを確認します：

# Example client.yaml structure
servers:
  example.haloy.dev:
    token_env: HALOY_API_TOKEN_example_HALOY_DEV
  prod.mycompany.com:
    token_env: HALOY_API_TOKEN_PROD

判断フロー：

1. サーバーが見つかった場合：選択肢として提示し、ユーザーに選んでもらいます。サーバーキー（例：example.haloy.dev）が設定で使用する値です。

   「次の haloy サーバーが設定されています。どのサーバーにデプロイしますか？」

   • example.haloy.dev
   • prod.mycompany.com
   • 別のサーバーを入力

2. サーバーが見つからない場合：which haloy または haloy --version を実行して、haloy CLI がインストールされているか確認します。

   • haloy がインストールされている場合：サーバー URL を手動で尋ねます。

     「haloy サーバーの URL を入力してください。（例：haloy.yourserver.com）」

   • haloy がインストールされていない場合：最初に CLI のインストールと設定が必要であることをユーザーに伝えます。

     「haloy サーバーが設定されていません。haloy でデプロイするには、CLI をインストールしてサーバーを追加する必要があります。こちらを参照してください：https://haloy.dev/docs/client-installation」

ドメイン

• 必ず尋ねます - Web アプリケーションでは必須です
• 質問の例：「このアプリにアクセスするドメインを教えてください。（例：myapp.example.com）」
• ユーザーが「なし」または「スキップ」と答えた場合は、domains セクションを省略します。

ドメインエイリアス

• ドメインの後に尋ねます：ユーザーがドメインを指定したら、エイリアスを追加するか尋ねます。
• 質問の例：「ドメインエイリアスを追加しますか？（例：www.myapp.example.com）」
• よくあるエイリアス：メインドメインに www. を付けたもの
• ユーザーが「なし」または「スキップ」と答えた場合は、エイリアスを省略します。

DNS に関するリマインダー

ドメイン情報を収集した後、ユーザーに DNS の設定を促してください。

「ドメインプロバイダーで DNS を設定してください。A レコードを使用してドメインを Haloy サーバーの IP アドレスに向けるか、サーバーにドメイン名がある場合は CNAME レコードを使用してください。」

ポート

• 上の表に記載されたフレームワークのデフォルト値を使用
• Dockerfile の EXPOSE ディレクティブを確認してください。こちらが優先されます
• 次の場合にのみ質問してください。公開されているポートが複数ある場合、または明確なデフォルト値がない場合

ヘルスチェックのパス

• 既存のエンドポイント（/health、/healthz、/api/health、/_health）を検索します
• 見つかった場合：既存のヘルスチェックエンドポイントを使用します
• 見つからない場合：/（ルートパス）を使用します
• 質問しないでください。haloy はデフォルトで / を使用し、ほとんどのアプリで機能します

データベース

データベースの依存関係が検出された場合（「データベースの検出」セクションを参照）：

1. ユーザーに質問します。

   「データベースの依存関係（[検出されたタイプ]）が見つかりました。セルフホスト可能なデータベースサービスを追加しますか、それとも外部プロバイダー（Supabase、Neon、RDS など）を使用しますか？」

   • セルフホスト可能なデータベースを追加する
   • 外部プロバイダーを使用する（DATABASE_URL は自分で設定します）

2. セルフホスト可能なデータベースを使用する場合：

   • データベースサービスとアプリのターゲットを含むマルチターゲット設定を生成します
   • データベースのターゲットには database プリセットを使用します
   • ユーザーがすでに環境ファイルまたはシークレットプロバイダーに設定している場合を除き、適切な環境変数をプレースホルダー値とともに追加します
   • データの永続化用にボリュームを追加します
   • 追加のイメージフィールドが必要でない場合は、シンプルなデータベースイメージには文字列の短縮表記を優先します
   • preset: database は、image.history.strategy: "none" などのより安全なデフォルト設定を適用することを明記します
   • データベースのタイプごとのデフォルト値：

   データベース	イメージ	ポート	ボリュームパス
   PostgreSQL	postgres:18	5432	/var/lib/postgresql
   MySQL	mysql:8	3306	/var/lib/mysql

   • イメージやバージョンによってイメージのデータパスは異なります。ユーザーがイメージを変更した場合は、そのイメージのドキュメントで正しいマウントパスを確認してください。

3. 外部プロバイダーを使用する場合：

   • 通常どおり、単一ターゲットの設定を生成します
   • ユーザーに次のように伝えます。「外部データベース用の DATABASE_URL 環境変数を設定してください。」

設定リファレンス

Haloy は次の 2 つのモードに対応しています。

1. 単一デプロイ：targets が定義されていない場合、ルート設定がデプロイターゲットになります
2. マルチターゲット：targets が定義されている場合、ルート設定はベース／デフォルト設定として機能します

最小限の設定（単一デプロイ）

name: "my-app"
server: "haloy.yourserver.com"

これは、プロジェクトにルート Dockerfile がすでにあり、カスタムイメージ設定が不要な場合のデフォルトの選択肢です。

ドメインとポートを指定する場合

name: "my-app"
server: "haloy.yourserver.com"
domains:
  - domain: "my-app.example.com"
    aliases:
      - "www.my-app.example.com"
port: "3000"
health_check_path: "/health"

公開済みイメージを使用する場合

name: "my-app"
server: "haloy.yourserver.com"
image: "ghcr.io/acme/my-app:v1.2.3"
domains:
  - domain: "my-app.example.com"
port: 3000

カスタムのローカルビルドを使用する場合

name: "my-app"
server: "haloy.yourserver.com"
image:
  repository: "my-app"
  tag: "latest"
  build_config:
    context: "."
    dockerfile: "./apps/web/Dockerfile"
domains:
  - domain: "my-app.example.com"
port: 3000

環境変数を使用する場合

name: "my-app"
server: "haloy.yourserver.com"
domains:
  - domain: "my-app.example.com"
port: "3000"
env:
  - name: "NODE_ENV"
    value: "production"
  - name: "DATABASE_URL"
    value: "postgres://user:pass@db:5432/myapp"

ボリュームを使用する場合（永続データ用）

name: "my-app"
server: "haloy.yourserver.com"
domains:
  - domain: "my-app.example.com"
volumes:
  - "app-data:/app/data"

セルフホスト可能なデータベースを使用する場合（マルチターゲット）

server: "haloy.yourserver.com"
env:
  - name: POSTGRES_USER
    value: "postgres"
  - name: POSTGRES_PASSWORD
    value: "change-me-in-production"
  - name: POSTGRES_DB
    value: "my_app"

targets:
  postgres:
    preset: database
    image: "postgres:18"
    port: 5432
    volumes:
      - postgres-data:/var/lib/postgresql

  my-app:
    domains:
      - domain: "my-app.example.com"
    port: 3000
    env:
      - name: DATABASE_URL
        value: "postgres://postgres:change-me-in-production@postgres:5432/my_app"
      - name: NODE_ENV
        value: "production"

image_key を使用した名前付きイメージ

name: "my-app"
server: "haloy.yourserver.com"
images:
  web:
    repository: "my-app-web"
    tag: "v1.2.3"
  worker: "my-app-worker:v1.2.3"

targets:
  production:
    image_key: "web"
    domains:
      - domain: "my-app.example.com"
    port: 3000

  jobs:
    image_key: "worker"

マルチターゲットの例

# Base settings inherited by all targets
image:
  repository: "my-app"
  tag: "latest"
  build_config:
    context: "."
    dockerfile: "Dockerfile"
port: 3000

targets:
  production:
    server: "prod.haloy.com"
    domains:
      - domain: "my-app.com"
    replicas: 2
  staging:
    server: "staging.haloy.com"
    domains:
      - domain: "staging.my-app.com"
    replicas: 1

全リファレンス

すべての設定オプションについては、こちらをご覧ください：https://haloy.dev/docs/configuration-reference

主なオプション：

• name - アプリケーション名（単一デプロイでは必須）
• server - Haloy サーバーの URL（必須）
• image - デフォルト／単一ターゲット用の Docker イメージ設定。文字列の省略形式またはオブジェクト形式に対応します
• images - 複数ターゲットのデプロイ用の、名前付きイメージのルートマップ
• image_key - images 内の名前付きイメージへのターゲットレベルの参照
• image.build_config - ローカルビルド設定：context、dockerfile、platform、args、および任意の push
• image.registry - プライベートイメージまたはレジストリへのプッシュ用のレジストリ認証
• image.history - ロールバック戦略（local、registry、または none）
• domains - domain と任意の aliases を含むドメインオブジェクトの配列
• port - コンテナポート（デフォルト：「8080」）
• health_check_path - ヘルスチェックのエンドポイント（デフォルト：「/」）
• env - 名前と値のペアで指定する環境変数
• volumes - 永続データ用のボリュームマウント
• replicas - コンテナインスタンスの数（デフォルト：1）
• deployment_strategy - 「rolling」（デフォルト）または「replace」
• targets - 複数のデプロイターゲットを定義します（マルチターゲットモード）
• preset - プリセット設定を適用します（「database」または「service」）

出力形式

情報を収集したら、haloy.yaml ファイルを作成し、次の項目を提示してください：

1. haloy.yaml ファイル - プロジェクトのルートに書き込みます
2. .dockerignore を更新 - まだ含まれていない場合は、.dockerignore に haloy.yaml を追加します。haloy.yaml の変更でビルドキャッシュが無効にならないため、Docker レイヤーのキャッシュ効率が向上します。
3. 検証コマンド：

   haloy validate-config
   

4. デプロイコマンド：

   haloy deploy
   

5. haloy CLI がインストールされていない場合は、インストール方法を提示します：

   # Shell script
   curl -fsSL https://sh.haloy.dev/install-haloy.sh | sh
   
   # Homebrew
   brew install haloydev/tap/haloy
   
   # npm/pnpm/bun
   npm install -g haloy
   pnpm add -g haloy
   bun add -g haloy
   

やり取りの例

詳細なやり取りの例については、references/examples.md をご覧ください。以下の内容を扱っています：

• 設定済みサーバーを使ったデプロイ
• データベースの検出とセルフホスト可能なデータベースのセットアップ
• サーバー設定が不足している場合の対処