Docker Health Checks Before Proxmox VE 9.2 Upgrade
Docker health checks give Proxmox VE 9.2 upgrade teams a pass/fail gate for OCI LXC apps, proving services stay healthy before, after, and rollback to cut guesswork.

On this page
Docker health checks give you a fast, repeatable signal that an application inside a Proxmox OCI LXC is still serving requests before you upgrade the host to Proxmox VE 9.2. Run those checks from the host, record the result, and compare it after the upgrade or after a rollback. The outcome is a small pass/fail gate that turns "the container looked started" into "the app was healthy at these timestamps."
Key Takeaways
- Health first: Check the application before the host upgrade so you can tell a new failure from an old one.
- Host-side proof: Use the Proxmox container exec feature to test the app without opening a shell inside the LXC.
- Snapshot pairing: Take an OCI LXC snapshot only after the health check passes, so rollback has a clean target.
- App only: A Docker health check proves the containerized service, not the host kernel, storage, or backup path.
- Short window: A 90-second health window is usually enough for a simple web service to become ready after a reboot.
Why Docker health checks matter before a VE 9.2 upgrade
Proxmox VE 9.2 upgrades touch the host kernel, systemd, storage, and network stack. Those changes can reach into an OCI LXC that runs Docker Engine, even when the container itself is not rebuilt. A container can be running while its application is not answering requests, while the Docker daemon is stuck, or while the container's network path is half-broken.
An OCI LXC is usually unprivileged, and Docker inside it depends on nesting and user namespace support. A privileged LXC can make Docker inside LXC easier, but it also widens the blast radius when something goes wrong. The health check is the signal that tells you whether the application path survived the change, regardless of which container security model you chose.
The usual first checks are too shallow. A running LXC does not prove Docker started, Docker started does not prove the app can read its database, and the app can read its database does not prove it can answer an HTTP request. A Docker health check gives you one narrow signal that the application path you care about is working.
If the OCI LXC is not yet running Docker in a way you trust, start with Docker in OCI LXC on Proxmox VE 9.2: Setup and Backup. This article assumes the container already runs Docker Engine 27.3.1 and at least one application container with a name you can target.
How to set up a Docker health check that works inside an OCI LXC
A useful health check is not just "the process is alive." It should fail when a request to the application fails. For a web service, that means an endpoint that returns success only when dependencies are ready. For a worker, it may mean a queue-depth or last-heartbeat check.
Make the endpoint prove the app is usable
A good health endpoint is narrow but meaningful. It may check the database connection, a cache connection, a required configuration file, or a background worker heartbeat. It should not check external SaaS providers unless those providers are part of the request path you are testing.
Before adding the check to the container definition, run the same command manually inside the application container:
pct exec 210 -- docker exec web curl -fsS http://127.0.0.1:8080/health
If that command fails, the health check will fail too. If it succeeds, you have a command that Docker can run on a schedule.
Give the container a realistic start period
Many apps fail the first health check because the application has not finished connecting to its dependencies. Docker supports a start period, which gives the container time to boot before failed checks count against it.
services:
web:
image: example/web:1.0.0
ports:
- "127.0.0.1:8080:8080"
healthcheck:
test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8080/health"]
interval: 10s
timeout: 3s
retries: 3
start_period: 20s
This configuration checks every 10 seconds, allows 3 seconds for each request, and tolerates 20 seconds of startup time before marking the container unhealthy. A service that normally takes 12 seconds to warm up will not cause false failures.
Test the command before making it a health check
If you use Docker Compose, bring the service up and inspect its reported status:
pct exec 210 -- docker compose -f /srv/web/docker-compose.yml up -d
pct exec 210 -- docker compose -f /srv/web/docker-compose.yml ps
The compose status output should show the health state. If it does not, the health check may be missing, malformed, or dependent on a tool that is not present inside the image.
What should the health check actually test?
The health check should test the failure mode you care about. For an HTTP service, a request to a health endpoint is the simplest useful test. For a background worker, checking a process may be enough, but checking a heartbeat file or queue metric is better.
HTTP checks are best for services
HTTP checks catch many real upgrade regressions: DNS changes, proxy misconfiguration, missing environment variables, database connection failures, and broken TLS paths. They also produce a clear pass/fail result that can be scripted from the Proxmox host.
Process checks are okay for workers
A worker container may not expose HTTP. In that case, the health check can confirm that the worker is still processing jobs. The important part is that the check fails when the worker is stuck, not merely when the process is missing.
Avoid checks that depend on the host
Do not make the health check depend on a file mount that only exists when a Proxmox host service is running, unless that dependency is part of the application's definition of health. Otherwise the check may fail for reasons unrelated to the containerized app.
| Check | What it proves | What it misses |
|---|---|---|
| Container running status | The OCI LXC is started on the host | Whether Docker or the application works |
| Docker container list | The application container process is up | Whether the service answers requests |
| Docker health check | A command inside the app container succeeded | Host kernel, storage, or network changes outside the container |
| Docker daemon active status | The Docker daemon is active | Whether the app has a usable health endpoint |
| Backup restore test | The container can be restored from backup | Whether the restored app passes health checks after VE 9.2 |
How to run the health check from the Proxmox host
Running the check from the host is what makes it useful for an upgrade. You do not need to log into the LXC, and you can capture the result in a script that runs before and after the upgrade.
Proxmox can execute commands inside a running container. The health state is stored in the application container's Docker metadata, so the host can ask for it directly:
pct exec 210 -- docker inspect -f '{{.State.Health.Status}}' web
pct exec 210 -- docker inspect -f '{{.State.Health.FailingStreak}}' web
pct exec 210 -- docker inspect --format '{{json .State.Health}}' web
The first command returns starting, healthy, or unhealthy. The second command tells you how many consecutive checks have failed. The third command returns a JSON object that is useful when you want to save the full health log for a failed upgrade attempt.
{
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2026-02-10T14:03:21.112345678Z",
"End": "2026-02-10T14:03:21.212345678Z",
"ExitCode": 0,
"Output": ""
}
]
}
A full health gate is simple enough to put on the host:
#!/usr/bin/env bash
CTID=210
APP=web
WAIT_SECONDS=90
INTERVAL=5
for _ in $(seq 1 $((WAIT_SECONDS / INTERVAL))); do
status=$(pct exec "$CTID" -- sh -c "docker inspect -f '{{.State.Health.Status}}' $APP 2>/dev/null || echo missing" 2>/dev/null || echo missing)
echo "$(date +%H:%M:%S) $status"
if [ "$status" = "healthy" ]; then
exit 0
fi
sleep "$INTERVAL"
done
echo "health check did not become healthy within ${WAIT_SECONDS}s"
exit 1
Save it as a script on the Proxmox host, make it executable, and run it before the upgrade:
chmod +x health-gate.sh
./health-gate.sh
If the script exits 0, the application was healthy within the 90-second window. If it exits 1, stop and look at the container logs before changing the host.
How to use the check during a VE 9.2 upgrade and rollback
The value of the health check comes from using it at three points: before the upgrade, after the upgrade, and after any rollback. That gives you a timeline instead of a vague memory of what worked.
-
Confirm the application name and current health:
pct exec 210 -- docker inspect -f '{{.State.Health.Status}}' web -
Run the health gate before touching the host:
./health-gate.sh -
Take an OCI LXC snapshot only after the gate passes:
pct snapshot 210 pre-ve92 --description "Docker healthy before VE 9.2" -
Upgrade the Proxmox host and reboot:
apt update apt dist-upgrade reboot -
After the host comes back, make sure the container is started and the Docker daemon is active:
pct status 210 pct exec 210 -- systemctl is-active dockerIf the container is stopped, start it before continuing:
pct start 210 -
Run the same health gate again:
./health-gate.sh -
If the gate fails, collect the health log and recent application logs:
pct exec 210 -- docker inspect --format '{{json .State.Health}}' web pct exec 210 -- docker logs web --tail 50 -
If the application was healthy before the upgrade and the host rollback plan calls for a container rollback, restore the snapshot:
pct rollback 210 pre-ve92 ./health-gate.sh
For the broader host-level rollback plan, see Proxmox VE 9.2 Snapshot Rollback Test Before Upgrade. For OCI LXC patching patterns that combine snapshots with PBS, see Patching OCI LXC on Proxmox VE 9.2 With Snapshots and PBS.
What the health check cannot prove
A Docker health check is a narrow test, and that is the point. It proves the application container passed its own command within the configured retries. It does not prove the Proxmox host kernel is compatible with Docker, that storage is healthy, that PBS can restore the container, or that the host's network path is fully correct.
The tradeoff is maintenance. A health check needs an endpoint, a command, or a small helper inside the image. If the image is minimal, the health check may fail simply because the required tool is missing. In one practical case, a distroless application image had no HTTP client, so the health check failed with a command-not-found error even though the service was answering requests correctly. The fix was not to make the app more complex; it was to use a health command that existed inside the image.
Another practical gotcha appears after a host reboot. The container may start before Docker's network or storage dependencies are fully ready. A 90-second health window covers that short startup race in many homelab and small production setups. If the app needs longer, increase the window rather than removing the check.
Conclusion
Docker health checks turn a Proxmox VE 9.2 upgrade into a measurable event for OCI LXC workloads. Run the same health gate before the upgrade, after the reboot, and after any rollback, and you know whether the application path actually survived the change. Your next step is to add one health check to a single container, take a snapshot after it passes, and repeat the gate on the next VE 9.2 patch window.


