How can you add, change, or disable a container's health probe at `docker run` time without rebuilding the image, and when is that the right move?

## Two places a probe can be defined A health check can be declared in the **image** (`HEALTHCHECK` in the Dockerfile, stored in the image config) or supplied at **container creation** (`docker run --health-*`, or a Compose `healthcheck:` block). The container-level definition wins: it replaces whatever the image declared. That layering exists because the right probe is partly a property of the software (which endpoint means "ready") and partly of the deployment (how fast do you need detection, how slow is startup on this hardware, is this a dev laptop or a production host). ## The run-time flags | Flag | Overrides | |---|---| | `--health-cmd` | the probe command itself | | `--health-interval` | gap between probes | | `--health-timeout` | maximum duration of one probe | | `--health-retries` | consecutive failures needed to flip to unhealthy | | `--health-start-period` | startup grace window | | `--health-start-interval` | probe frequency during the start period (Docker 25.0+) | | `--no-healthcheck` | disables health checking entirely | A subtlety: `--health-cmd` takes a **string**, and Docker runs it through the container's shell — so it needs `/bin/sh` present. In a shell-less image you cannot express an arbitrary command this way, which is one of the few places where the Dockerfile's exec form (`HEALTHCHECK CMD ["/bin/healthcheck"]`) is strictly more capable. Another: overrides apply at container creation. Changing them later means recreating the container — you cannot retune a probe on a running container the way you can with some other settings. ## Disabling: two spellings - **`docker run --no-healthcheck`** — this container has no probe. - **`HEALTHCHECK NONE` in a Dockerfile** — images built from this one inherit no probe. - **Compose**: `healthcheck: { disable: true }`. Disabling is legitimate more often than people expect. A base image's check may test something your build removed or reconfigured; a batch job that runs for 40 seconds has nothing meaningful to probe; and during an incident, silencing a flapping probe keeps a consumer (an autoheal watcher, a Swarm scheduler) from acting while you look at the container. ## Compose as the usual home for these values In practice most teams put the *command* in the Dockerfile — it belongs to the software — and let the *timings* be overridable per environment in Compose or the deployment manifest. Compose's `healthcheck:` block accepts `test`, `interval`, `timeout`, `retries`, `start_period`, `start_interval`, and `disable`, mirroring the flags exactly, and the `test` list form (`["CMD", ...]` vs `["CMD-SHELL", "..."]`) lets you choose exec or shell semantics explicitly — which the `--health-cmd` flag does not. ## The tradeoff to state out loud Run-time overrides are configuration drift waiting to happen. If the probe only exists in one operator's `docker run` line, then anyone else who starts the image gets no check, or a stale one, and nothing in the image records what "healthy" is supposed to mean. Symptoms of having gone too far this way: the same `--health-cmd` copy-pasted across several scripts with slightly different intervals, or a production incident where the container had no probe because a flag was dropped from a deploy script. The healthy division: - **Image**: the probe command and sensible default timings — so every consumer gets a working check for free. - **Deployment config**: environment-specific timing overrides, checked into version control alongside the rest of the deployment. - **Ad-hoc `docker run` flags**: experiments and debugging, not the durable answer. ## Verifying an override took effect After starting the container, confirm what is actually configured rather than what you intended: ``` docker inspect --format '{{json .Config.Healthcheck}}' api ``` That prints the effective test, interval, timeout, retries, and start period for that container — including whether a `--no-healthcheck` left it empty. Pair it with `.State.Health` to see what the probe is currently reporting.