Application

Healarr

Description

Healarr monitors Docker containers for unhealthy status and automatically performs configurable actions (restart, stop, pause, unpause, kill) with retry logic to prevent false positives. It supports filtering containers by label, environment variable, or name, and includes comprehensive logging.

Key Features:

• Monitors Docker containers with health checks for unhealthy status
• Configurable retry logic to verify unhealthy state before taking action
• Multiple filtering options: by label, environment variable, or container name (OR logic)
• Support for direct Docker socket or socket proxy connection
• Configurable actions: restart, stop, pause, unpause, kill
• Structured logging with configurable log levels
• Notification to multiple services via Apprise
• Graceful shutdown handling

Build notes

Arch Linux base with Docker CLI.

Docker Socket Access

Healarr supports two methods for accessing the Docker daemon:

Method 1: Direct Docker Socket Mount (Traditional)

Mount the Docker socket directly into the container:

-v /var/run/docker.sock:/var/run/docker.sock

Method 2: Docker Socket Proxy (Recommended for Security)

Use a Docker socket proxy container for enhanced security:

-e DOCKER_HOST=tcp://dockersocket:2375

Required proxy permissions:

• CONTAINERS=1 - Read container information
• POST=1 - Allow POST requests (for restart/stop/etc)
• ALLOW_RESTARTS=1 - Allow restart action
• ALLOW_STOP=1 - Allow stop action (if using stop action)
• ALLOW_START=1 - Allow start action (if using unpause after pause)

See examples below for complete socket proxy setup.

Usage

docker run -d \
    --name=<container name> \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v <path for config files>:/config \
    -v /etc/localtime:/etc/localtime:ro \
    -e DOCKER_HOST=<tcp://dockersocket:2375> \
    -e MONITOR_INTERVAL=<seconds between health checks> \
    -e RETRY_COUNT=<number of retry checks> \
    -e RETRY_DELAY=<seconds between retries> \
    -e ACTION=<restart|stop|pause|unpause|kill|none> \
    -e CONTAINER_LABEL=<label to filter> \
    -e CONTAINER_ENV_VAR=<env var to filter> \
    -e CONTAINER_NAME=<comma separated names> \
    -e APPRISE_NOTIFICATION_SERVICES=<comma separated apprise service URLs> \
    -e LOG_LEVEL=<0|1|2|3> \
    -e ENABLE_HEALTHCHECK=<yes|no> \
    -e HEALTHCHECK_COMMAND=<command> \
    -e HEALTHCHECK_ACTION=<action> \
    -e HEALTHCHECK_HOSTNAME=<hostname> \
    -e UMASK=<umask for created files> \
    -e PUID=<uid for user> \
    -e PGID=<gid for user> \
    ghcr.io/binhex/arch-healarr

Please replace all user variables in the above command defined by <> with the correct values.

Required Mount:

• /var/run/docker.sock:/var/run/docker.sock - Docker socket access (required for container management) OR
• DOCKER_HOST environment variable - For use with Docker socket proxy (see examples below)

Environment Variables

Note: Filters (CONTAINER_LABEL, CONTAINER_ENV_VAR, CONTAINER_NAME) use OR logic. If no filters are specified, all containers with health checks will be monitored.

Access application

N/A, daemon only. Check logs for monitoring activity.

Examples

Example 1: Monitor all containers, restart unhealthy ones

docker run -d \
    --name=healarr \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /apps/docker/healarr:/config \
    -v /etc/localtime:/etc/localtime:ro \
    -e MONITOR_INTERVAL=60 \
    -e RETRY_COUNT=3 \
    -e RETRY_DELAY=10 \
    -e ACTION=restart \
    -e LOG_LEVEL=1 \
    -e UMASK=000 \
    -e PUID=99 \
    -e PGID=100 \
    ghcr.io/binhex/arch-healarr

Example 2: Monitor specific containers by name

docker run -d \
    --name=healarr \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /apps/docker/healarr:/config \
    -v /etc/localtime:/etc/localtime:ro \
    -e MONITOR_INTERVAL=120 \
    -e RETRY_COUNT=5 \
    -e RETRY_DELAY=15 \
    -e ACTION=restart \
    -e CONTAINER_NAME="sonarr,radarr,plex,jellyfin" \
    -e LOG_LEVEL=1 \
    -e UMASK=000 \
    -e PUID=99 \
    -e PGID=100 \
    ghcr.io/binhex/arch-healarr

Example 3: Monitor containers with specific label

docker run -d \
    --name=healarr \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /apps/docker/healarr:/config \
    -v /etc/localtime:/etc/localtime:ro \
    -e MONITOR_INTERVAL=90 \
    -e RETRY_COUNT=3 \
    -e RETRY_DELAY=10 \
    -e ACTION=restart \
    -e CONTAINER_LABEL="healarr.monitor=true" \
    -e LOG_LEVEL=1 \
    -e UMASK=000 \
    -e PUID=99 \
    -e PGID=100 \
    ghcr.io/binhex/arch-healarr

Example 4: Monitor containers with specific env vars

docker run -d \
    --name=healarr \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /apps/docker/healarr:/config \
    -v /etc/localtime:/etc/localtime:ro \
    -e MONITOR_INTERVAL=60 \
    -e RETRY_COUNT=2 \
    -e RETRY_DELAY=20 \
    -e ACTION=stop \
    -e CONTAINER_ENV_VAR="AUTO_HEAL=true" \
    -e LOG_LEVEL=2 \
    -e UMASK=000 \
    -e PUID=99 \
    -e PGID=100 \
    ghcr.io/binhex/arch-healarr

Example 5: Using Docker Socket Proxy (LinuxServer.io)

First, create a Docker socket proxy container:

docker run -d \
    --name=dockersocket \
    --restart=unless-stopped \
    -v /var/run/docker.sock:/var/run/docker.sock:ro \
    -e CONTAINERS=1 \
    -e POST=1 \
    -e ALLOW_RESTARTS=1 \
    -e ALLOW_STOP=1 \
    -e ALLOW_START=1 \
    --network=docker-management \
    lscr.io/linuxserver/socket-proxy:latest

Then run Healarr using the socket proxy:

docker run -d \
    --name=healarr \
    -v /apps/docker/healarr:/config \
    -v /etc/localtime:/etc/localtime:ro \
    -e DOCKER_HOST=tcp://dockersocket:2375 \
    -e MONITOR_INTERVAL=60 \
    -e RETRY_COUNT=3 \
    -e RETRY_DELAY=10 \
    -e ACTION=restart \
    -e LOG_LEVEL=1 \
    -e UMASK=000 \
    -e PUID=99 \
    -e PGID=100 \
    --network=docker-management \
    ghcr.io/binhex/arch-healarr

Important Note: Both containers MUST be on the same Docker network (docker-management in this example).

Notes

User ID (PUID) and Group ID (PGID) can be found by issuing the following command for the user you want to run the container as:-

id <username>

If you appreciate my work, then please consider buying me a beer :D

Documentation | Support forum