A wget Healthcheck vs a Client Inside the Image: Containers That Pass Before the App Listens

Ivo Markham

Ivo Markham

September 22, 2026

A wget Healthcheck vs a Client Inside the Image: Containers That Pass Before the App Listens

Your Compose stack went green. The reverse proxy flipped to the new container. The first real request got a connection reset, or worse, a 502 that lasted just long enough for someone to notice. The healthcheck did exactly what you asked: it proved something was listening. It did not prove the process you care about was ready.

That gap is where the wget-or-curl healthcheck and the “client inside the image” healthcheck stop being style preferences and start being different failure modes. One checks the network surface Docker can see. The other checks the same codepath your users hit, from inside the same filesystem and dependency tree as the app. Both can lie. They lie for different reasons.

This is not a lecture on Kubernetes probes. It is the decision solo operators make every time they paste a healthcheck block into a Compose file and hope the next deploy will not race the database migration.

What “healthy” actually means in Compose

Docker’s healthcheck answers a narrow question: did this command exit zero within the timeout? Compose then uses that bit for depends_on: condition: service_healthy, for restart policies, and for the green badge that makes you stop staring at docker compose ps.

None of that requires the command to understand your application. A TCP open on port 8080 is enough for many default snippets. A wget -qO- http://127.0.0.1:8080/ is enough for slightly less naive ones. Your app can still be mid-migration, still loading plugins, still waiting on a lock, still serving a placeholder process that is not the real worker.

So the tool choice is really a bet: do you want a cheap external signal that the process is up, or a heavier signal that the process can do useful work?

Laptop and mini PC on a desk used for homelab container work

The wget (or curl) healthcheck: cheap and outside the app

The classic pattern looks like this:

healthcheck:
  test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:8080/health"]
  interval: 10s
  timeout: 3s
  retries: 3
  start_period: 40s

Or the curl variant with -f so non-2xx fails. The appeal is obvious. You do not need a special binary. Official images often include wget or curl. The check speaks HTTP, which matches how the proxy talks to the container. If the listen socket is not open yet, the check fails. If the process crashed after bind, the check fails.

For a static site, a tiny Go binary that binds and is immediately ready, or a sidecar that only needs “port open,” this is fine. It is also fine as a liveness signal when you already trust a separate readiness path.

Where it breaks for solo stacks:

  • The process listens before it is ready. Many frameworks bind the HTTP server early, then finish boot in the background. wget gets 200 from a “starting” route, or even from a default page that has nothing to do with your app’s readiness contract.
  • You hit the wrong surface. Checking / while traffic goes to /api behind a path prefix means the healthcheck never sees the cold path that actually fails.
  • The tool is not in the image. Distroless and slim images ship neither wget nor curl. People “fix” that by baking a busybox wget into a custom image—which is already halfway to the other pattern—or by using Docker’s CMD-SHELL with something that is not there.
  • Success is too cheap. A 200 from a reverse proxy inside the same container, or from a static file server that started first, can green-light a stack while the real app process is still dead.

wget is not wrong. It is a network probe wearing an HTTP costume. Treat it that way.

The client inside the image: same binary, same contract

The other pattern puts the check next to the app:

  • a tiny CLI the project already ships (myapp healthcheck, vault status, redis-cli ping)
  • a script that imports the same config loader and opens the same DB pool
  • an official health binary that talks the app’s protocol, not generic HTTP

Example shape:

healthcheck:
  test: ["CMD", "/usr/local/bin/myapp", "ready"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 60s

The point is not “more Docker.” The point is that the check fails for the same reasons a request would fail: schema not migrated, dependencies unreachable, feature flags not loaded, worker not registered. If ready returns zero only after those gates, Compose’s green badge starts meaning something closer to “safe to send traffic.”

This is the pattern that saves you when the HTTP server accepts connections while the migration lock is still held. wget would have been happy. Your first user would not.

Glass jars on a metal shelf suggesting sealed container boundaries

When wget still wins

Prefer the external HTTP/wget check when:

  • You do not control the image. Third-party containers often expose a documented /health or /ready and nothing else. Fighting that with a sidecar client is usually worse than using their published probe.
  • The readiness contract is already HTTP. If the app’s own docs say “wait for 200 on /ready,” wget is the intended client. Do not invent a richer check that the maintainers never promised.
  • The failure mode you care about is “process died / port closed.” Restarts and crash loops are well served by a dumb probe. You are not trying to validate business logic every ten seconds.
  • You need a check that survives app-language changes. A wget against a stable health URL keeps working when you rewrite the service from Node to Go, as long as the URL stays.

In other words: wget is a good boundary check. It is a weak application check.

When the in-image client wins

Prefer a client (or app subcommand) inside the image when:

  • Boot has phases. Listen → migrate → warm caches → accept traffic. Only the last state should be healthy for depends_on.
  • Protocol is not HTTP. Postgres, Redis, MQTT, custom TCP: a proper client ping beats “is something on 5432.”
  • Slim images already ship the CLI. pg_isready, redis-cli, and many *-cli tools exist for this exact job. Using them is not exotic; using wget against a port that never spoke HTTP is.
  • You own the Dockerfile. Adding a ready command costs little and removes an entire class of “compose said healthy, proxy said 502” nights.

The cost is real: the healthcheck now depends on your app’s packaging. If the binary path changes, the check breaks. If the ready command opens a DB connection on every interval, you can load a small database harder than you meant to. Keep it light, idempotent, and documented.

The hybrid most homelabs actually need

A useful middle path for apps you own:

  1. Teach the app a cheap /ready that only returns 200 when migrations and critical deps are done.
  2. Probe that URL with wget/curl from the healthcheck.
  3. Keep a separate, stricter check for jobs that are not HTTP (queue workers, cron sidecars) using the in-image CLI.

That looks like “just wget,” but the honesty moved into the application. The probe stayed dumb on purpose. Dumb probes against honest readiness endpoints beat smart probes against dishonest ones.

If you cannot change the app, you are stuck with whatever the image offers. Then the decision collapses to: use their documented probe, or wrap the container with a Compose-level gate you control (a small init container pattern, or a script that blocks depends_on until a real client succeeds). Do not pretend a generic wget on port 80 is a readiness contract the upstream never published.

start_period, retries, and the race you are actually fighting

People reach for wget versus in-image clients when the real bug is timing. A slow JVM or a cold SQLite migrate needs start_period (and, on newer engines, thoughtful intervals) so early failures do not burn retries. Neither probe style fixes a start window that is shorter than boot.

Set start_period from measured cold start, not from optimism. Watch one deploy with logging on the ready path. If healthy flips before the last migration line, your probe is wrong—or your ready definition is. Fix the definition first. Changing wget to a custom client will not help if both call the same premature endpoint.

Also separate liveness from readiness in your head even if Compose only has one healthcheck slot. A process that is wedged but still accepting TCP should fail readiness for traffic and may deserve a restart. A process that is busy with a long legitimate job should not. In-image checks are better at that distinction because they can ask the app. wget can only ask the socket.

A practical chooser

Use this when you are staring at a blank healthcheck block:

  • Third-party image with a documented HTTP ready URL → wget/curl that URL. Stop there.
  • Database or broker → official CLI ping (pg_isready, redis-cli ping). Not wget.
  • Your own HTTP service with phased boot → implement /ready, then wget it. Optionally add myapp ready for non-HTTP workers in the same repo.
  • Distroless app image → either a tiny static health binary you copy in, or an external checker service. Do not assume shell tools exist.
  • You only care that the container did not crash-loop → simplest port or HTTP check is enough; invest elsewhere.

If two services must start in order, put the stricter check on the dependency, not on the dependent. A perfectly honest frontend healthcheck will still 502 if Compose marked the API healthy too early.

What green should mean on a one-person stack

On a homelab or a one-person VPS, “healthy” should mean “I would send a friend’s traffic here.” That is a higher bar than “PID is alive.” wget can meet that bar when the URL is honest. An in-image client can meet that bar when the command encodes the real gates. Neither meets it when you copy a snippet that spiders / on a framework that returns 200 while still installing plugins.

Pick the probe that fails when you would refuse traffic. Then measure boot once, set start_period from reality, and leave the badge alone until the next deploy proves it again. The goal is not a prettier Compose file. The goal is a container that stops passing before the app listens for real work.

More articles for you