Using Rails (Rack) deployment health checks
Overview
Deployment health checks are a way to check whether your code has been deployed properly by checking on the status of your Rails application.
Cloud 66 offers two kinds of deployment health checks:
- Automated health checks (custom webservers only)
- Custom health checks
Automated health checks
If your app uses a custom web server such as Puma, Unicorn or Thin (i.e. anything but Passenger, our default web server) then we offer automated deployment health checks.
We use two metrics to ensure your application is healthy:
- We check if systemd is reporting that your application is healthy
- We check that your application process IDs change in some way on redeployment.
If either of these two checks fail, we mark the deployment as failed.
Enabling automated health checks
To enable automated health checks on an application:
- Open your Dashboard and click on the application
- Click on Settings & Information in the right-hand panel
- Check the “Web Health” checkbox
Custom health checks
Custom health checks allow you to define simple tests (in YAML format) to confirm whether your Rails (or Rack) application has been successfully deployed, and to mark a deployment as “failed” if any of these checks do not pass.
These tests send a request to one of your app’s endpoints (as defined by you) and assign a status (“pass” or “fail”) based on the range of acceptable HTTP response code.
This can help to catch deployments that don’t throw any errors, but are problematic for other reasons (such as issues at the code or database level). This is particularly useful for serial or rolling deployment strategies to ensure that bad code doesn’t bring your entire application down.
Defining custom health checks
Custom health checks are defined in your application’s manifest file. Health checks have the following options:
rails:
configuration:
health:
protocol: 'http'
host: 'localhost'
port: 80
endpoint: '/'
accept: ["200", "300-399"]
timeout: 30
The values above are the default values and are all optional. Any options that are excluded will simply use the defaults above. You can see a complete list of supported options in our detailed manifest guide.
To simply use all these defaults with no changes, you can set:
rails:
configuration:
health: default
The limitations of health checks
As you can see these checks are quite simple - they confirm that the endpoints defined are returning acceptable HTTP response codes. They do this by running a curl command from the server itself once new code has been deployed.
If you have set up custom error handling for your application, be sure these checks account for that customisation.
In particular you should check that your application correctly reports response codes and does not mask them. This applies to both false positives (i.e. health checks that should fail but appear to pass) and to false negatives (failed checks of healthy deployments).
Dealing with domain access controls
Some applications are set to only accept requests that originate from their own domain (or set of domains). In this case the health checks would always fail. The best way to work around this issue is to add an entry to your /etc/hosts file that maps your localhost (127.0.0.1) to your primary domain.
Need more detail?
- We have a complete how-to guide to building Manifest files
- We have more info on using deployment strategies
