【和訳】heroku.yml - Build Manifest (Developer Preview)

Container RegistryでもReview Apps使いたいなーと思っていたら、heroku.yml使えばいけそうと気付いたので翻訳する
https://devcenter.heroku.com/articles/heroku-yml-build-manifest

# heroku.yml - 新しいビルド方式（開発者レビュー中）

`heroku.yml`はアプリケーションのビルドを定義するための新しい方式です。現在（4/26時点）は開発者プレビュー中で、今後のロードマップのためにも皆さんの手助けがあるとうれしいです。ぜひフィードバックを送ってください。

`heroku.yml`を使うと、

- ひとつの方式でアプリケーションビルドの定義ができる
- [`apt`](https://help.ubuntu.com/lts/serverguide/apt.html)からのパッケージ追加が容易にできる
- コンパイル（ビルド）前後に実行したいコマンドを定義できる
- Dockerベースのアプリケーションでも`Review Apps`が使える
- Herokuに自分でビルドしたDockerイメージをデプロイできる

`heroku.yml`は、Ruby、Java、そしてDockerベースのアプリケーションをサポートしています。

## Getting started - 既存のアプリケーション

まず、自分のアプリケーションのルートディレクトリに`heroku.yml`ファイルを作成します。サンプルとしてRubyアプリケーションの例です。

```yml
build:
  languages:
    - ruby
  packages:
    - imagemagick
  config:
    RAILS_ENV: development
release:
  command:
    - rake db:migrate
run:
  web: bundle exec puma -C config/puma.rb
```

`git commit`します。

```sh
$ git add heroku.yml
$ git commit -m "Add heroku.yml"
```

Herokuアプリケーションのstack設定を`container`に変更します。

```sh
$ heroku stack:set container
```

そして、Herokuアプリケーションに`git push`してください。

```sh
$ git push heroku master
```

アプリケーションは新しいビルドサービスで構築され、`Procfile`ではなく`heroku.yml`ファイルのrunコマンドを実行します。

## Getting started - 新しいアプリケーション

サンプル用のリポジトリを`git clone`します。

```sh
$ git clone https://github.com/heroku/ruby-getting-started.git
$ cd ruby-getting-started
```

プロジェクトのルートディレクトリに`heroku.yml`ファイルを作成します。

```yml
build:
  languages:
    - ruby
run:
  web: bundle exec puma -C config/puma.rb
```

`Procfile`を削除（任意）して、`heroku.yml`ファイルを`git commit`します。

```sh
$ rm Procfile
$ git rm Procfile
$ git add heroku.yml
$ git commit -m "Added heroku.yml and removed Procfile"
```

次に、stack設定を`container`にして新しいアプリケーションを作成します。

```sh
$ heroku create your-app-name --stack=container
```

データベース（無料）を追加します。

```sh
$ heroku addons:create heroku-postgresql:hobby-dev
```

プロジェクトを`git push`します。

```sh
$ git push heroku master
```

アプリケーションは新しいビルドサービスで構築され、`Procfile`ではなく`heroku.yml`ファイルのrunコマンドを実行します。

最後に、アプリケーションにアクセスします。

```sh
$ heroku open
```

## ビルドの定義

### 言語設定について

`heroku.yml`はRubyとJavaアプリケーションの構築をサポートしており、別言語のサポートも予定しています。

```yml
build:
  languages:
    - ruby
```
```yml
build:
  languages:
    - java
```

### コンパイル（ビルド）前後のコマンド実行について

`heroku.yml`の`pre`と`post`では、`languages`で設定した言語のコンパイル（ビルド）の前後で実行されます。（`Dockerfile`ビルドでは、`pre`、`post`は無視されます）shellコマンド数に制限はなく、すべて実行します。

```yml
build:
  languages:
    - ruby
  pre:
    - curl https://sh.rustup.rs -sSf | sh -s -- -y
  post:
    - fortune | tee -a banner.txt
```

### `apt`からのパッケージインストールについて

`heroku.yml`の`packages`では、`apt`からインストールするパッケージを定義します。

```yml
build:
  packages:
    - imagemagick
```

### ビルド時の環境変数について

`heroku.yml`の`config`では、ビルド中に使う環境変数を設定できます。

```yml
build:
  config:
    RAILS_ENV: development
    FOO: bar
```

ここで設定した環境変数は、アプリケーション実行中の[環境変数](https://devcenter.heroku.com/articles/config-vars)にはなりません。

## Dockerイメージのビルド

Dockerイメージでアプリケーションを実行できるようにする場合は、`heroku.yml`に`Dockerfile`を設定することができます。`heroku.yml`に`Dockerfile`の相対パスを指定してください。

```yml
build:
  docker:
    web: Dockerfile
    worker: worker/Dockerfile
```

`Dockerfile`を設定すると、新しいビルドサービスで`docker build`してデプロイします。アプリケーションの実行には`CMD`で指定したコマンドを実行します。

## リリースフェーズ

[リリースフェーズ](https://devcenter.heroku.com/articles/release-phase)では、新しいリリースが本番環境にデプロイされる前にコマンドを実行できます。（例えば、`CSS/JS/assets`をCDNに送信、キャッシュストア、データベースのマイグレーション）

リリースフェーズコマンドの定義は、`heroku.yml`の`release`にコマンドを指定します。

```yml
build:
  ...
release:
  command:
    - rake db:migrate
run:
  web: bundle exec puma -C config/puma.rb
```

`Dockerfile`でビルド定義している場合は、コマンド実行に使うDockerイメージを指定することもできます。

```yml
build:
  docker:
    web: Dockerfile
    worker: worker/Dockerfile
release:
  image: worker
  command:
    - ./deployment-tasks.sh
```

:speaker: リリースフェーズのログを確認したい場合は、Dockerイメージに`curl`をインストールしなければいけません。インストールしていない場合は、アプリケーションログにリリースフェーズのログを表示します。もし、[`heroku/heroku:16`](https://devcenter.heroku.com/articles/heroku-16-stack#heroku-16-docker-image)イメージを使っているなら、`curl`はインストール済です。

## 実行プロセスの定義

`run`では、アプリケーションの起動時に実行したいコマンドを設定できます。プロジェクト内に`Procfile`もあった場合は、`Procfile`は無視して、`run`のコマンドを実行します。

```yml
build:
  languages:
    - ruby
run:
  web: bundle exec puma -C config/puma.rb
```

### Dockerの場合

Dockerを使う場合、`Dockerfile`で指定した`CMD`のコマンドを実行し、`heroku.yml`の`run`コマンドは無視します。Dockerイメージを使った場合の要件詳細については、[Container Registry and Runtime documentation](https://devcenter.heroku.com/articles/container-registry-and-runtime#dockerfile-commands-and-runtime)を確認してください。

## Review Appsと`app.json`

`heroku.yml`を使っていて、Review Appsを利用する場合は[`app.json`](https://devcenter.heroku.com/articles/github-integration-review-apps#app-json)ファイルが必要です。将来的に`app.json`は`heroku.yml`に統合する予定です。（`app.json`はいらなくなります）

必ず、`app.json`の[stack](https://devcenter.heroku.com/articles/app-json-schema#stack)設定で`container`に設定してください。

## 既知の問題と制限事項

- Revie Appsはサポートしていますが、`pipeline promotions`はサポートしていない
- RubyとJavaをサポートしている