dockerize

Haloy 向けに Docker 化する

haloy でのデプロイに最適化した、本番環境対応の Dockerfile を作成します。

ユーザーのリクエストに docker-compose、複数のコンテナ、または複雑なオーケストレーションが含まれる場合は、次のように伝えてください。

「このスキルでは、haloy のデプロイ向けに単一の Dockerfile を作成します。Haloy は本番環境向けの docker-compose のように機能し、独自の設定を通じてオーケストレーションを処理します。複数のサービスが必要な場合は、それぞれに独自の Dockerfile を用意し、haloy.yaml で個別のサービスとして定義する必要があります。代わりに、特定のサービス向けの Dockerfile を作成しましょうか？」

仕組み

1. プロジェクトの種類を判定します。次の項目を確認します。

   • package.json に @tanstack/react-start が含まれている（TanStack Start）
   • package.json に next が含まれている（Next.js）
   • package.json（Node.js／JavaScript／TypeScript）
   • bun.lockb、pnpm-lock.yaml、package-lock.json、または yarn.lock（Node.js のパッケージマネージャー）
   • requirements.txt、pyproject.toml、Pipfile（Python）
   • uv.lock、poetry.lock、または pyproject.toml の [tool.poetry]（Python のパッケージマネージャー）
   • go.mod（Go）
   • Cargo.toml（Rust）
   • Gemfile（Ruby）
   • pom.xml、build.gradle（Java）
   • composer.json（PHP）
   • その他の手がかり

2. アプリケーションを分析して、次の項目を特定します。

   • ビルドプロセスと依存関係
   • ランタイム要件
   • エントリーポイント／起動コマンド
   • 必要な環境変数
   • 静的アセットまたはビルド出力

3. ヘルスエンドポイントを確認します。存在しない場合は、作成するかどうかをユーザーに尋ねます（下記の「ヘルスチェック」セクションを参照）。

4. ベストプラクティスに従って、最適化された Dockerfile を作成します。

   • イメージサイズを削減するマルチステージビルド
   • 適切なベースイメージ（可能な場合は Alpine）
   • キャッシュ効率を高める適切なレイヤー順序
   • セキュリティのための非 root ユーザー
   • ヘルスエンドポイントを指定する HEALTHCHECK 命令

5. haloy.yaml が存在しない場合は、Haloy の設定に関するガイダンスを提供します。

ヘルスチェックエンドポイント

すべての Haloy デプロイで /health エンドポイントを設けることを強く推奨します。Dockerfile を作成する前に、アプリケーションに既存のヘルスエンドポイントがあるか確認してください。

ヘルスチェックが重要な理由

Haloy は次の目的でヘルスチェックを使用します。

• ダウンタイムのないデプロイ：新しいコンテナは、トラフィックを受け取る前にヘルスチェックに合格する必要があります。
• 自動復旧：正常でないコンテナは自動的に再起動されます。
• デプロイの検証：アプリを適切に起動できない場合、デプロイはすぐに失敗します。

ヘルスチェックがないと、Haloy はアプリケーションが実際に動作しているか確認できず、壊れたコンテナにトラフィックをルーティングする可能性があります。

既存のヘルスエンドポイントを確認する

既存のヘルスエンドポイントを検索します。

• /health、/healthz、/api/health、/_health
• ステータス 200 または { status: "ok" } を返すルート定義を探します。

ユーザーに尋ねる

ヘルスエンドポイントが存在しない場合は、ユーザーに次のように尋ねてください。

「アプリケーションにヘルスチェックエンドポイントがないようです。Haloy はダウンタイムのないデプロイと自動復旧にヘルスチェックを使用します。/health エンドポイントを作成しましょうか？」

ユーザーが同意した場合は、フレームワークに適した最小限のヘルスエンドポイントを作成します。

TanStack Start（src/routes/health.tsx）：

import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/health")({
  server: {
    handlers: {
      GET: async () => {
        return Response.json({ status: "ok" });
      },
    },
  },
});

Express／Node.js：

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

Next.js（app/health/route.ts または pages/api/health.ts）：

export async function GET() {
  return Response.json({ status: 'ok' });
}

FastAPI：

@app.get("/health")
def health():
    return {"status": "ok"}

Go（net/http）：

http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.Write([]byte(`{"status":"ok"}`))
})

ヘルスチェックのベストプラクティス

• すぐに応答する（基本的なヘルスチェックではデータベースクエリを避けます）。
• 正常な場合は HTTP 200、正常でない場合は 200 以外を返します。
• 応答は最小限にします。{"status": "ok"} で十分です。
• 一貫したパスに配置します。標準は /health です。

判断フロー

重大な値が不足していない限り、デフォルトを使用してください。必要な場合にのみユーザーに質問してください。

• ヘルスエンドポイント：既存のヘルスルートが見つからない場合にのみ質問してください。
• 起動コマンド：既存の scripts.start またはフレームワークのデフォルトを使用してください。明確なエントリーポイントがない場合は質問してください。
• ポート：設定ファイルまたは環境変数でポートが指定されていない限り、一般的なデフォルト（Node は 3000、Python は 8000）を使用してください。
• パッケージマネージャー：ロックファイルから判断してください。存在しない場合は、Node では npm、Python では pip をデフォルトで使用してください。

ベースイメージのバージョン

重要：開発環境と本番環境の一貫性を確保するため、必ずローカルのランタイムバージョンを検出してください。バージョン番号について、学習データに頼らないでください。

バージョン選択の優先順位：

1. プロジェクト設定ファイル（最優先） - .nvmrc、.node-version、engines.node、.python-version、go.mod、rust-toolchain.toml、.ruby-version など
2. ローカルにインストールされたバージョン - ランタイムのバージョン確認コマンドを実行
3. references/base-images.md にフォールバック - 上記の方法が失敗した場合のみ

バージョン検出方法、設定ファイルの場所、バージョンとタグの対応、現在推奨されているフォールバックバージョンの詳細については、references/base-images.md を参照してください。

デフォルトでは slim バリアントを使用し、より小さなイメージが必要な場合は alpine を使用してください（互換性に関するトレードオフがあります）。必ず具体的な major.minor タグを使用し、latest は使用しないでください。

Dockerfile のベストプラクティス

一般原則

• latest ではなく、具体的なバージョンタグを使用してください（上記の「ベースイメージのバージョン」を参照）
• RUN コマンドをまとめてレイヤーを最小限に抑えてください
• 変更頻度の低い命令から高い命令の順に並べてください
• 不要なファイルを除外するには .dockerignore を使用してください
• 本番環境では root 以外のユーザーとして実行してください
• ドキュメントとして EXPOSE を含めてください

マルチステージビルドのパターン

# Build stage (verify current LTS version in references/base-images.md)
FROM node:24-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
ENV NODE_OPTIONS="--max-old-space-size=4096"
RUN npm run build

# Production stage
FROM node:24-slim AS runner
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -u 1001 -S appuser -G appgroup
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
USER appuser
EXPOSE 3000
CMD ["node", "dist/index.js"]

フレームワーク固有の考慮事項

TanStack Start：詳しい手順については references/tanstack-start.md を参照してください。主なポイント：

• package.json に "type": "module" が必要です
• tanstackStart() と nitro() プラグインを含む vite.config.ts が必要です
• ビルド出力先は .output/server/index.mjs です
• corepack 経由で pnpm を使用し、Node 24 slim を使用してください
• ヘルスチェック用に /health ルートを含めてください

Next.js：スタンドアロン出力モードを使用し、.next/standalone と .next/static をコピーしてください

Vite/React：静的ファイルをビルドし、nginx または Node サーバーで配信してください

Python/FastAPI：slim イメージを使用し、--no-cache-dir を指定してインストールしてください

Go：静的バイナリをビルドし、最小限のイメージには scratch または distroless を使用してください

出力形式

Dockerfile の作成後、次の順序で出力してください。

1. Dockerfile 全体
2. .dockerignore が存在しない場合は、そのファイル
3. ローカルでビルドおよびテストする手順：

   docker build -t myapp .
   docker run -p 3000:3000 myapp
   

4. haloy.yaml が存在しない場合は、ユーザーに次のように案内してください：

   "haloy のセットアップを完了するには、haloy.yaml 設定ファイルが必要です。/haloy-config スキルを実行して生成するか、設定方法について haloy のドキュメント を確認してください。"

参照ファイル

詳しい手順については、適切な参照ファイルを読んでください。

• ベースイメージ：references/base-images.md - すべてのランタイムについて現在推奨されているバージョン（最初に確認してください！）
• TanStack Start：references/tanstack-start.md - ヘルスチェック、データベースのセットアップ、haloy.yaml の例を含む完全ガイド

.dockerignore を作成するタイミング

既存の .dockerignore があるか必ず確認してください。存在しない場合は、プロジェクトの種類に適したものを作成してください。一般的な除外項目：

node_modules
.git
.env
.env.*
*.log
dist
.next
.output
.vinxi
__pycache__
*.pyc
.venv
target
haloy.yaml

重要：必ず haloy.yaml を .dockerignore に含めてください。このファイルはデプロイ設定として haloy によって使用されますが、コンテナ内には必要ありません。除外すると、ドメインや環境変数の更新など、haloy.yaml の変更によってビルドキャッシュが無効にならないため、Docker のレイヤーキャッシュが改善されます。