https://github.com/binhex/arch-healarr

Healarr monitors Docker containers for unhealthy status and automatically performs configurable actions.
https://github.com/binhex/arch-healarr

automated automation docker heal healarr healing health healthcheck restart

Last synced: 5 months ago
JSON representation

Healarr monitors Docker containers for unhealthy status and automatically performs configurable actions.

Host: GitHub
URL: https://github.com/binhex/arch-healarr
Owner: binhex
License: gpl-3.0
Created: 2025-12-29T12:30:31.000Z (6 months ago)
Default Branch: main
Last Pushed: 2026-01-02T11:54:35.000Z (6 months ago)
Last Synced: 2026-01-03T17:18:43.266Z (6 months ago)
Topics: automated, automation, docker, heal, healarr, healing, health, healthcheck, restart
Language: Shell
Homepage: https://github.com/binhex/arch-healarr
Size: 43 KB
Stars: 4
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

          # Application

[Healarr](https://github.com/binhex/arch-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:

```bash

-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:

```bash

-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

```bash

docker run -d \

    --name= \

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

    -v :/config \

    -v /etc/localtime:/etc/localtime:ro \

    -e DOCKER_HOST= \

    -e MONITOR_INTERVAL= \

    -e RETRY_COUNT= \

    -e RETRY_DELAY= \

    -e ACTION= \

    -e CONTAINER_LABEL= \

    -e CONTAINER_ENV_VAR= \

    -e CONTAINER_NAME= \

    -e APPRISE_NOTIFICATION_SERVICES= \

    -e LOG_LEVEL=<0|1|2|3> \

    -e ENABLE_HEALTHCHECK= \

    -e HEALTHCHECK_COMMAND= \

    -e HEALTHCHECK_ACTION= \

    -e HEALTHCHECK_HOSTNAME= \

    -e UMASK= \

    -e PUID= \

    -e PGID= \

    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

| Variable | Values | Default | Description |

| -------- | ------ | ------- | ----------- |

| `DOCKER_HOST` | string | _(empty)_ | Docker socket proxy address (e.g. `tcp://dockersocket:2375`). Use as a secure alternative to mounting `/var/run/docker.sock`. Leave empty to use direct socket mount. |

| `MONITOR_INTERVAL` | integer | `60` | Time in seconds between checking for unhealthy containers |

| `RETRY_COUNT` | integer | `3` | Number of times to verify unhealthy status before taking action |

| `RETRY_DELAY` | integer | `10` | Time in seconds to wait between retry health checks |

| `ACTION` | restart\|stop\|pause\|unpause\|kill\|none | `restart` | Docker action to execute on unhealthy containers, set to 'none' to perform no action |

| `CONTAINER_LABEL` | string | _(empty)_ | Filter containers by label (e.g. `com.example.monitor=true`) |

| `CONTAINER_ENV_VAR` | string | _(empty)_ | Filter containers by environment variable (e.g. `MONITOR_ENABLED=true`) |

| `CONTAINER_NAME` | string | _(empty)_ | Filter containers by name, comma-separated (e.g. `sonarr,radarr,plex`) |

| `APPRISE_NOTIFICATION_SERVICES` | string | _(empty)_ | Comma-separated list of Apprise service URLs for notifications (e.g. `mailto://user:pass@gmail.com,discord://webhook_id/webhook_token`) |

| `LOG_LEVEL` | 0\|1\|2\|3 | `1` | Logging level: `0`=DEBUG, `1`=INFO, `2`=WARN, `3`=ERROR |

| `ENABLE_HEALTHCHECK` | yes\|no | `no` | Enable or disable healthchecks (for this container) |

| `HEALTHCHECK_COMMAND` | string | `healthcheck.sh` | Healthcheck command or script to execute |

| `HEALTHCHECK_ACTION` | string | `exit 1` | Action on healthcheck failure, e.g. `exit 1` or `kill 1` |

| `HEALTHCHECK_HOSTNAME` | string | `cloudflare.com` | Hostname for healthcheck DNS/HTTPS tests |

| `PUID` | integer | `99` | User ID for the running container |

| `PGID` | integer | `100` | Group ID for the running container |

| `UMASK` | integer | `000` | UMASK for created files |

**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

```bash

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

```bash

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

```bash

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

```bash

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:

```bash

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:

```bash

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:-

```bash

id 

```

___

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

[![PayPal donation](https://www.paypal.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=MM5E27UX6AUU4)

[Documentation](https://github.com/binhex/documentation) | [Support forum](https://forums.unraid.net/topic/196150-support-binhex-healarr/)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/binhex/arch-healarr

Awesome Lists containing this project

README