🐞 Bug: Portainer fails health checks

[mgrecar]

Bug Description

In setting up Portainer, I found that the health check as configured in this repo is never successful, even when I can access and use Portainer just fine.

Expected Behavior

I expect a health check that succeeds when the container is healthy.

Actual Behavior

OCI runtime exec failed: exec failed: unable to start container process: exec: "pgrep": executable file not found in $PATH

Screenshots

No response

Operating System

Linux

Tailscale Version

1.98.4 Linux 6.17.0-35-generic

Docker Version

29.5.3 (API: 1.54)

Relevant Logs or Error Messages

Docker Compose Configuration

Environment Configuration (.env file)

Additional Context

No response

[jackspiering]

Thanks for reporting this and for testing it.

After investigating, the issue is that Portainer uses the official portainer/portainer-ce image, which is an extremely minimal container image. It only contains the Portainer binary and does not include common utilities such as sh, bash, ls, wget, curl, nc, or pgrep.

Because Docker health checks execute commands inside the container, there is no reliable built-in tool available that can be used to verify the Portainer web interface or API from within the container itself.

While it is possible to switch to the Alpine-based Portainer image to gain access to tools like wget, that would require using a different image variant solely for health checking purposes.

The recommended approach is to monitor Portainer externally using a third-party monitoring solution such as Uptime Kuma, which can periodically check the Portainer URL or API endpoint and provide much more meaningful availability monitoring than an in-container health check.

For users who require an internal health check, the Alpine variant (portainer/portainer-ce:alpine) can be used, as it includes additional utilities such as wget. However, we do not plan to switch the repository to the Alpine image by default at this time. If there is sufficient interest from users, please create an issue or PR.

Given these limitations, I’ll open a new PR to remove the Portainer health check from the template. The current health check cannot be implemented reliably with the official Portainer image and may lead to false unhealthy states. The container already uses restart: always, so Docker will still automatically restart Portainer if the process exits.