Health checks

A health check tells Docker and Coolify whether an application container is ready. Health checks are optional, but they provide a readiness signal for deployments and rolling replacement.

This routing behavior applies only when Coolify Proxy uses Traefik. When application health checks are enabled, Traefik removes unhealthy containers from routing. If every application container is unhealthy, Traefik can return 404 Not Found or No available server instead of forwarding the request.

Choose where to define the check

Location	Use it for	Availability
Configuration > Healthcheck	Configure an HTTP request or a command without changing the image definition.	Nixpacks, Railpack, Static, Dockerfile, and Docker Image applications.
Dockerfile `HEALTHCHECK`	Keep the check with the image and use it anywhere the image runs.	Any image built from a Dockerfile.
Docker Compose `healthcheck`	Configure a separate check for each service in a Compose application.	Docker Compose applications and user-defined Services.

Docker Compose applications do not use the standard application Healthcheck page. Define the check in each service's Dockerfile or in the Compose definition.

For a non-Compose Dockerfile application, Coolify detects the image's HEALTHCHECK and uses it instead of adding the health check configured in the dashboard. Remove the Dockerfile instruction and redeploy before switching that application to a Coolify-managed check.

Configure a health check in Coolify

Open the application, select Configuration > Healthcheck, then choose HTTP or CMD under Type.

HTTP checks require curl or wget inside the container

Coolify runs dashboard-configured HTTP checks from inside the application container. The final application image must contain curl or wget; installing either command only on the deployment server is not enough. Without one of them, the HTTP check fails and Docker marks the container unhealthy.

Choose HTTP when the application exposes an endpoint that reports whether it is ready to receive requests.

Create a readiness endpoint

Add an endpoint such as /health to the application. It should return success only when the process is ready, remain lightweight, and avoid changing application data.

Configure the request

Enter:

Method: GET or POST
Scheme: http or https
Host: normally localhost
Port: the port used inside the container; when empty, Coolify uses the first value from Ports Exposes
Path: the readiness path, such as /health

For a static application, Coolify uses port 80.

Verify the container has an HTTP client

Open the application's Terminal and confirm that the running container contains at least one supported client:

command -v curl || command -v wget

Use curl when the check depends on the selected HTTP method. The generated wget fallback performs its normal request behavior.

Test the endpoint

Open the application's Terminal and run the same internal request:

curl --fail http://localhost:3000/health

Replace 3000 and /health with the values entered in the health-check form. The command should exit with code 0.

Current response validation

The generated HTTP check currently uses the curl or wget exit status to determine health. Although Return Code and Response Text appear in the form, the generated check does not compare the response against those two fields.

Configure timing

These settings apply to both HTTP and CMD checks:

Setting	Behavior
Interval (s)	Time between health-check attempts. Must be at least one second.
Timeout (s)	Maximum time allowed for one attempt. Must be at least one second.
Retries	Consecutive failed attempts required before Docker marks the container unhealthy. Must be at least one.
Start Period (s)	Startup period before failures count toward the retry limit.

Give slow-starting applications enough Start Period (s) to complete migrations, cache loading, or other required initialization.

Save and enable the check

Select Save, then select Enable Healthcheck.

If the application is already running, restart or redeploy it so Coolify recreates the container with the health-check configuration. Disabling a check also requires the container configuration to be recreated before Docker stops running it.

Define the check with the application

Keep a health check in the Docker configuration when it should travel with the image or Compose service instead of being owned by one Coolify application.

Add a HEALTHCHECK instruction after installing the command used by the check:

FROM node:22-alpine

RUN apk add --no-cache curl
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
  CMD curl --fail http://localhost:3000/health || exit 1

CMD ["npm", "start"]

The command runs inside containers created from the image. It must use the internal listening port, and every binary referenced by HEALTHCHECK must be installed in the final image stage.

For a non-Compose Dockerfile application, Coolify detects this instruction and does not add its dashboard-configured health check to the generated container definition.

Health checks and rolling updates

During an application-level rolling update, a health check lets Coolify wait for the new container before removing the currently running container. If the replacement fails its check, Coolify can remove it and keep the healthy version running.

Rolling replacement also depends on container naming, networking, and port settings. Read Rolling updates before depending on zero-downtime replacement.

Troubleshoot a failed check

Open the application's Terminal.
Run the same request or command used by the health check.
Confirm the binary exists inside the container.
Confirm the check uses the internal container port rather than a public or host-mapped port.
Inspect Logs for startup or dependency failures.

Follow No available server when Traefik has no healthy target.

On this page