{"id":21976807,"url":"https://github.com/stuartapp/dockercheck","last_synced_at":"2026-04-19T14:32:21.089Z","repository":{"id":86222113,"uuid":"218246021","full_name":"StuartApp/dockercheck","owner":"StuartApp","description":"Expose a group of containers health via HTTP. Bonus track: Prometheus metrics","archived":false,"fork":false,"pushed_at":"2024-02-28T09:07:26.000Z","size":134,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":51,"default_branch":"master","last_synced_at":"2025-03-23T00:22:44.093Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/StuartApp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-29T09:07:45.000Z","updated_at":"2024-02-26T15:02:51.000Z","dependencies_parsed_at":"2025-01-28T03:39:19.904Z","dependency_job_id":null,"html_url":"https://github.com/StuartApp/dockercheck","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/StuartApp/dockercheck","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StuartApp%2Fdockercheck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StuartApp%2Fdockercheck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StuartApp%2Fdockercheck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StuartApp%2Fdockercheck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StuartApp","download_url":"https://codeload.github.com/StuartApp/dockercheck/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StuartApp%2Fdockercheck/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262963654,"owners_count":23391868,"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":[],"created_at":"2024-11-29T16:12:21.585Z","updated_at":"2026-04-19T14:32:16.025Z","avatar_url":"https://github.com/StuartApp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dockercheck - check and expose containers health\n\ndockrcheck is an HTTP server that serves a `/health` endpoint for the targetgroup. It also exposes a Prometheus client with the statuses of the containers.\n\n`dockercheck` inspects all the running containers on the system, looking for containers labelled with `com.docker.compose.project` (default value, can be adjusted via an environment variable).\nIt will check disk usage and the health of the containers and then return the proper HTTP status on the `/health` endpoint.\n\n## Prometheus client\n\nAt the same time, `dockercheck` exposes a Prometheus clients with the statuses of all the containers matching the label. It exports a single metric (controlled by `DOCKERCHECK_PROM_METRIC`) with two labels attached:\n\n* container `name`\n* container `role`\n\n on the `/metrics` path. The metrics get updated everytime the `/health` endpoint is accessed (sorry, no dedicated updating thread atm `¯\\_(ツ)_/¯`).\n\n## Configuration parameters\n\nThe program is customizable via environment variables\n\n|ENV VAR |Default value |Meaning|\n|-|-|-|\n|DOCKERCHECK_HTTP_PORT|8080|Port used for the healthcheck status|\n|DOCKERCHECK_LABEL|\"com.docker.compose.project\"|Label used to filter containers. It can be just a label name or label=value|\n|DOCKERCHECK_PROM_METRIC|\"container_status\"|The name of the metric exposed by the Prometheus client|\n|DISK_USAGE_THRESHOLD|90|The threshold for the disk usage|\n\n## Makefile\n\nThe Makefile included in this repository provides several targets to automate common tasks related to setting up and running the `dockercheck` application.\n\n### Targets\n\n- **venv**: Creates a virtual environment, installs dependencies listed in `requirements.txt`.\n- **run-and-start-containers**: Starts Docker containers using `docker-compose up -d` and then runs the `dockercheck` application.\n- **test-health**: Hits the `/health` endpoint of the running application using `curl`.\n- **stop-containers**: Stops Docker containers using `docker-compose down`.\n- **clean**: Deletes the virtual environment.\n\n### Example Usage\n\nTo set up the environment and run the `dockercheck` application, you can use the following commands:\n\n```bash\nmake run-and-start-containers\n```\nFor testing the health of the application:\n```bash\nmake test-health\n```\n\n## Health calculation logic\n\n![Diagram showing the health calculation logic](dockercheck.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstuartapp%2Fdockercheck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstuartapp%2Fdockercheck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstuartapp%2Fdockercheck/lists"}