deploy

Elixir/Phoenix デプロイリファレンス

Elixir/Phoenix アプリケーションをデプロイするためのクイックリファレンスです。

絶対に守るべき原則 — 決して違反しないでください

1. 設定はコンパイル時ではなく、実行時に行う — config.exs 内のシークレットはリリースバイナリに埋め込まれます。起動時にシークレットを解決できるよう、環境変数を使用して runtime.exs で設定してください
2. グレースフルシャットダウンは 60 秒以上 — タイムアウトが短いと、処理中のリクエストや WebSocket 接続が処理の途中で終了し、ユーザーのデータ損失につながります
3. ヘルスチェックは必須 — 起動時・稼働中・準備完了の各エンドポイントがないと、オーケストレーターは起動中のノードと停止したノードを区別できず、再起動が連鎖的に発生します
4. データベースの SSL 検証を行う — verify: :verify_peer を省略すると、アプリケーションとデータベース間で MITM 攻撃を受ける可能性があります。本番データはこの接続を通過します
5. CPU 制限を設定しない — BEAM スケジューラーはすべてのコアを使用できる前提で動作します。cgroups の CPU 制限によりスケジューラーが破綻し、VM が使用可能なコア数を超えるコアがあると認識して、レイテンシーが急増することがあります
6. 省略可能なサービスの認証情報を条件付きにする — runtime.exs は、eval ベースのマイグレーションコマンドを含め、リリースが起動するたびに実行されます。S3、Redis などの認証情報は、その連携が有効な場合にのみ必須にしてください

クイック設定

runtime.exs（必須）

if config_env() == :prod do
  database_url = System.get_env("DATABASE_URL") || raise "DATABASE_URL is required"
  secret_key_base = System.get_env("SECRET_KEY_BASE") || raise "SECRET_KEY_BASE is required"
  host = System.get_env("PHX_HOST") || raise "PHX_HOST is required"

  config :my_app, MyApp.Repo,
    url: database_url,
    pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10"),
    ssl: true,
    ssl_opts: [verify: :verify_peer]

  config :my_app, MyAppWeb.Endpoint,
    url: [host: host, port: 443, scheme: "https"],
    http: [ip: {0, 0, 0, 0}, port: String.to_integer(System.get_env("PORT") || "4000")],
    secret_key_base: secret_key_base,
    server: true
end

省略可能なサービスの条件付き設定

DATABASE_URL や SECRET_KEY_BASE などのコア起動用シークレットは必須のままにします。 省略可能な連携の認証情報は、その連携を有効にする機能スイッチと同じ条件で必須にしてください：

s3_config =
  if System.get_env("STORAGE_BACKEND") == "s3" do
    [
      access_key_id:
        System.get_env("S3_ACCESS_KEY") ||
          raise("S3_ACCESS_KEY is required when STORAGE_BACKEND=s3"),
      secret_access_key:
        System.get_env("S3_SECRET_KEY") ||
          raise("S3_SECRET_KEY is required when STORAGE_BACKEND=s3")
    ]
  else
    []
  end

config :my_app, :s3_config, s3_config

これにより、S3 を使用しないリリースタスクは S3 の認証情報なしで起動でき、S3 が選択されている場合は速やかにエラーになります。

ヘルスチェック用 Plug

def call(%{path_info: ["health", "readiness"]} = conn, _opts) do
  case Ecto.Adapters.SQL.query(MyApp.Repo, "SELECT 1", []) do
    {:ok, _} -> send_resp(conn, 200, ~s({"status":"ok"})) |> halt()
    {:error, _} -> send_resp(conn, 503, ~s({"status":"error"})) |> halt()
  end
end

クイックな選択肢

プラットフォームの選択

ニーズ	使用するもの
シンプルなマネージド環境	Fly.io
エンタープライズ環境、既存の K8s	Kubernetes
カスタムインフラストラクチャ	Docker + 任意のオーケストレーター

リソース制限

リソース	推奨事項
CPU	制限なし（BEAM スケジューラーの問題を回避）
メモリ	制限を設定（通常 256Mi～512Mi）
グレースフルシャットダウン	60 秒以上

デプロイチェックリスト

• すべてのシークレットを環境変数から runtime.exs に設定する
• 省略可能なサービスの認証情報は、連携が有効な場合にのみ必須にする
• エンドポイント設定で server: true を設定する
• データベース接続で SSL 検証を行う
• ヘルスチェック用エンドポイント：/health/startup、/health/liveness、/health/readiness
• グレースフルシャットダウン期間を 60 秒以上にする
• CPU 制限を設定しない（メモリ制限のみ）
• デプロイプロセスにマイグレーションを含める

アセットパイプラインに関する注意事項

Phoenix 1.8 は esbuild + tailwind を使用します（Node.js は不要です）：

• :esbuild と :tailwind の設定は config/config.exs にあります
• mix assets.deploy で本番環境向けにビルドします
• mix assets.setup で初回実行時にバイナリをインストールします
• カスタム JS バンドラーは config/config.exs で設定します

参考資料

詳細なパターンについては、以下を参照してください：

• ${CLAUDE_SKILL_DIR}/references/docker-config.md - マルチステージ Dockerfile、ベストプラクティス
• ${CLAUDE_SKILL_DIR}/references/flyio-config.md - fly.toml、クラスタリング、コマンド