Platform API を使用したアプリのセットアップ

最終更新日 2024年05月08日(水)

この記事では、Platform API​ の app-setups​ リソースの使用方法について説明します。このリソースを、ソースコードに埋め込まれた app.json​ マニフェストファイル​と共に使用して、プログラムでアプリをセットアップすることができます。

アプリのセットアップは、Heroku Button​ を強化するテクノロジです。保守するソースコードのセットアップを簡単にするために、README または関連するガイドおよびチュートリアルに Heroku Button を追加することを検討してください。

ここで示すいくつかのシナリオでは、保守するソースコードで app.json​ および app-setups​ が役立つ場合があります。

  • ステージングアプリでテストするために共同作業者が各自のソースコードをセットアップして Heroku にデプロイする作業を簡単にしたい
  • すぐにデプロイできるアプリまたはフレームワークを管理していて、他の人にもそれをすばやく Heroku にデプロイして試してもらいたい

app-setups​ リソースは、アプリケーションのソースコードの tar アーカイブを受け取り、app.json​ マニフェストファイルを探し、それを使用して、Heroku へのアプリケーションの初回セットアップを調整し、アプリケーションのデプロイとリリースを効率化します。

セットアップの準備

app-setups​ リソースを使用して単純なアプリケーションをデプロイしたいと考えていると仮定します。これは独自のアプリケーションかもしれませんし、興味のあるサンプルまたはテンプレートかもしれません。

ruby-rails-sample​ サンプルアプリケーションはそのような例です。ここでは例として Ruby を使用しているだけであり、どの言語で記述されたアプリでもこの API を使用できることに注意してください。

最初の手順では、app.json​ 設定ファイルをアプリに追加します。このアプリの設定には次のものが含まれます。

  • テンプレートをカスタマイズするためのランタイム環境内の環境設定
  • いくつかのアドオン
    • ログ記録用の Papertrail
    • データベース用の Heroku Postgres
  • データベースを準備するためにデプロイ後に実行されるコマンド。

API を呼び出すには、そのソース tarball の URL が必要です。この例では、この URL​ を使用します。API では、この設定情報を含む app.json​ ファイルが、ソースバンドルのディレクトリ構造のルートに存在していることを期待します。

パブリック GitHub リポジトリをソースコード用に使用している場合、各リポジトリに固有で、リポジトリの内容の tarball に解決する URL が GitHub によって提供されます。この URL は通常、次のようになります。https://github.com/<username>/<repo name>/tarball/master/

アプリのセットアップの作成

app.json​ を含むソース tarball を使用して https://api.heroku.com/app-setups​ エンドポイントを呼び出し、app.json​ に対応したアプリケーションを Heroku 上でセットアップします。アプリケーションのソースコードの tarball を指すソース URL がリクエストの本体に含まれている必要があります。

cURL を使用して app-setups​ エンドポイントを呼び出してみましょう。

$ curl -n -X POST https://api.heroku.com/app-setups \
-H "Content-Type:application/json" \
-H "Accept:application/vnd.heroku+json; version=3" \
-d '{"source_blob": { "url":"https://github.com/heroku/ruby-rails-sample/tarball/master/"} }'

必要に応じて、overrides​ セクションをリクエストに含めることで、app.json​ で指定された環境変数の値を提供する、デフォルト値を上書きする、または追加の環境変数を提供することができます。app.json​のうち上書きできるのは env​ セクションの部分だけです。

$ curl -n -X POST https://api.heroku.com/app-setups \
-H "Content-Type:application/json" \
-H "Accept:application/vnd.heroku+json; version=3" \
-d '{"source_blob": { "url":"https://github.com/heroku/ruby-rails-sample/tarball/master/"},
"overrides": {"env": { "RAILS_ENV":"development" } } }'

Heroku では、生成されたアプリ名で Heroku アプリを作成することでアプリケーションのセットアップを開始し、すぐに応答を返します。この応答に含まれている ID を後のリクエストで使用できます。

{
    "id": "df1c2983-fbde-455b-8e7b-e17c16bdf757",
    "failure_message": null,
    "status": "pending",
    "app": {
        "id": "888ee9fb-c090-499b-a115-2f335a1f0ef5",
        "name": "pacific-peak-6986"
    },
    "build": {
        "id": null,
        "status": null
    },
    "manifest_errors": [],
    "postdeploy": {
        "output": null,
        "exit_code": null
    },
    "resolved_success_url": null,
    "created_at": "2014-05-09T18:41:35+00:00",
    "updated_at": "2014-05-09T18:41:35+00:00"
}

アプリの作成に失敗する場合があります。その場合、失敗の詳細を含む次のような応答が返されます。

{ "id": "invalid_params", "message": "You've reached the limit of 5 apps for unverified accounts. Add a credit card to verify your account." }

セットアップステータスのポーリング

ID を使用して API をポーリングし、最新のステータスを取得します。

$ curl -n https://api.heroku.com/app-setups/df1c2983-fbde-455b-8e7b-e17c16bdf757 \
-H "Content-Type:application/json" \
-H "Accept:application/vnd.heroku+json; version=3"

ビルドが開始されたときの応答は次のとおりです。

{
  "id": "df1c2983-fbde-455b-8e7b-e17c16bdf757",
  "failure_message": null,
  "status": "pending",
  "app": {
    "id": "888ee9fb-c090-499b-a115-2f335a1f0ef5",
    "name": "pacific-peak-6986"
  },
  "build": {
    "id": "06503167-f75e-4ad6-bd06-4d5da3825eb5",
    "status": "pending"
   },
   "resolved_success_url": null,
   ...
}

ステータスが pending​ から succeeded​ または failed​ に変わるまでポーリングを続けます。

セットアップ中に問題が発生した場合、応答でそれらのエラーが示されます。

{
  "id": "df1c2983-fbde-455b-8e7b-e17c16bdf757",
  "failure_message": "app.json not found",
  "status": "failed",
  "app": {
    "id": "888ee9fb-c090-499b-a115-2f335a1f0ef5",
     "name": "pacific-peak-6986"
  },
  ...
}

セットアッププロセスのどこかで手順が失敗した場合、アプリは削除されますが、セットアップのステータスはいつでも確認できます。

ビルドステータスが succeeded​ または failed​ に更新されたら、ビルド ID を使用して Platform API を呼び出し、ビルドのより詳細なステータスを取得できます。詳細は、「Platform API を使用したビルドとリリース​」を参照してください。ビルドステータスのリクエストを作成するには、セットアップ中のアプリの名前とビルド ID の両方が必要です。これらはどちらも、前出の応答に含まれています。

$ curl -n -X GET https://api.heroku.com/apps/pacific-peak-6986/builds/06503167-f75e-4ad6-bd06-4d5da3825eb5/result \
-H "Content-Type:application/json" \
-H "Accept:application/vnd.heroku+json; version=3"

これにより、ビルド出力のすべての行を含む詳細なビルド結果が返されます。

{
  "build": {
    "id": "06503167-f75e-4ad6-bd06-4d5da3825eb5",
    "status": "succeeded"
  },
  "exit_code": 0,
  "lines": [
    {
      "stream": "STDOUT",
      "line": "\n"
     },
     {
       "stream": "STDOUT",
       "line": "-----> Ruby app detected\n"
     },
     ...

デプロイ後スクリプトの出力は、全体的なセットアップステータスのポーリングリクエストへの応答内でインラインで提供されます。

"postdeploy": {
  "output": "",
  "exit_code": 0
}

ステータスが succeeded​ の場合、セットアップの完了時にユーザーをリダイレクトする先の完全修飾 URL が resolved_success_url​ に設定されます。この値は app.json​ マニフェストファイルの success_url​ 属性から決定されます。success_url​が絶対 URL の場合、そのまま返されます。相対 URL の場合、アプリの web_url​ のコンテキストで解決されます。

"resolved_success_url": "http://pacific-peak-6986.herokuapp.com/"

背後での作業

次に示すのは、app.json​ ファイル内のさまざまな要素に対して Heroku Platform API が実行する処理の概要です。app.json​を使用してセットアップしたアプリは、通常、Git ベースのワークフロー​を使用してデプロイしたアプリと同じように動作します。app-setups では Build API を使用するため、ソース tarball が GitHub から取得された場合、それらのソース tarball には Git サブモジュールが復元されないことに注意してください。

この記事で説明するセットアップフローは API を通じて利用でき、Heroku Button を使用したアプリのセットアップ​を拡張するものです。

アプリケーションメタデータ

name​、description​、website​、repository​、logo​ の各フィールドは、アプリケーションに関する基本的な情報を提供します。これは、ユーザーが app.json​ の内容からアプリケーションの概要を把握するための情報にすぎず、アプリケーションのセットアップ中に API がこのセクションを使用するわけではありません。

"name": "Ruby on Rails",
"description": "A template for getting started with the popular Ruby framework.",
"website": "http://rubyonrails.org"

環境変数

env​ セクションは、一連の変数と、それらの変数に関する詳細情報で構成されます。変数ごとに、API によってアプリの環境設定​が行われます。

"env": {
  "RAILS_ENV": "production",
  "COOKIE_SECRET": {
    "description": "This gets generated",
    "generator": "secret"
  },
  "SETUP_BY": {
    "description": "Who initiated this setup",
    "required": false
  }
}

変数には説明とデフォルト値を指定できます。前の例で示したように、Platform API のリクエストには、これらのデフォルト値を上書きする値を提供する overrides​ セクションが含まれる場合があります。

app.json​ で値が指定されている場合、API はそれを必須の変数として扱います。Platform API が呼び出されるときに、overrides​ セクションで変数の値が指定されている必要があります。指定されていないと、セットアップは失敗します。省略可能な変数は "required": false​ を使用して指定できます。

一部の変数には、アプリケーションのデプロイおよびセットアップ時に生成される値が必要です。これらの変数のジェネレーターを指定できます。現在サポートされている唯一のジェネレーターは、64 文字の 16 進文字列を生成する secret​ です。

アドオン

"addons": ["heroku-postgresql:essential-0", "papertrail"]

アプリの作成直後、またコードがビルドおよびリリースされる前に、API によってアドオンがプロビジョニングされます。app.json​では、アドオン名のみ、またはアドオン名と特定の層の組み合わせを指定できます。層を指定しない場合、Platform API は最下位層 (多くのアドオンでは無料層) をプロビジョニングします。

デプロイ後スクリプト

1 つのデプロイ後スクリプトを app.json​ ファイルで指定できます。このスクリプトは、アプリケーションがビルドおよびリリースされるとすぐ、Heroku によって One-off dyno​ で実行されます。このスクリプトはアプリケーションと同じ環境で実行され、その環境設定とアドオンにアクセスできます。

"scripts": {
  "postdeploy": "bundle exec rake db:migrate"
}

実行する複数のコマンドがある場合、それらをスクリプトに入れて、スクリプトをソースバンドルに追加し、そのスクリプトを実行するために使用するコマンドを postdeploy​ の値として指定します。アプリケーションと同じ言語でスクリプトを記述し、rails setup-script.rb​ などの適切なコマンドを指定することもできます。

デプロイされたアプリ

この例の Heroku アプリは、次の環境設定を使用してセットアップされています。

$ heroku config -a pacific-peak-6986

=== pacific-peak-6986 Config Vars
COOKIE_SECRET:              1e1867380b9365f2c212e31e9c43a87c17e82be0ce1a61406ea8274fac0680dc
DATABASE_URL:               postgres://bdlgvbfnitiwtf:DGuFLR87rMNFe7cr_y1HGwadMm@ec2-54-225-182-133.compute-1.amazonaws.com:5432/d8p7bm6d7onr10
HEROKU_POSTGRESQL_ONYX_URL: postgres://bdlgvbfnitiwtf:DGuFLR87rMNFe7cr_y1HGwadMm@ec2-54-225-182-133.compute-1.amazonaws.com:5432/d8p7bm6d7onr10
PAPERTRAIL_API_TOKEN:       VikcKA2wQf2H1ajww3s
RAILS_ENV:                  development
SETUP_BY:                   MyDeployerScript

次のアドオンがプロビジョニングされています。

$ heroku addons -a pacific-peak-6986

=== pacific-peak-6986 Configured Add-ons
heroku-postgresql:essential-0  HEROKU_POSTGRESQL_ONYX
papertrail:choklad

データベースが移行され、アプリケーションはトラフィックを処理する準備ができています。

Heroku アプリに関連付けられた Git リポジトリにソースコードが準備されています。アプリのコーディングを続行し、標準の git push​ デプロイで変更をプッシュするには、アプリを複製するだけです。

$ heroku git:clone pacific-peak-6986

Cloning from app 'pacific-peak-6986'...
Cloning into 'pacific-peak-6986'...
Initializing repository, done.
remote: Counting objects: 77, done.
remote: Compressing objects: 100% (69/69), done.
remote: Total 77 (delta 2), reused 0 (delta 0)
Receiving objects: 100% (77/77), 17.85 KiB | 0 bytes/s, done.
Resolving deltas: 100% (2/2), done.
Checking connectivity... done