trackman

Trackman is an add-on that lets you keep your error and maintenance pages within your Ruby on Rails project and hosts them for you when you deploy to Heroku.

Trackmanは、Ruby on Railsのプロジェクト内に、エラーとメンテナンスの画面を提供し、Herokuへのデプロイ時にこれらの画面をホストするアドオンです。

Don't spend time manually uploading and managing those pages separately: これらの画面を手動でアップロードしたり、分けて管理することに時間を使わないで下さい。:

• They are part of your project and should be handled as such.

• Keep them versioned and modify them within your project.

• Deploy your app those pages will be synced to S3.

• Reference the assets you already created (images/js/css) in your app.

• これらの画面は、プロジェクトの一部です。そして、そのように扱われるべきものなのです。

• プロジェクト内で、バージョン管理と修正を行って下さい。

• アプリケーションをデプロイすることで、これらの画面がS3と同期されます。

• アプリケーションで既に作成済みのアセット（images/js/css）を参照して下さい。

Provisioning the add-on

アドオンの設定

Trackman can be attached to a Heroku application via the CLI: TrackmanはCLIを経由してHeroku上のアプリケーションへアタッチされます。:

A list of all plans available can be found [here](http://addons.heroku.com/trackman). 利用可能なプランの確認はこちらで行えます。

:::term
$ heroku addons:add trackman
-----> Adding trackman to sharp-mountain-4005... done, v18 (free)

Once Trackman has been added a TRACKMAN_URL, TRACKMAN_ERROR_PAGE_URL and a TRACKMAN_MAINTENANCE_PAGE_URL settings will be available in the app configuration and will contain the provisioning information needed to serve and modify all the assets related to your maintenance and error pages. This can be confirmed using the heroku config command.

一度、Trackmanを追加さえしてしまえば、アプリケーションの設定でTRACKMAN_URL、TRACKMAN_ERROR_PAGE_URL、TRACKMAN_MAINTENANCE_PAGE_URLが利用可能となり、またメンテナンスとエラーページに関連した全てのアセットを提供、修正する際に必要となる設定情報が含まれることとなります。

:::term
$ heroku config | grep TRACKMAN
TRACKMAN_URL    => https://user:pass@trackman-server/resourceid
TRACKMAN_ERROR_PAGE_URL    => http://s3.amazon.com/trackman-bucket/app-id/path/to/your/page.html
TRACKMAN_MAINTENANCE_PAGE_URL    => http://s3.amazon.com/trackman-bucket/app-id/path/to/your/page.

Using with Ruby on Rails

Ruby on Railsでの使用方法

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Trackman client library. Ruby on Railsのアプリケーションでは、Trackmanのクライアントライブラリを明示するために、Gemfileに下記のエントリを追加する必要があります。

:::ruby
gem 'trackman'

Update application dependencies with bundler. アプリケーションの依存関係をbundlerで更新して下さい。

:::term
$ bundle install

And setup Heroku's error and maintenance page config vars with rake trackman:setup.

そして、Herokuのエラーとメンテナンスの画面の設定変数をrake trackman:setupコマンドでセットアップして下さい。

Ruby on Rails 2.x applications should generate the required files with `./script/generate trackman` before. Ruby on Rails 2.x のアプリケーションでは、事前に`./script/generate trackman`を実行することで、必要なファイルを生成する必要があります。

:::term
$ bundle exec rake trackman:setup
overriding the required heroku configs MAINTENANCE_PAGE_URL and ERROR_PAGE_URL
done! Thank you for using Trackman!

If you already have custom maintenance or error page configs in `MAINTENANCE_PAGE_URL` or `ERROR_PAGE_URL` they will be copied to a config var of the same name with a `_bkp` suffix. For example: `ERROR_PAGE_URL` will be backed up into `ERROR_PAGE_URL_bkp`.

もし、既にMAINTENANCE_PAGE_URLやERROR_PAGE_URL内に、カスタムのメンテナンスやエラーページを設定済みでしたら、_bkpと接尾辞の付いた同名の設定変数にコピーが行われます。例えば、ERROR_PAGE_URLは、ERROR_PAGE_URL_bkpへバックアップされます。

Scaffold your maintenance pages

メンテナンスページのScaffold

:::term
$ rails generate trackman:controller [name]

This will generate a special controller that, when on development, will create your maintenance pages for you when you execute its actions. Because Rails 3 can handle 500 and 404 pages dynamically, the generator also adds the required route to handle them. On Rails 2, it generates the 4 different static pages instead.

このコマンドは、特別なコントローラーを生成します。開発環境で、アクションを実行時メンテナンスページを生成します。 Rails 3は、500と404のページを直にハンドルするため、これらをハンドルするためのルートをジェネレーターが追加します。 Rails 2では、4つの異なる静的なページが代わりに生成されます。

The controller has class methods to filter the response output.
You can find examples on how to use them within the controller itself.

コントローラは、レスポンスのアウトプットをフィルターするクラスメソッドを管理しています。 コントローラ自身を参照すれば、それらを使う方法の例を見つけることができるでしょう。

Deploy changes

デプロイの変更

Deploy the maintenance and error pages: メンテナンスとエラーページのデプロイ:

:::term
$ git add public/503.html
$ git add public/503-error.html
$ git commit -a -m "Adding maintenance and error pages"
$ heroku maintenance:on
$ git push heroku master
...
-----> Heroku receiving push
-----> Launching... done, v3
       http://warm-frost-1289.herokuapp.com deployed to Heroku

To [email protected]:warm-frost-1289.git
 * [new branch]      master -> master

The following file conventions must be used: The maintenance page must exist at `public/503.html` and the error page at `public/503-error.html`.

以下のファイル管理規約が適用されなければなりません。：メンテナンスのページは、`public/503.html`に存在する必要があります。エラーページは、`public/503-error.html`に存在する必要があります。

Sync assets

アセットの同期

If anything goes wrong, Trackman will fail silently and will not break your app.

何かしらの問題が起きたとしても、Trackmanはサイレントフェイル？し、アプリケーションを壊すことはないでしょう。

Trackman will sync on the boot of your application. Trackmanは、アプリケーションの起動時に同期します。

View changes

If it does not display the latest changes, make sure your browser is not using a cached version by starting a new session.

To verify the new maintenance pages, you can query it from your browser.

When you are done you can set maintenance back to off

:::term
$ heroku maintenance:off

If you'd like to explicitly sync your error and maintenance pages you can manually invoke the sync task and see additional details as well.

:::term
$ heroku run rake trackman:sync

Testing

Confirm that it all worked by doing:

:::term
$ heroku maintenance:on

And checking your website to see your custom maintenance page. After verifying be sure to take the website off maintenance mode:

:::term
$ heroku maintenance:off

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan.

:::term
$ heroku addons:upgrade trackman:newplan
-----> Upgrading trackman:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: trackman:newplan

Removing the add-on

Trackman can be removed via the CLI.

This will destroy all associated data and cannot be undone!

:::term
$ heroku addons:remove trackman
-----> Removing trackman from sharp-mountain-4005... done, v20 (free)

You will need to manually restore any custom MAINTENANCE_PAGE_URL or ERROR_PAGE_URL config vars after removing the add-on.

Support

All Trackman support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome here.

Additional resources

Additional resources are available at:

• Trackman website
• Trackman on github