{"id":24077495,"url":"https://github.com/tmknight/docker-autoheal","last_synced_at":"2025-04-30T08:11:18.141Z","repository":{"id":217677439,"uuid":"739800529","full_name":"tmknight/docker-autoheal","owner":"tmknight","description":"Monitor and remediate unhealthy Docker containers","archived":false,"fork":false,"pushed_at":"2025-03-18T14:16:02.000Z","size":531,"stargazers_count":31,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-30T14:11:51.979Z","etag":null,"topics":["automation","docker","management"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tmknight.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-06T15:31:16.000Z","updated_at":"2025-03-28T08:40:52.000Z","dependencies_parsed_at":"2024-04-10T12:48:17.725Z","dependency_job_id":"796f794a-0746-45a8-addb-0ecfcc44a04b","html_url":"https://github.com/tmknight/docker-autoheal","commit_stats":null,"previous_names":["tmknight/docker-autoheal"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmknight%2Fdocker-autoheal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmknight%2Fdocker-autoheal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmknight%2Fdocker-autoheal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmknight%2Fdocker-autoheal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmknight","download_url":"https://codeload.github.com/tmknight/docker-autoheal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251666283,"owners_count":21624293,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","docker","management"],"created_at":"2025-01-09T20:16:41.589Z","updated_at":"2025-04-30T08:11:18.135Z","avatar_url":"https://github.com/tmknight.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker-Autoheal\n\n[![GitHubRelease][GitHubReleaseBadge]][GitHubReleaseLink]\n[![DockerPublishing][DockerPublishingBadge]][DockerLink]\n[![DockerSize][DockerSizeBadge]][DockerLink]\n[![DockerPulls][DockerPullsBadge]][DockerLink]\n\u003c!-- [![GitHubAssetDl][GitHubAssetDlBadge]][GitHubAssetDlLink] --\u003e\n\nA cross-platform tool to monitor and remediate unhealthy Docker containers\n\nWritten in Rust and designed to be OS agnostic, flexible, and performant in large environments via concurrency and multi-threading\n\nThe `docker-autoheal` binary may be executed in a native OS or from a Docker container\n\n## How to Use\n\n### You must first apply `HEALTHCHECK` to your docker images\n\n- See \u003chttps://docs.docker.com/engine/reference/builder/#healthcheck\u003e for details\n\n### Environment Variables\n\n| Variable                     | Default                  | Description                                           |\n|:----------------------------:|:------------------------:|:-----------------------------------------------------:|\n| **AUTOHEAL_CONNECTION_TYPE** | local                    | This determines how `docker-autoheal` connects to Docker (One of: local, socket, http, ssl                           |\n| **AUTOHEAL_STOP_TIMEOUT**    | 10                       | Docker waits `n` seconds for a container to stop before killing it during restarts (override via label; see below)  |\n| **AUTOHEAL_INTERVAL**        | 5                        | Check container health every `n` seconds              |\n| **AUTOHEAL_START_DELAY**     | 0                        | Wait `n` seconds before first health check            |\n| **AUTOHEAL_POST_ACTION**     |                          | The absolute path of an executable to be run after restart attempts; container `name`, `id` and `stop-timeout` are passed as arguments in that order                                                              |\n| **AUTOHEAL_MONITOR_ALL**     | FALSE                    | Set to `TRUE` to simply monitor all containers on the host or leave as `FALSE` and control via `autoheal.monitor.enable` |\n| **AUTOHEAL_LOG_ALL**         | FALSE                    | Allow (`TRUE`/`FALSE`) logging (and webhook/apprise if set) for containers with `autostart.restart.enable=FALSE`          |\n| **AUTOHEAL_LOG_PERSIST**     | FALSE                    | Allow (`TRUE`/`FALSE`) external persistent logging and reporting of historical data   |\n| **AUTOHEAL_TCP_HOST**        | localhost                | Address of Docker host                                |\n| **AUTOHEAL_TCP_PORT**        | 2375 (ssl: 2376)         | Port on which to connect to the Docker host           |\n| **AUTOHEAL_TCP_TIMEOUT**     | 10                       | Time in `n` seconds before failing connection attempt |\n| **AUTOHEAL_PEM_PATH**        | /opt/docker-autoheal/tls | Absolute path to requisite ssl certificate files (key.pem, cert.pem, ca.pem) when `AUTOHEAL_CONNECTION_TYPE=ssl`         |\n| **AUTOHEAL_APPRISE_URL**     |                          | URL to post messages to the apprise following actions on unhealthy container                                             |\n| **AUTOHEAL_WEBHOOK_KEY**     |                          | KEY to post messages to the webhook following actions on unhealthy container                                             |\n| **AUTOHEAL_WEBHOOK_URL**     |                          | URL to post messages to the webhook following actions on unhealthy container                                             |\n\n### Optional Container Labels\n\n| Label                        | Default | Description                                                                                                                                 |\n|:----------------------------:|:-------:|:-------------------------------------------------------------------------------------------------------------------------------------------:|\n| **autoheal.stop.timeout**    |         | Per container override (in seconds) of `AUTOHEAL_STOP_TIMEOUT` during restart (e.g. Some container routinely takes longer to cleanly exit)  |\n| **autoheal.monitor.enable**  | FALSE   | Per container override (true/false) to control if should be monitored (e.g. If you have a large number of containers that you wish to monitor and restart, apply this label as `FALSE` to the few that you do not wish to monitor and set `AUTOHEAL_MONITOR_ALL` to `TRUE`)                                                                                  |\n| **autoheal.restart.enable**  | TRUE    | Per container override (true/false) to control if should restart on unhealthy (e.g. If you have a large number of containers that you wish to monitor and restart, apply this label as `FALSE` to the few that you do not wish to restart and set `AUTOHEAL_MONITOR_ALL` to `TRUE`)                                                                       |\n\n### Binary Options\n\nUsed when executed in native OS (NOTE: The environment variables are also accepted)\n\n```bash\nOptions:\n    -a, --apprise-url \u003cAPPRISE_URL\u003e\n                        The apprise url\n    -c, --connection-type \u003cCONNECTION_TYPE\u003e\n                        One of local, socket, http, or ssl\n    -d, --start-delay \u003cSTART_DELAY\u003e\n                        Time in seconds to wait for first check\n    -h, --help          Print help\n    -i, --interval \u003cINTERVAL\u003e\n                        Time in seconds to check health\n    -j, --webhook-key \u003cWEBHOOK_KEY\u003e\n                        The webhook json key string\n    -k, --key-path \u003cKEY_PATH\u003e\n                        The absolute path to requisite ssl PEM files\n    -l, --log-all       Enable logging of unhealthy containers where restart\n                        is disabled (WARNING, this could be chatty)\n    -m, --monitor-all   Enable monitoring off all containers that have a\n                        healthcheck\n    -n, --tcp-host \u003cTCP_HOST\u003e\n                        The hostname or IP address of the Docker host (when -c\n                        http or ssl)\n    -p, --tcp-port \u003cTCP_PORT\u003e\n                        The tcp port number of the Docker host (when -c http\n                        or ssl)\n    -s, --stop-timeout \u003cSTOP_TIMEOUT\u003e\n                        Time in seconds to wait for action to complete\n    -t, --tcp-timeout \u003cTCP_TIMEOUT\u003e\n                        Time in seconds to wait for connection to complete\n    -w, --webhook-url \u003cWEBHOOK_URL\u003e\n                        The webhook url\n    -L, --log-persist Enable external persistent logging and reporting of historical\n                        data\n    -P, --post-action \u003cSCRIPT_PATH\u003e\n                        The absolute path to a script that should be executed\n                        after container restart\n    -V, --version       Print version information\n```\n\n### Local\n\n```bash\n/usr/local/bin/docker-autoheal --monitor-all --log_persist \u003e /var/log/docker-autoheal.log \u0026\n```\n\nWill connect to the local Docker host, monitor all containers, and generate a persistent log at `/opt/docker-autoheal/log.json`\n\n### Socket\n\n```bash\ndocker run -d --read-only \\\n    --user=[uid]:[gid]\n    --name docker-autoheal \\\n    --network=none \\\n    --restart=always \\\n    --env=\"AUTOHEAL_CONNECTION_TYPE=socket\" \\\n    --env=\"AUTOHEAL_MONITOR_ALL=true\" \\\n    --env=\"AUTOHEAL_LOG_PERSIST=true\" \\\n    --volume=/var/run/docker.sock:/var/run/docker.sock:ro \\\n    --volume=/opt/docker-autoheal/log.json:/opt/docker-autoheal/log.json:rw \\\n    tmknight88/docker-autoheal:latest\n```\n\nWill connect to the Docker host via unix socket location /var/run/docker.sock or Windows named pipe location //./pipe/docker_engine, monitor all containers, and write persistent log data to `/opt/docker-autoheal/log.json` as the user with the specified `uid:gid`\n\n### HTTP\n\n```bash\ndocker run -d --read-only \\\n    --user=[uid]:[gid]\n    --name docker-autoheal \\\n    --restart=always \\\n    --env=\"AUTOHEAL_CONNECTION_TYPE=http\" \\\n    --env=\"AUTOHEAL_TCP_HOST=MYHOST\" \\\n    --env=\"AUTOHEAL_TCP_PORT=2375\" \\\n    --env=\"AUTOHEAL_LOG_PERSIST=true\" \\\n    --volume=/opt/docker-autoheal/log.json:/opt/docker-autoheal/log.json:rw \\\n    tmknight88/docker-autoheal:latest\n```\n\nWill connect to the Docker host via hostname or IP and the specified port, monitor only containers with a label `autoheal.monitor.enable=true`, and write persistent log data to `/opt/docker-autoheal/log.json` as the user with the specified `uid:gid`\n\n### Logging\n\n```bash\n2024-01-23 03:03:23-0500 [WARNING] [nordvpn] Container (886d37fd9f5c) is unhealthy with 3 failures\n2024-01-23 03:03:23-0500 [WARNING] [nordvpn] Container (886d37fd9f5c) last output: [4] Status: Unstable\n2024-01-23 03:03:23-0500 [WARNING] [nordvpn] Restarting container (886d37fd9f5c) with 10s timeout\n2024-01-23 03:03:34-0500 [   INFO] [nordvpn] Restart of container (886d37fd9f5c) was successful\n2024-01-23 03:03:34-0500 [   INFO] [nordvpn] Container (886d37fd9f5c) has been unhealthy 1 time\n2024-01-23 03:04:48-0500 [WARNING] [privoxy] Container (74f74eb7b2d0) is unhealthy with 3 failures\n2024-01-23 03:04:48-0500 [WARNING] [privoxy] Container (74f74eb7b2d0) last output: [-1] Health check exceeded timeout (3s)\n2024-01-23 03:04:48-0500 [WARNING] [privoxy] Restarting container (74f74eb7b2d0) with 10s timeout\n2024-01-23 03:04:59-0500 [   INFO] [privoxy] Restart of container (74f74eb7b2d0) was successful\n2024-01-23 03:04:59-0500 [   INFO] [privoxy] Container (74f74eb7b2d0) has been unhealthy 1 time\n```\n\nExample output when docker-autoheal is in action\n\n### Persistent Logging\n\nExamples of working with log.json:\n\n```bash\njq -s 'group_by(.name) | map({name: .[0].name, data: (group_by(.id) | map({id: .[0].id, data: .}))})' /opt/docker-autoheal/log.json\n```\n\nGroup all entries by name and then group by container id\n\n```bash\njq -s 'map(select(.name==\"privoxy\"))' /opt/docker-autoheal/log.json\n```\n\nFind all occurrences of 'privoxy'\n\n```bash\njq -s 'map(select(.name==\"privoxy\")) | group_by(.name) | map({name: .[0].name, data: (group_by(.id) | map({id: .[0].id, data: .}))})' /opt/docker-autoheal/log.json\n```\n\nFind all occurrences of 'privoxy' and group by container id\n\n## Other Info\n\n### Docker Labels\n\na) Apply the label `autoheal.monitor.enable=true` to your container to have it watched\n\nOR\n\nb) Set ENV `AUTOHEAL_MONITOR_ALL=true` (or apply `--monitor-all` to the binary) to watch all running containers\n\n### SSL Connection Type\n\nSee \u003chttps://docs.docker.com/engine/security/https/\u003e for how to configure TCP with mTLS\n\nThe certificates and keys need these names:\n\n- ca.pem\n- cert.pem\n- key.pem\n\n### Docker Security\n\nAdditional security can be obtained by:\n\n- Use a unique user for monitoring and remediating\n  - Create a new user\n  - Add that user to the `docker` group\n  - Execute the binary or docker container with that uid:gid\n- Run docker in [rootless mode](https://docs.docker.com/engine/security/rootless/)\n\n### Docker Timezone\n\nIf you need the `docker-autoheal` container timezone to match the local machine, you can map `/etc/localtime`\n\n```bash\ndocker run ... -v /etc/localtime:/etc/localtime:ro\n```\n\n### Webhook/Apprise\n\n- The payload includes the following separated by `|`: Docker system hostname, the last health output, and the result of restart action\n\n### A Word of Caution about Excluding from Restart and Logging of those Exclusions\n\n- Excluding a container from restarts and enabling logging for excluded containers will generate numerous log messages whenever that container becomes unhealthy\n- Additionally, if a webhook or apprise is also configured, they will be executed at each monitoring interval for those containers\n\n## Credits\n\n- [willfarrell](https://github.com/willfarrell)\n\n\u003c!-- [GitHubReleaseBadge]: https://img.shields.io/github/actions/workflow/status/tmknight/docker-autoheal/github-release.yml?branch=main\u0026style=flat\u0026logo=github\u0026color=32c855\u0026label=generate%20release\u0026cacheSeconds=9000\n--\u003e\n[GitHubReleaseBadge]: https://img.shields.io/github/actions/workflow/status/tmknight/docker-autoheal/github-release.yml?branch=main\u0026style=flat\u0026logo=github\u0026label=generate%20release\u0026cacheSeconds=9000\n[GitHubReleaseLink]: https://github.com/tmknight/docker-autoheal/releases\n\u003c!-- [DockerPublishingBadge]: https://img.shields.io/github/actions/workflow/status/tmknight/docker-autoheal/docker-publish.yml?branch=main\u0026style=flat\u0026logo=github\u0026color=32c855\u0026label=publish%20image\u0026cacheSeconds=9000\n--\u003e\n[DockerPublishingBadge]: https://img.shields.io/github/actions/workflow/status/tmknight/docker-autoheal/docker-publish.yml?branch=main\u0026style=flat\u0026logo=github\u0026label=publish%20image\u0026cacheSeconds=9000\n[DockerPullsBadge]: https://img.shields.io/docker/pulls/tmknight88/docker-autoheal?style=flat\u0026logo=docker\u0026color=blue\u0026cacheSeconds=9000\n[DockerSizeBadge]: https://img.shields.io/docker/image-size/tmknight88/docker-autoheal?sort=date\u0026arch=amd64\u0026style=flat\u0026logo=docker\u0026color=blue\u0026cacheSeconds=9000\n[DockerLink]: https://hub.docker.com/r/tmknight88/docker-autoheal\n\u003c!-- [GithubAssetDlBadge]: https://img.shields.io/github/downloads/tmknight/docker-autoheal/total?style=flat\u0026logo=github\u0026color=32c855\u0026label=release%20downloads\u0026cacheSeconds=7200\n[GithubAssetDlLink]: https://github.com/tmknight/docker-autoheal/releases --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmknight%2Fdocker-autoheal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmknight%2Fdocker-autoheal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmknight%2Fdocker-autoheal/lists"}