Health checks: how The Deployer knows your app is up

A health check is one address in your app, such as /health, that answers "OK" (HTTP 200) whenever the app is running. The Deployer uses it to tell a running app from a broken one. Deployments use it to know a release really works before switching visitors to it, and monitoring watches it.

You don't have to set it up. The Deployer finds your app's health check, proves it works on the live app, remembers it, and offers to add one if your app has none.

How The Deployer finds and proves it

Every deployment does this for your app's web service:

1. Find. It reads your code for routes that look like a health check, such as /health, /healthz, /up or /status. It also knows the ones some frameworks provide, like Spring's actuator or Rails' /up, and it follows the prefix your app puts its routes under (for example /api).
2. Prove. A route only counts once your live app answers it with a success. An address that shows a web page instead (such as a single-page app that shows the same page for every address, or a login form) does not count.
3. Remember. The proven route is kept with your project, along with where it came from and when it last answered.
4. Confirm. After your app starts, the route is checked again and the result recorded.

If the app is not live yet, The Deployer uses the best route from your code and proves it once the app is running.

None of this can fail a deployment. If the code can't be read or a check times out, the deployment carries on and checks your app's main address instead.

The Health check card

Open your project's Dashboard and find the Health check card. For each web service it shows the route and its state:

It also says where the route came from: Found in your code, or Added by The Deployer (approved by you).

Click Check now to test the route against your live app straight away. Open Log to see every time a route was found, checked, proposed, approved or committed, with the deployment it belongs to.

Between deployments, the dashboard checks the route again from time to time, so the card corrects itself without waiting for the next deployment.

When your app has no working health check

If your app has no health-check route, or its route fails on the live app while the app itself is up, the next deployment writes one for you. It is a small route, such as /health, that answers 200 while the app runs and depends on nothing else, so it works the same in production as on your machine. If your existing route fails with a server error, usually because it checks the database, that route is left as it is and a separate route is added for deployments.

Before asking you, The Deployer checks the change: that it is valid code, that your existing code is untouched, and that the address isn't already taken. Then the deployment pauses and waits for you. Nothing is committed to your repository without your yes.

Approving or declining the change

When a deployment is waiting for you, the Launch screen says Waiting for you, and the change also appears on the Health check card and your to-do list.

1. Click Review the change.
2. Read why it's needed, the file it changes, the checks it passed, and the exact change line by line.
3. Choose one:
   • Approve and commit. The route is committed to your branch as one commit by The Deployer. This same deployment then builds it and checks that the route answers on your live app. The commit doesn't start a second deployment.
   • Deploy without it. Nothing is committed. The deployment carries on and checks your app's main address instead.

If you deploy without it, the next deployment you start yourself asks again. Automatic deployments, such as a push or an automatic retry, don't stop again for a change you already declined.

Approving or declining needs the Deploy permission. Check now needs Retries and health checks.

Domain first, then the server's address

When The Deployer checks your live app, it tries your app's own domain over HTTPS first, then your app's other addresses, and the server's plain address last. A server behind a domain usually sends its plain address to HTTPS, and there is no certificate for a bare address, so checking the address alone would look like a failure when your app is fine.

Common problems

• "Not answering: not found (404)". The route isn't reachable at that address. Check the prefix your app puts its routes under, or let the next deployment add one.
• "Needs a login (401)" or "refused (403)". A health check must be open to everyone. Take it out from behind your app's login.
• "Answered with a web page, not a health check". Your site shows the same page for any address. Add a real route, or approve the one The Deployer writes.
• "Behind the app's access rules". You limited who can open your app, so the route can't be checked from outside. Keep the health check open: see Who can open your app.
• "Could not reach your app from here". None of your app's addresses answered. Check that the app is running and that your domain points at it.
• "The change could not be committed". The git connection can't write to your repository, or a branch rule stopped the push. Fix that and click Approve and commit again, or deploy without it.