Health Checks and Bootstrap Time
Bahriya uses health checks to determine whether your container is running correctly. If a health check fails repeatedly, the container is restarted automatically. This keeps your application available without manual intervention.
How health checks work
When you create an HTTP container, you specify a health check path — an HTTP endpoint in your application that returns a success response (any 2xx status code) when the application is healthy.
Bahriya checks this endpoint in two phases:
1. Startup phase
After your container starts, Bahriya gives it time to initialise before checking its health. This is controlled by the bootstrap time setting.
During the startup phase, Bahriya probes the health check endpoint every 5 seconds. If the endpoint responds successfully within the bootstrap time window, the container is considered started and moves to the liveness phase.
If the health check does not pass within the bootstrap time, the container is considered failed to start and is restarted.
Example: With a bootstrap time of 30 seconds, Bahriya makes up to 6 attempts (30s / 5s interval) before declaring a startup failure.
2. Liveness phase
Once the container has started successfully, Bahriya continues checking the health endpoint periodically. If the endpoint stops responding, the container is restarted.
This catches situations where your application hangs, deadlocks, or enters an unrecoverable state.
Bootstrap time
Bootstrap time is the maximum number of seconds Bahriya waits for your container to become healthy after starting.
| Setting | Default | Range |
|---|
| Bootstrap time | 30 seconds | 5 to 600 seconds |
How to choose a value:
- For lightweight applications that start in a few seconds, the default of 30 seconds is fine.
- For applications that load large datasets, run database migrations on startup, or have other slow initialisation steps, increase the bootstrap time accordingly.
- Setting it too low causes unnecessary restarts. Setting it too high delays detection of genuinely broken deployments.
A good rule of thumb: set it to roughly twice your application's typical startup time.
Health check path
The health check path should be a lightweight endpoint in your application that verifies the application is ready to serve traffic. Common patterns:
/health or /healthz — Returns 200 if the app is running./ready — Returns 200 only if the app has finished initialisation and can serve requests.
The endpoint should:
- Respond quickly (under 1 second).
- Not perform expensive operations (no database queries, no external API calls).
- Return a 2xx status code when healthy, any other status when unhealthy.
Worker containers
Worker containers do not require a health check. However, if your worker exposes a port and you configure a health check path, Bahriya will use it to monitor the worker's health in the same way as HTTP containers.
If no port or health check is configured, Bahriya monitors the worker process directly and restarts it if it crashes.
Troubleshooting
Container keeps restarting:
- Check your application logs to see if it is crashing during startup.
- Increase the bootstrap time if your application needs more time to initialise.
- Verify that the health check path returns a 2xx response. A common mistake is returning a 404 because the route doesn't exist.
Container starts but becomes unhealthy later:
- The liveness check is failing. Check whether your application is running out of memory, hitting connection limits, or encountering deadlocks.
- Review your application logs around the time of the restart.
