Monitors / Monitor Docker containers

Monitor Docker containers

Check that a container is running and healthy through the Docker Engine API, locally or through a read-only socket proxy.

A Docker container monitor reads the state of a container from the Docker Engine API. Use it for services that expose no port to check, or to catch a container stuck in a restart loop before its users notice.

How the check works

At each interval, Uptime Kotlin asks the engine for the state of the container and decides:

State of the container	Result	Message in the logs
Running, without `HEALTHCHECK`	Healthy	`Container web is running`
Running and `healthy`	Healthy	`Container web is running (healthy)`
Running, health check still `starting`	Failure	`Container web is running but its health check is still starting`
Running and `unhealthy`	Failure	`Container web is unhealthy`
Restarting	Failure	`Container web is restarting (restarted 4 times)`
Exited or dead	Failure	`Container web is exited (exit code 137)`
Not found	Failure	`Docker container check failed: container "web" not found on unix:///…`

A failure follows the usual retries: the monitor is Degraded while retries are left, then Unhealthy. Add a HEALTHCHECK to your images: without it, a container that runs but no longer serves is still seen as healthy.

Fill in the form

Pick Docker container in the Containers family of the Monitor protocol list.

Container name or ID: the name given by container_name or docker ps, for example my-container, or its ID. A leading / is removed.
Docker host: where to reach the engine. unix:///var/run/docker.sock by default.

Docker host	Meaning
`unix:///var/run/docker.sock`	The local engine, through its socket mounted in the container.
`tcp://host:2375`	An engine or a socket proxy over plain HTTP. `2375` when no port is set.
`http://host:port`	Same as `tcp://`.
`https://host:2376`	An engine over HTTPS. TLS client certificates are not supported.

Give Uptime Kotlin access to the engine

The checks run in the uptime-kotlin container, or in the workers in cluster mode. That container needs to reach the Docker host you set.

With a read-only proxy (recommended)

A socket proxy only exposes the container endpoints of the API. Add it to your compose.yaml and use tcp://docker-socket-proxy:2375 as the Docker host of your monitors:

YAML

docker-socket-proxy:
  image: tecnativa/docker-socket-proxy:latest
  container_name: uptime_kotlin_docker_proxy
  restart: unless-stopped
  environment:
    CONTAINERS: 1
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro

Do not publish its port: only the Uptime Kotlin containers of the same Compose project need to reach it.

With the socket mounted

Mount the socket in the uptime-kotlin service and keep the default Docker host. The image runs as user 1001, so it also needs the group that owns the socket on the host:

Terminal

stat -c %g /var/run/docker.sock

Then add that group to the service, here 999:

YAML

uptime-kotlin:
  image: ghcr.io/theomeunier/uptime-kotlin:latest
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro
  group_add:
    - '999'

Access to the Docker socket is equivalent to root access on the host, and :ro does not change that. Prefer the proxy.

Common errors

cannot reach the Docker socket: the socket is not mounted, or the group of the socket is missing from group_add.
Docker Engine answered HTTP 403: the proxy does not allow the container endpoints. Check CONTAINERS: 1.
container "web" not found: the name does not match. Run docker ps --format '{{.Names}}' on the host to list the exact names.

Suggest a change on GitHub