This add-on is operated by SynApps
Maintenance made fun again
Table of Contents
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.
Provisioning the add-on
Trackman can be attached to a Heroku application via the CLI:
A list of all plans available can be found here.
$ heroku addons:add trackman -----> Adding trackman to sharp-mountain-4005... done, v18 (free)
Once Trackman has been added a
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.
$ 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 applications will need to add the following entry into their
Gemfile specifying the Trackman client library.
Update application dependencies with bundler.
$ bundle install
Enable heroku config at build-time (Rails >= 3.1)
By default, Heroku does not load the configuration variables at build-time. Since we run after assets:precompile, we need to tell heroku to load them by doing:
heroku labs:enable user-env-compile -a myapp
Setup Heroku’s error and maintenance page config vars with
Ruby on Rails 2.x applications should generate the required files with
./script/generate trackman before.
$ 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
ERROR_PAGE_URL they will be copied to a config var of the same name with a
ERROR_PAGE_URL will be backed up into
Scaffold your maintenance pages
$ 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.
The controller has class methods to filter the response output. You can find examples on how to use them within the controller itself.
Deploy the maintenance and error pages:
$ 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@example.com: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
If anything goes wrong, Trackman will fail silently and will not break your app.
Trackman will sync on the boot of your application.
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
$ 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.
$ heroku run rake trackman:sync
Confirm that it all worked by doing:
$ heroku maintenance:on
And checking your website to see your custom maintenance page. After verifying be sure to take the website off maintenance mode:
$ heroku maintenance:off
Migrating between plans
Application owners should carefully manage the migration timing to ensure proper application function during the migration process.
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!
$ heroku addons:remove trackman -----> Removing trackman from sharp-mountain-4005... done, v20 (free)
You will need to manually restore any custom
ERROR_PAGE_URL config vars after removing the add-on.
Additional resources are available at: