Docker Autoheal

Monitor and automatically restart unhealthy Docker containers.

How to Use

Docker Image Tags

The Docker image is available in multiple tag formats:

main (Development Build)
- Tracks the latest commit on the main branch.
- Recommended for: Developers and testers.
- Note: Updated with every commit; may include breaking changes.
latest (Stable Release)
- Points to the most recent stable release.
- Recommended for: General use in production environments.
A.B.C.D (Versioned Releases)
- Provides specific versioned releases for consistency.
- Recommended for: Environments that require version control.

Installation Options

You can pull the Docker image from either of the following registries:

ghcr.io/journeydocker/docker-autoheal:<tagname>
journeyover/docker-autoheal:<tagname>

1. Running with Docker CLI

Using UNIX Socket

docker run -d \
    --name autoheal \
    --restart=always \
    -e AUTOHEAL_CONTAINER_LABEL=all \
    -v /var/run/docker.sock:/var/run/docker.sock \
    journeyover/docker-autoheal:main

Using TCP Socket

docker run -d \
    --name autoheal \
    --restart=always \
    -e AUTOHEAL_CONTAINER_LABEL=all \
    -e DOCKER_SOCK=tcp://$HOST:$PORT \
    -v /path/to/certs/:/certs/:ro \
    journeyover/docker-autoheal:main

Using TCP with mTLS (HTTPS)

docker run -d \
    --name autoheal \
    --restart=always \
    --tlscacert=/certs/ca.pem \
    --tlscert=/certs/client-cert.pem \
    --tlskey=/certs/client-key.pem \
    -e AUTOHEAL_CONTAINER_LABEL=all \
    -e DOCKER_HOST=tcp://$HOST:2376 \
    -e DOCKER_SOCK=tcps://$HOST:2376 \
    -e DOCKER_TLS_VERIFY=1 \
    -v /path/to/certs/:/certs/:ro \
    journeyover/docker-autoheal:main

The required certificate files inside the container:

ca.pem
client-cert.pem
client-key.pem

Refer to Docker's documentation for configuring TCP with mTLS.

2. Docker Compose Example

services:
  autoheal:
    image: journeyover/docker-autoheal:main
    restart: always
    network_mode: none
    environment:
      - AUTOHEAL_CONTAINER_LABEL=autoheal-app
    deploy:
      replicas: 1
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/run/docker.sock:/var/run/docker.sock

3. Using in Your Container Image

You can enable autoheal by choosing one of the following methods:

Label-based: Add autoheal=true to your container labels.
Environment Variable: Set AUTOHEAL_CONTAINER_LABEL=all to monitor all running containers.
Custom Label: Use AUTOHEAL_CONTAINER_LABEL with an existing container label that has the value true.

Note: Ensure that your Docker images have a HEALTHCHECK configured. See Docker's Healthcheck Reference for details.

Optional Container Labels

Label	Description
`autoheal.stop.timeout=20`	Overrides stop timeout (in seconds) for container restarts.

Environment Defaults

Variable	Description
`AUTOHEAL_CONTAINER_LABEL=autoheal`	Monitors containers with the specified label set to `true`.
`AUTOHEAL_INTERVAL=5`	Checks container health every 5 seconds.
`AUTOHEAL_START_PERIOD=0`	Initial delay before the first health check (in seconds).
`AUTOHEAL_DEFAULT_STOP_TIMEOUT=10`	Maximum time (in seconds) Docker waits before forcefully stopping a container.
`AUTOHEAL_ONLY_MONITOR_RUNNING=false`	If `true`, only running containers are monitored (paused containers are ignored).
`AUTOHEAL_RESTART_THRESHOLD=5`	The maximum number of times a container can be restarted within the `AUTOHEAL_RESTART_WINDOW` before it is stopped.
`AUTOHEAL_RESTART_WINDOW=600`	The time window (in seconds) within which the restart count is tracked. If the container is restarted more than `AUTOHEAL_RESTART_THRESHOLD` times within this window, it will be stopped.
`DOCKER_SOCK=/var/run/docker.sock`	Unix socket path for Docker API requests.
`CURL_TIMEOUT=30`	Maximum time (in seconds) for `curl` requests to the Docker API.
`WEBHOOK_URL=""`	Sends a webhook notification if a container is restarted or fails to restart.

Local Testing & Development

To build and run locally:

docker buildx build -t autoheal .

docker run -d \
    -e AUTOHEAL_CONTAINER_LABEL=all \
    -v /var/run/docker.sock:/var/run/docker.sock \
    autoheal

JourneyDocker/docker-autoheal