最終更新日 2025年01月08日(水)

Heroku でサポートされている言語のいずれかを使用する多くのアプリでは、使用するのに適切な buildpack が自動的に検出されます。buildpack は必要なバイナリのインストール、必要な依存関係のダウンロード、ソースコードのコンパイルなどを行います。こうしたケースでは、ビルドに使用する buildpack をカスタマイズする必要はありません。

この記事では、アプリの buildpack を管理およびカスタマイズする方法とそのタイミングについて説明します。クラシック buildpack​ とCloud Native Buildpack (CNB)​ では管理の方法が異なります。

buildpack を追加またはカスタマイズするタイミング

buildpack を手動で追加する必要がある理由はさまざまです。たとえば、アプリが次の条件に当てはまる場合などです。

• ffmpeg​ などの Heroku ベースイメージにデフォルトで含まれていないバイナリが必要である。
• Rust などの Heroku で直接サポートされていない言語を使用している。
• nx​ や task​ などの Heroku の buildpack には用意されていないカスタムビルドツールが必要である。
• Ruby、Python、または PHP アプリケーションと Node.js ライブラリを組み合わせて使用するときにアセットを処理するために複数の buildpack が必要である。

通常は使用する正しい buildpack が検出されますが、失敗​する場合もあります。失敗した場合は、buildpack を手動で設定​することもできます。

アプリに buildpack を設定する

アプリに公式の Heroku buildpack​ または サードパーティの buildpack​ を設定できます。 クラシック buildpack​ と CNB​ では設定の方法が異なります。

クラシック buildpack を設定する

アプリケーションの作成時

既存アプリの場合

複数の buildpack を追加する

app.json を使用する

Cloud Native Buildpack を設定する

Fir 世代のアプリ用のCloud Native Buildpack を選択するには、アプリリポジトリのルートディレクトリの project.toml​ で設定します。ファイルに 1 つまたは複数の buildpack を追加して、特定の順序で実行できます。詳細については、CNB 仕様を参照してください。

たとえば、同じ CNB ビルドで Node.js と Go の両方が必要な場合は、project.toml​ に次の内容を含めます。

[_]
schema-version = "0.2"

[[io.buildpacks.group]]
id = "heroku/nodejs"

[[io.buildpacks.group]]
id = "heroku/go"

次に、ファイルを git にコミットし、Heroku にプッシュします。

$ git add project.toml
$ git commit -m "Set custom CNB"
$ git push heroku main

この場合も、アプリは指定された buildpack の検出に合格する必要があります。たとえば、heroku/ruby が指定されている場合は Gemfile が存在している必要があり、存在しない場合はビルドが失敗します。

インライン buildpack

アプリ専用のスクリプトを実行するには、ID とスクリプトを指定して buildpack を project.toml​ に直接インライン化します。

[[io.buildpacks.group]]
id = "my-inline-buildpack"

 [io.buildpacks.group.script]
 api = "0.10"
 inline = "echo 'Hello World'"

TOML """​ heredoc 区切り文字を使用して複数行のスクリプトを追加します。

[[io.buildpacks.group]]
id = "my-inline-buildpack"

 [io.buildpacks.group.script]
 api = "0.10"
 inline = """
echo 'Hello World'
echo 'Goodbye'
"""

project.toml の要件と制限

project.toml​ プロジェクト記述子​は CNB フレームワークの一部です。Heroku Fir では含めることができる構成のほとんどをサポートしていますが、すべてのタイプの構成をサポートしているわけではありません。

• スキーマ バージョンは 0.2 にするか省略する必要があります。
• Platform API バージョンは 0.12 である必要があります。
• ビルダーは heroku/builder​ リポジトリからのものである必要があります。Heroku では現在、Heroku-24 ビルダー heroku/builder:24​ のみをサポートしています。
• include​ と exclude​ はサポートされていません。

buildpack を表示する

次のコマンドを実行すると、アプリの buildpack の完全なリストを表示できます。

$ heroku buildpacks
=== nameless-brushlands-4859 Buildpack
1. heroku/nodejs
2. heroku/ruby

リストの最後の buildpack は、アプリケーションのプロセスタイプ​を決定するために使用されます。以前の buildpack から定義されたプロセスタイプは無視されます。

heroku help buildpacks​ を実行して、コマンドのオプションの完全なリストを取得できます。

buildpack を削除する

クラシック buildpack を削除する

buildpack はアプリから削除できます。

$ heroku buildpacks:remove heroku/nodejs

アプリからすべての buildpack を消去するには:

$ heroku buildpacks:clear --app example-app

Cloud Native Buildpack を削除する

project.toml​ から buildpack を削除し、コードをコミットして Heroku にプッシュします。

複数の buildpack を使用する

アプリケーションのビルド時に単一の buildpack では十分ではないシナリオが多数存在します。これには、次の操作が必要な場合が含まれます。

• アプリで使用する言語ごとに buildpack を実行する。たとえば、アセットには JavaScript buildpack を、アプリケーションには Ruby buildpack を実行する場合です。
• アプリケーションでデーモンプロセスを実行する。
• apt​ でシステム依存関係を取得する。

アプリが必要とする特定の buildpack と、それらの実行順序を定義できます。詳細については、buildpack の設定手順​を参照してください。

サードパーティの buildpack の使用

buildpack を探す

Heroku のクラシック buildpack と CNB のリストについては、「公式にサポートされる buildpack​」を参照してください。

Heroku で公式にサポートされている buildpack の対象とならない言語またはフレームワークをサポートするために、カスタムサードパーティ buildpack を使用できます。

カスタムクラシック buildpack

厳選されたカスタムサードパーティクラシック buildpack のリストについては、Elements marketplace​ をご覧ください。

何百種類ものカスタム buildpack を CLI から検索することもできます。検索するには、次を実行します。

$ heroku buildpacks:search elixir
Buildpack        Category   Description
───────────────  ─────────  ───────────────────────────
hashnuke/elixir  languages  Heroku Buildpack for Elixir

$ heroku buildpacks:info hashnuke/elixir
description: Heroku Buildpack for Elixir
category:    languages
license:     MIT License
support:     https://github.com/HashNuke/heroku-buildpack-elixir/issues
source:      https://github.com/HashNuke/heroku-buildpack-elixir
readme:

buildpack の名前空間/名前または Git URL を使用して、公式のクラシック buildpack と同じコマンド​でカスタム buildpack を追加できます。

カスタム Cloud Native Buildpack

公式にサポートされている Heroku CNB とサードパーティ CNB はどちらも、Cloud Native Buildpack Registry (https://registry.buildpacks.io) にあります。Heroku が公式にサポートしている buildpack は、レジストリの heroku​ スコープに一覧表示されています (例: ​heroku/go​)。レジストリに一覧表示されているサードパーティ CNB の多くは Heroku の CNB ビルダーと Heroku Fir で動作しますが、Heroku では公式にサポートされていません。project.toml​ 内の他の CNB と同様に追加​できます。

CNB アプリのベースイメージまたはビルダーを変更する

CNB のベースイメージはビルダーの一部であるため、直接変更することはできません。デフォルトでは、Heroku Fir プラットフォーム上の CNB ビルドは、Heroku-24 ベースイメージを使用する heroku/builder:24 CNB ビルダーを使用します。Heroku では heroku/builder リポジトリのビルダーのみを使用できます。現在、Heroku では heroku-24​ ビルダーのみをサポートしています。

CNB ビルドの環境変数を設定する

アプリの環境設定はビルド中に使用できませんが、ビルド中に使用する環境変数を設定できます。これらの環境変数は project.toml​ にあるため、リポジトリにコミットされます。project.toml​ 経由で機密データやシークレットを設定しないでください。

[_]
schema-version = "0.2"

[[io.buildpacks.build.env]]
name = "NODE_ENV"
value = "production"

buildpack リファレンス

クラシック buildpack リファレンス

buildpack の値は次のいずれかで設定できます。

• heroku/python​ など、短縮形式の Buildpack Registry​ 名 (公開済みの buildpack の場合)
• Git リポジトリの URL (例: ​https://github.com/heroku/heroku-buildpack-nodejs.git​)
• gzip で圧縮された tarball の URL

使用する buildpack のソースが Git リポジトリにある場合、Git オブジェクト​ (タグ名、ブランチ名、40 文字のコミット SHA など) を URL に追加することによって、使用する buildpack の特定のタグまたはブランチを指定できます。たとえば、次のようになります。

• https://github.com/heroku/heroku-buildpack-nodejs.git#somedevbranch
• https://github.com/heroku/heroku-buildpack-nodejs.git#v9861
• https://github.com/heroku/heroku-buildpack-nodejs.git#a2113e0671bc132310ff9f85ad07f5a19f217313

Cloud Native Buildpack リファレンス

CNB を参照できるすべての方法については、Buildpacks.io​ の公式ドキュメントを参照してください。

クラシック buildpack と CNB を使用してアプリを移行する

クラシック buildpack と CNB を使用してアプリを移行することはできません。

Cedar 世代のアプリを Fir に再デプロイする必要があります。そうすると、クラシック buildpack の代わりに CNB が自動的に使用されるようになります。

Fir 世代のアプリを Cedar に再デプロイする必要があります。そうすると、CNB の代わりにクラシック buildpack が自動的に使用されるようになります。

その他の資料

• buildpack
• 公式にサポートされる buildpack
• buildpack エラーのトラブルシューティング