How to check the health of a running Docker container using health checks and docker inspect

Keeping Docker Containers Healthy: Health checks, docker inspect, and a few trusted tricks

If you’re working with containers, you already know the feeling: a container is running, the lights are on, but something still feels off. The app responds slowly, or a critical endpoint goes silent. That’s not a win for reliability. Health isn’t just “is it on?”—it’s “is it doing its job well, right now?” In practice, a healthy container means it’s responsive, returns clean results, and can be trusted to recover if something hiccups. Let’s unpack how to check that health in a clear, practical way.

What does healthy mean in Docker terms?

Think of health as a little quality check for your container. Docker gives you a simple status you can rely on: healthy, unhealthy, or starting. This status isn’t automatic just because a container is alive. It comes from a health check—something that runs inside the container at intervals you define. If that check passes, Docker tags the container as healthy; if it fails consistently, the status flips to unhealthy. The exact meaning can vary by app, but the idea is the same: a healthy container should be able to handle requests, not crash in the middle of a busy afternoon.

Two reliable routes to measure health

There are two robust ways to gauge health in a running container:

1. Define a health check in the Dockerfile

2. Use docker inspect to read the health status and logs

Here’s the practical gist of each.

Health checks in the Dockerfile

A HEALTHCHECK directive in the Dockerfile is a built-in, low-friction way to tell Docker how to test your app. You’re basically telling Docker, “Hey, every so often, run this command to see if we’re good.” If the command exits with status 0, that’s a thumbs-up; any non-zero exit means trouble.

• Why it helps: You get an automatic, consistent signal that the container is functioning as expected. Or not.

• How to set it up: You add a line like HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 CMD curl -f http://localhost/health || exit 1

• The interval is how often the test runs.

• Timeout is how long you’ll wait for a response.

• Start-period gives the app a warm-up time after starting.

• Retries tell Docker how many failed checks to tolerate before flipping health status to unhealthy.

• Real-world note: The exact command should be cheap to run, idempotent, and reflect a meaningful readiness indicator for your service. If you’re not sure what endpoint to check, pick something that proves the app is responding in a meaningful way, not just “the process is still alive.”

Using docker inspect to verify health

If you already have a container running, or you’ve got a few that you’d like to inspect more deeply, docker inspect is your friend. It returns a lot of details in a structured way. When you define a health check, you’ll see a Health object inside the container’s state.

• Quick look: docker inspect --format '{{.State.Health.Status}}' container_id

• You’ll get a simple answer like healthy, unhealthy, or starting.

• Digging deeper: docker inspect --format '{{json .State.Health}}' container_id

• This reveals the health checks’ history, including each test’s status, exit codes, and timestamps.

• Why this matters: It’s not just a status label. The log array (Health.Log) shows why a test failed or passed, which is incredibly helpful for diagnosing flaky checks or slow recoveries.

• Caveat: If a container doesn’t have a HEALTHCHECK defined, the Health field won’t appear in the inspect output. In that case, docker ps will still show you whether the container is running, but not whether it’s healthy by the test you’d expect.

Why not rely on docker ps or logs alone?

It’s tempting to glance at docker ps and think, “All good—containers are up!” But that only tells you if the container process is running. It doesn’t reveal whether the app inside is healthy, responsive, or capable of handling requests. Logs can hint at problems, but they’re reactive, not proactive. A slow response or a 500 error might show up in logs, but by the time you notice, the problem could be affecting users. Health checks give you a proactive, automated signal about the container’s ability to serve.

A quick recipe you can try today

If you’re curious to see how this works in practice, here’s a compact, easy-to-follow path:

• Pick a small, meaningful health endpoint for your app. If it’s a web app, something like /health or /status is usually enough.

• Add a HEALTHCHECK line to your Dockerfile. Keep the command minimal and deterministic.

• Build and run your container as usual.

• Observe the health status with docker ps and docker inspect. See the healthy status appear after the checks pass.

• If something goes wrong, inspect the Health.Log array with docker inspect to understand which check failed and why.

A couple of practical examples

Example 1: A simple web app

• Dockerfile addition:

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

• Why this works: If the app is up, responds with 200 OK at /health, and doesn’t stall, the check passes.

• What you learn when you peek with docker inspect: You’ll see Health.Status switch between starting, healthy, or unhealthy as checks run, with a log history showing each attempt.

Example 2: A microservice that depends on a database

• HEALTHCHECK could orchestrate a quick DB ping rather than HTTP:

HEALTHCHECK --interval=60s --timeout=10s --start-period=15s --retries=2 CMD psql -h db.example -U user -c 'SELECT 1' >/dev/null || exit 1

• Caution: Health checks involving external services can be flaky if those services aren’t always ready. In such cases, tune the interval, start-period, and retries to fit your environment.

Common gotchas you’ll want to watch

• Don’t make the health check too heavy. It should be fast and safe to run frequently. A check that spins up extra processes or performs long-running queries can become a bottleneck.

• Make checks idempotent. A test should yield the same result if run multiple times in a row, so you don’t misinterpret transient hiccups.

• Use meaningful endpoints. The health check is supposed to reflect readiness and ability to serve traffic, not just “the app is alive.” If your app needs a database, an endpoint that verifies DB connectivity makes the signal far more useful.

• Separate readiness from liveness when needed. In some setups, you may want a liveness check that confirms the app is running, plus a readiness check that tests whether it can actually serve requests. This distinction matters for orchestration.

• If you change how your health is determined, remember to update the HEALTHCHECK directive or the corresponding docker inspect checks. A stale signal is worse than no signal.

Reading health status like a pro

Once you have a health check in place, here’s how you read the signal in everyday use:

• Check the surface status: docker ps shows whether the container is up and running. It isn’t a health signal by itself, but it confirms the process is alive.

• Ask Docker for the verdict: docker inspect --format '{{.State.Health.Status}}' container_id tells you if it’s healthy, starting, or unhealthy.

• Peek at the reasoning: docker inspect --format '{{json .State.Health}}' container_id reveals each test’s outcome and a chronological log.

• Use the log for rapid triage: If a test fails, the Health.Log array can show which test failed, how long it took, and when it passed last. This makes it easier to decide whether you should tweak the health check or investigate the underlying service.

A gentle nudge toward reliability

Health checks aren’t a silver bullet, but they’re a quiet, powerful habit. They make disasters less dramatic and recovery less dependent on human timing. When combined with solid logging, proper resource limits, and sensible restart policies, health checks help maintain a predictable, steadier flow. Your future self will thank you when a container misbehaves in production and Docker already has a plan to flag it and recover.

Tying it back to real-world work

Let me explain it this way: you wouldn’t leave a car idling in a garage without checking the fuel gauge, would you? You’d want something that tells you when something’s off and a simple way to verify it’s back in good shape. Health checks are that gauge for your containers. They’re small, they’re fast, and they’re incredibly practical when you’re building, testing, or deploying services.

A last thought, in case you’re juggling several containers at once

When you run a microservices set, health checks become the network of signals that keep the whole system robust. If one service starts failing its checks, orchestration tools can take corrective action—restarting the container, replacing it, or diverting traffic. It’s not magic; it’s a well-placed signal, a reliable test, and a little bit of patience as you tune the checks to your app.

In sum: how to check health, in a nutshell

• Define a health check in the Dockerfile with HEALTHCHECK to have Docker measure readiness automatically.

• Use docker inspect to confirm health status and to read the health test logs.

• Remember that docker ps shows only the running state, not health. Logs are informative but not a definitive health signal.

• Keep checks lightweight, deterministic, and meaningful for your app’s ability to serve traffic.

• Tweak intervals, timeouts, and retries as your environment evolves.

If you approach container health with that mindset, you’ll spot issues early and keep your services reliable for users. It’s a small shift in how you observe containers, but a big lift in how confidently you can deploy and operate them. And if you ever feel the need to revisit the basics, you’ll find the concepts are flexible enough to adapt as your stack grows. After all, a healthy container is a quiet win that compounds over time.