Health checks: proving a service is actually working
What a health check endpoint is, why a running process is not the same thing as a working one, and how to set the exact path Voroa probes after every deploy.
What this covers
A health check is a small endpoint in your application that answers only when the service is genuinely able to do its job. It exists because a running process proves very little: your code can start cleanly, fail to reach its database, and sit there answering nothing while every dashboard shows it as up. A good health check confirms the things your service cannot work without, and returns a failure when one of them is missing, so the platform can tell a working deploy from a broken one and refuse to send traffic to the broken one.
Setting your health check path
Open your service, go to Settings and then Health Checks. Two fields live there.
Health check path is the path Voroa requests to decide whether a new version is working. Leave it
blank and Voroa falls back to what it can tell on its own: that your service came up and started
answering. Set it to something like /healthz and the deploy is marked Live only once that path
answers with a 2xx status. The path is requested inside your own container, on the port your service
listens on, so it does not need to be reachable from the internet and it does not need to be listed in
any allow-list. A service built from a Dockerfile is checked the same way when its image has node,
python3, curl or wget; see Deploy with Docker for the details.
Startup timeout is how many seconds a new version gets to start answering before Voroa gives up on the deploy. Leave it blank to use the platform default. Raise it if your service is genuinely slow to boot - .NET, Java and large bundles often are. This waiting time counts towards your build minutes, so set it to what your service needs rather than to the highest number available.
Both apply from your next deploy, not to the version running right now.
Writing a health check endpoint that is worth having
The point of the endpoint is to answer for the things your service cannot work without. A handler that
returns 200 OK unconditionally tells you only that the web framework started, which you already knew.
A useful one checks the dependencies a request will actually need - the database connection, a cache, a
required credential being present - and returns a non-2xx status when one of them is missing.
Keep it cheap. It runs every few seconds for as long as your service is up, so it should not do real work, run an expensive query, or call a third-party API. Checking that a connection is alive is enough; running a report is not.
When a deploy fails its health check
If your service starts but never passes its health check, the deploy stops and any previous version keeps running. The build log then shows what the check saw on its last try, under “Output from your service before it stopped”, for example:
[app] Voroa health check: GET /health answered HTTP 404
A 404 usually means the path does not exist in your app - fix the path in Settings or add the route. A 500 means the route exists but failed, so look at your app’s own lines just above it. “failed: ECONNREFUSED” or “got no answer within 4s” means nothing answered on that port in time.
What happens to the previous version
Once the new version passes its check, traffic moves to it and the previous version is sent a stop signal (SIGTERM). It then has up to 30 seconds to finish the requests it is already serving before it is stopped for good. Background workers get the same signal and the same 30 seconds, but their previous copy is stopped before the new one starts, so two copies never run at once.
To use that time, handle SIGTERM in your app: stop accepting new connections, let in-flight requests finish, then exit. Most web frameworks do this when you call their server’s close method from a SIGTERM handler. An app that ignores the signal is stopped when the 30 seconds are up.
Services with no health check field
Background workers and scheduled jobs do not have this setting, and the page hides it for them rather than showing a control that would do nothing. Neither one serves HTTP requests, so there is no path to probe - Voroa waits for the process to start instead.