最終更新日 2024年04月24日(水)

buildpack は、Heroku でのアプリのビルドを機能強化するためのスクリプトです。Heroku プラットフォームで buildpack が果たす役割の概要については、buildpack の記事​を確認してください。

buildpack API

buildpack は、次の 3 つのスクリプトで構成されます。

• bin/detect​: この buildpack がアプリに適用されるかどうかを判定します。
• bin/compile​: アプリで変換手順を実行するために使用されます。
• bin/release​: メタデータをランタイムに戻します。

bin/detect

使用法

bin/detect BUILD_DIR

まとめ

このスクリプトは 1 つの引数として BUILD_DIR​ を受け取り、BUILD_DIR​ に存在するアプリをこの buildpack で処理できる場合は 0​ の終了コードを返す必要があります。終了コードが 0​ である場合、このスクリプトは、人間に解読可能なフレームワーク名を stdout​ に出力する必要があります。

例

#!/bin/sh

# this pack is valid for apps with a hello.txt in the root
if [ -f $1/hello.txt ]; then
  echo "HelloFramework"
  exit 0
else
  exit 1
fi

bin/compile

使用法

bin/compile BUILD_DIR CACHE_DIR ENV_DIR

まとめ

このスクリプトは、buildpack の変換を実行します。BUILD_DIR​はアプリの場所になり、CACHE_DIR​ は buildpack がビルド間でビルド成果物をキャッシュするために使用できる場所になります。

このスクリプトから stdout​ で受信されたすべての出力が (対話型 Git プッシュビルドのために) ユーザーに表示され、ビルドと共に保存されます。

BUILD_DIR​ 内のアプリケーションは、compile​ スクリプトで加えられたすべての変更と共に slug にパッケージ化されます。

ENV_DIR​ は、アプリケーションの各環境設定​のファイルを含むディレクトリです。環境設定は、Procfile​ で指定されたコマンドの実行中や、1 回限りのプロセス​の実行時に環境変数として使用可能になります。

ファイルの名前が設定キーであり、ファイルの内容が設定値です。環境設定 S3_KEY=8N029N81​ と等価なものは、名前が S3_KEY​ で内容が 8N029N81​ であるファイルです。

ENV_DIR​ の内容を環境にエクスポートする方法を示す Bash 関数を次に示します。

export_env_dir() {
  env_dir=$1
  acceptlist_regex=${2:-''}
  denylist_regex=${3:-'^(PATH|GIT_DIR|CPATH|CPPATH|LD_PRELOAD|LIBRARY_PATH)$'}
  if [ -d "$env_dir" ]; then
    for e in $(ls $env_dir); do
      echo "$e" | grep -E "$acceptlist_regex" | grep -qvE "$denylist_regex" &&
      export "$e=$(cat $env_dir/$e)"
      :
    done
  fi
}

正規表現を使用して、エクスポートのための設定キーをブロックリストまたは許可リストに登録します。たとえば、PATH などの環境設定はビルドツールと競合する場合があるため、ブロックリストに登録することは良い考えです。ビルドの実行に環境設定の特定のサブセット (DATABASE_URL​ など) のみが必要であることがわかっている場合は、許可リスト登録が推奨されます。

コンパイルフェーズ中には、次の環境変数を使用できます。

• STACK​: これを使用する方法についての詳細は、後の「スタック」のセクション​を参照してください。
• SOURCE_VERSION​: 現在ビルトされているソースコードの “バージョン”​。Git プッシュビルドの場合、これは Git コミットの SHA-1 ハッシュです。

スタイル

buildpack 開発者には、出力を表示するときに Heroku プッシュスタイルと照合することをお勧めします。

-----> Main actions are prefixed with a 6-character arrow
       Additional information is indented to align

可能な場合は常に、使用されているソフトウェアのバージョンを表示します。

-----> Installing dependencies with npm 1.0.27

副作用

buildpack 開発者は、ビルド中に副作用が発生することを回避する必要があります。たとえば、コンパイルスクリプトでデータベース移行を実行することはお勧めできません。

例

#!/bin/sh

indent() {
  sed -u 's/^/       /'
}

echo "-----> Found a hello.txt"

# if hello.txt has contents, display them (indented to align)
# otherwise error

if [ ! -s $1/hello.txt ]; then
  echo "hello.txt was empty"
  exit 1
else
  echo "hello.txt is not empty, here are the contents" | indent
  cat $1/hello.txt
fi | indent

bin/release

使用法

bin/release BUILD_DIR

まとめ

BUILD_DIR​ はアプリの場所になります。

このスクリプトは、次の 2 つのキーを含む YAML 形式のハッシュを返します。

• addons​ は、インストールするデフォルトのアドオンの一覧です。
• default_process_types​ は、デフォルトの Procfile​ エントリのハッシュです。

このスクリプトは、存在する場合にのみ実行されます。

注意: buildpack の export​ スクリプトは bin/release​ が実行されるより前に供給されないため、export​ に設定されるすべての環境変数は利用できません (ランタイムバイナリを PATH​ に追加するものなど)。それらが必須の場合、export​ スクリプトを手動で供給する必要があります。

例

#!/bin/sh

cat << EOF
---
addons:
  - heroku-postgresql
default_process_types:
  web: bin/node server.js
EOF

default_process_types​ を使用する代わりに、デフォルトの Procfile​ を作成することもできます (提供されていない場合)。

.profile.d スクリプト

起動中、コンテナは、dyno のコマンドを実行する前に .profile.d/​ ディレクトリ内のすべての .sh​ スクリプトを提供する bash​ シェルを起動します。アプリケーションの環境設定​は、スクリプトが提供された時点ですでに環境内に存在します。

これにより、buildpack は、アプリ内のすべての dyno タイプに対して初期の環境を操作できます。潜在的なユースケースには、環境へのエクスポートによる $PATH​ などの初期の設定値の定義や、dyno の起動中に必要な他の初期化手順の実行が含まれます。

標準の Linux /etc/profile.d​ シェル起動ファイルと同様に、これらは bash​ スクリプトである必要があり、そのファイル名は .sh​ で終わる必要があります。これらのスクリプトが提供される順序に関する保証は何もありません。

.profile.d/mybuildpack-defaults.sh の例

# add vendor binaries to the path
export PATH=$PATH:$HOME/vendor/bin

# set a default LANG if it does not exist in the environment
export LANG=${LANG:-en_US.UTF-8}

複数の buildpack の構成

アプリは、順番に実行される複数の buildpack で構成 できます。 以降の buildpack に環境を提供するために、buildpack は、次の buildpack が実行される前に実行される $buildpack_dir/export​ スクリプトを作成できます。

たとえば、Node.js buildpack はこれを使用して、以降の buildpack が使用するノードバイナリ​を提供します。

キャッシング

bin/compile​ スクリプトには、その 2 番目の引数として、ビルド間で成果物を保存するために使用できる CACHE_DIR​ が付与されます。このディレクトリに保存された成果物は、連続したビルド中に CACHE_DIR​ で入手できます。このビルドキャッシュ​は slug のコンパイル中にのみ使用でき、ビルドされているアプリに固有のものです。

buildpack は、キャッシュを使用する予定がある場合、CACHE_DIR ディレクトリを作成する必要があります (存在しない場合)。

buildpack は多くの場合、このキャッシュを使用して解決済みの依存関係を保存することにより、連続したデプロイでのビルド時間を短縮します。

スタック

Heroku は、スタック​と呼ばれる複数の OS ベースイメージをサポートしています。

buildpack を保持しているユーザーには、その buildpack が、Heroku でサポートされるすべてのスタックで動作する slug を作成できるようにする責任があります。Heroku がアプリの slug を作成するために buildpack を実行する場合、そのビルドは常に、ビルドが実行されているアプリと同じスタックを使用して dyno で実行されます。さらに、buildpack がビルドの宛先スタックを特定できるように、コンパイルフェーズ中に STACK​ 環境変数が使用可能になります。STACK​値の例として heroku-20​ や heroku-22​ があります。

buildpack は、STACK​ 変数を使用して、そのスタックに適したバイナリやその他の依存関係を選択的にプルする必要があります。一般に、buildpack によってベンダリングされるバイナリは、互換性を確保するために、スタックごとに異なるバージョンでビルトする必要があります。詳細は、次の「バイナリ​」のセクションを参照してください。

バイナリ

buildpack は、アプリに関する完全な実行可能パッケージをビルドする役割を担っています。これには、アプリが動作するために必要な言語 VM やその他のシステムの依存関係の追加が必要になる可能性があります。

依存関係をビルドしてパッケージ化する場合は、これらが Heroku で現在使用されているスタック​と互換性があることを確認してください。依存関係をスタックごとに個別にコンパイルして配布したり、現在ビルトされているアプリの適切なセットでベンダリングしたりすることが必要になる場合があります。それを行うための 1 つの方法は、たとえば heroku run​ を使用して、Heroku dyno で依存関係をビルドすることです。

buildpack の公開と共有

buildpack を Heroku コミュニティと共有する場合は、buildpack を登録​できます。登録すると、その buildpack は heroku buildpacks:search​ CLI コマンドと Heroku Elements​ で表示されます (2018 年後半)。

buildpack の例

buildpack の作成を開始するための最も簡単な方法は、既存の多くの buildpack のいずれかを検証またはフォークすることです。

• デフォルトの buildpack
• サードパーティの buildpack