Why generate both a Dockerfile directive and a Compose block for the same check?

A HEALTHCHECK baked into the Dockerfile applies to any container run from that image, everywhere, while a Compose healthcheck: block only applies within that specific compose project and can override or add a healthcheck the image doesn't otherwise declare. Generating both from the same inputs keeps them in sync instead of drifting.

What's the difference between the three test types?

Curl runs a fixed HTTP check against a URL (`curl -f || exit 1`), Script runs a custom executable you provide inside the image in exec form (no shell involved), and TCP runs a bare port-reachability check with `nc -z `, useful for services with no HTTP endpoint like a database or message queue.

What does start_period actually do?

It's a grace period after the container starts during which failing healthchecks don't count toward the retries limit, so a slow-starting application (like a JVM warming up) isn't marked unhealthy before it's had a fair chance to become ready.

Why does the curl/TCP test end in '|| exit 1'?

HEALTHCHECK CMD treats a nonzero exit code as "unhealthy", and both curl and nc can exit nonzero on their own when the check fails, but appending `|| exit 1` makes that failure explicit and consistent even if the underlying tool's exit codes vary across versions.

Docker HEALTHCHECK Generator - Dockerfile + Compose

Overview

Introduction

Docker considers a container "running" the moment its main process starts, even if that process is still initializing and can't yet serve a single request, which is exactly the gap HEALTHCHECK closes.

This tool generates a Dockerfile HEALTHCHECK directive and the equivalent Compose healthcheck: block from the same test definition, so both stay consistent instead of being hand-written twice.

What Is Docker Healthcheck Generator?

A generator covering three common healthcheck shapes: an HTTP check via curl, a custom in-image script run in exec form, and a raw TCP port-reachability check via nc, each producing both Dockerfile and Compose syntax.

Interval, timeout, retries, and start_period are shared across both outputs, since Compose's healthcheck: fields map directly onto the Dockerfile HEALTHCHECK flags of the same name.

How Docker Healthcheck Generator Works

For curl and TCP checks, the test command runs via the shell (CMD in the Dockerfile, CMD-SHELL in Compose) so `|| exit 1` and other shell syntax work; for a script, it runs in exec form (a JSON array) since a script is already directly executable and doesn't need shell interpretation.

The same interval/timeout/retries/start_period values are rendered as --flag=value pairs on the Dockerfile HEALTHCHECK line and as separate keys under the Compose healthcheck: block, keeping the two representations in lockstep.

When To Use Docker Healthcheck Generator

Use it when adding a healthcheck to a new service, especially one with a startup period (a database migration, a JIT-compiled app) where a plain 'is the process running' check isn't enough.

It's also useful when you need the Dockerfile and Compose forms to match exactly, for example when the image is used both standalone and inside a Compose stack with an orchestrator watching container health.

Often used alongside Dockerfile Generator, Docker Compose Generator and Docker Swarm Stack Generator.

Features

Advantages

Produces matching Dockerfile and Compose syntax from one set of inputs, avoiding drift between the two.
Covers HTTP, custom script, and raw TCP checks, the three shapes that cover almost every real service.
Uses exec form for scripts and shell form only where shell syntax (like || exit 1) is actually needed.

Limitations

The TCP check relies on `nc` (netcat) being present in the image; minimal images (like distroless or scratch) may need a different tool or a tiny custom script instead.
Doesn't validate that the curl URL or script path actually exists or responds correctly inside the container, only that the syntax is well-formed.

Examples

An HTTP healthcheck for a web service

Input

testType: curl, curlUrl: http://localhost/health, interval: 30s, timeout: 10s, retries: 3, startPeriod: 5s

Output

# Dockerfile HEALTHCHECK directive
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost/health || exit 1

# Equivalent Compose healthcheck block
healthcheck:
  test: ["CMD-SHELL","curl -f http://localhost/health || exit 1"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 5s

Both forms use the shell command form since curl's exit code combined with || exit 1 needs shell interpretation.

Best Practices & Notes

Best Practices

Set start_period generously for services with a real warm-up cost (JVMs, database migrations) so early failed checks don't cause a restart loop.
Prefer a dedicated /health or /healthz endpoint over checking your main route, so the healthcheck doesn't depend on unrelated application logic.
For non-HTTP services (databases, queues), the TCP check is often the simplest reliable option if no protocol-specific health tool is available.

Developer Notes

Curl and TCP checks are emitted as shell-form commands (`CMD <command>` in the Dockerfile, `["CMD-SHELL", <command>]` in Compose) so that `|| exit 1` is interpreted correctly; the script test type instead emits exec form (`CMD ["<path>"]` / `["CMD", "<path>"]`) since a directly executable script needs no shell and exec form avoids an unnecessary shell process per health check tick.

Docker Healthcheck Generator Use Cases

Adding a healthcheck to a web service so an orchestrator (Swarm, Compose with depends_on: condition: service_healthy) can tell when it's actually ready
Health-checking a database or queue container over raw TCP when no HTTP endpoint exists
Keeping a Dockerfile-level and Compose-level healthcheck definition consistent for an image used in both contexts

Common Mistakes

Setting too short a start_period for a slow-starting service, causing it to be marked unhealthy (and possibly restarted) before it's actually ready.
Forgetting that `nc` might not be installed in a minimal or distroless base image, causing the TCP healthcheck command itself to fail.
Using exec form with shell operators like `||`, which fails silently since exec form never invokes a shell to interpret them.

Tips

Pair this with the Docker Compose Generator's healthcheck toggle, this tool's output is designed to drop straight into that generator's per-service healthcheck fields.
If your image doesn't have curl or nc, generate the script variant instead and ship a tiny purpose-built healthcheck script in the image.

Docker Healthcheck Generator