{"id":33239987,"url":"https://github.com/tarampampam/microcheck","last_synced_at":"2026-06-22T09:32:28.787Z","repository":{"id":323700542,"uuid":"1092766842","full_name":"tarampampam/microcheck","owner":"tarampampam","description":"🧪 Lightweight health check utilities for Docker containers","archived":false,"fork":false,"pushed_at":"2026-05-08T09:33:51.000Z","size":161,"stargazers_count":141,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-05-08T11:34:42.799Z","etag":null,"topics":["checkhttp","checkhttps","checkport","cli","docker","docker-image","healthcheck","precompiled-binaries","static-binary","tools"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tarampampam.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-09T09:14:07.000Z","updated_at":"2026-05-08T09:33:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tarampampam/microcheck","commit_stats":null,"previous_names":["tarampampam/microcheck"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/tarampampam/microcheck","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarampampam%2Fmicrocheck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarampampam%2Fmicrocheck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarampampam%2Fmicrocheck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarampampam%2Fmicrocheck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarampampam","download_url":"https://codeload.github.com/tarampampam/microcheck/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarampampam%2Fmicrocheck/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34643614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["checkhttp","checkhttps","checkport","cli","docker","docker-image","healthcheck","precompiled-binaries","static-binary","tools"],"created_at":"2025-11-16T20:00:27.512Z","updated_at":"2026-06-22T09:32:28.780Z","avatar_url":"https://github.com/tarampampam.png","language":"C","funding_links":[],"categories":["In-Container Tooling"],"sub_categories":["Wrappers"],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/tarampampam/microcheck#readme\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://socialify.git.ci/tarampampam/microcheck/image?description=1\u0026font=Raleway\u0026forks=1\u0026issues=1\u0026logo=https%3A%2F%2Fupload.wikimedia.org%2Fwikipedia%2Fcommons%2Fa%2Fa7%2FDocker-svgrepo-com.svg\u0026owner=1\u0026pulls=1\u0026pattern=Solid\u0026stargazers=1\u0026theme=Dark\"\u003e\n      \u003cimg align=\"center\" src=\"https://socialify.git.ci/tarampampam/microcheck/image?description=1\u0026font=Raleway\u0026forks=1\u0026issues=1\u0026logo=https%3A%2F%2Fupload.wikimedia.org%2Fwikipedia%2Fcommons%2Fa%2Fa7%2FDocker-svgrepo-com.svg\u0026owner=1\u0026pulls=1\u0026pattern=Solid\u0026stargazers=1\u0026theme=Light\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# Lightweight health check utilities for Docker containers\n\nMinimal, statically linked tools designed for [container health checks][docker-healthcheck]. Built with musl for\nminimal size and zero dependencies.\n\nA common use case is to include these tools in `HEALTHCHECK` instructions in Dockerfiles, allowing Docker to\nmonitor the health of applications running inside containers. Typically, you\n[don't need them in Kubernetes][k8s-probes] (because Kubernetes has its own health check mechanisms, where the\nkubelet periodically checks the container's status), but in vanilla Docker or other container runtimes without\nbuilt-in health checks, these tools can be very useful.\n\nYou might say, \"But why? There are already tools like `curl` or `wget`!\". That's true, but those tools are often\nquite large because they include many features and dependencies. Using them only for health checks can\nunnecessarily increase the size of your Docker images. These tools are designed to be as small as possible\nwhile still providing the required functionality, especially for `scratch` or `distroless` images (`curl` and\n`wget` **won't work there** at all, since they rely on shared libraries). In addition, their exit codes are\ndesigned to match Docker's expectations for health checks (0 = healthy, 1 = unhealthy), whereas `curl` and\n`wget` do not follow this convention.\n\nJust to illustrate the size difference, here is a comparison of adding `httpcheck` versus `curl` or `wget`:\n\n```\nCOPY --from=... /bin/httpcheck  [▌--------------------------------------] 75Kb\napk add wget                    [███████████████████--------------------] 3.3Mb // 44× larger\napt install wget                [█████████████████████------------------] 4Mb   // 53× larger\napk add curl                    [██████████████████████████-------------] 5.2Mb // 69× larger\napt install curl                [███████████████████████████████████████] 9.3Mb // 124× larger\n```\n\nSo, think of this as an alternative to:\n\n```diff\n-# install curl for health checks (+~10MB)\n-RUN apt update \u0026\u0026 apt install -y curl \u0026\u0026 rm -r /var/lib/apt/lists/*\n-\n-HEALTHCHECK --interval=5m --timeout=3s CMD curl -f http://localhost:8080/ || exit 1\n+# add httpcheck binary (+~75KB)\n+COPY --from=ghcr.io/tarampampam/microcheck:1 /bin/httpcheck /bin/httpcheck\n+\n+HEALTHCHECK --interval=5m --timeout=3s CMD [\"httpcheck\", \"http://localhost:8080/\"]\n```\n\n\u003e [!NOTE]\n\u003e By the way - the first approach also creates a shell process (adding unnecessary overhead) and depends on the\n\u003e shell being present in the container, which may not be the case in minimal images.\n\n[docker-healthcheck]: https://docs.docker.com/reference/dockerfile/#healthcheck\n[k8s-probes]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/\n\n## 🔥 Features\n\n* **Statically linked**: Works in minimal containers (e.g., `scratch`, `distroless`)\n* **Pretty fast**: Written in pure `C`, compiled with `musl`\n* **Multi-arch and cross-compiled** (x86_64, ARM, etc.), even for macOS you may find precompiled binaries in\n  the releases\n* **Distributed** as single binaries (see the releases page) and Docker image\n* **Minimal size**: Optimized for small Docker images\n* **TLS support**: Uses `mbedTLS` for HTTPS (accepts self-signed certificates and does NOT verify SSL/TLS certificates)\n* **Protocol auto-detection** (`httpscheck` only): Automatically tries HTTPS first, falls back to HTTP on TLS errors\n* **Flexible configuration**: Command-line flags and environment variables\n* **Docker-friendly**: Handles signals (`SIGTERM`, `SIGINT`) gracefully\n\n## 🧩 Tools\n\n| Tool         |  Size  | Use case                                  |\n|--------------|:------:|-------------------------------------------|\n| `httpcheck`  | ~75KB  | Check HTTP (only) endpoints               |\n| `httpscheck` | ~500KB | Check HTTP and HTTPS endpoints            |\n| `portcheck`  | ~70KB  | Check TCP/UDP ports                       |\n| `parallel`   | ~50KB  | Run multiple commands in parallel         |\n| `pidcheck`   | ~40KB  | Check if process from PID file is running |\n\n\u003e [!WARNING]\n\u003e **Value priority: CLI flag \u003e environment variable \u003e default**. This applies to all `--*-env` flags across\n\u003e all tools. Passing both `--*-env` and its corresponding flag is a common mistake - the explicit flag always\n\u003e wins and the env variable is never read.\n\u003e\n\u003e ```dockerfile\n\u003e # WRONG: HTTP_PORT=9000 is ignored - portcheck always checks 8080\n\u003e HEALTHCHECK CMD [\"/bin/portcheck\", \"--port-env\", \"HTTP_PORT\", \"--port\", \"8080\"]\n\u003e\n\u003e # CORRECT: set the default via ENV and let --port-env read it at runtime\n\u003e ENV HTTP_PORT=8080\n\u003e HEALTHCHECK CMD [\"/bin/portcheck\", \"--port-env\", \"HTTP_PORT\"]\n\u003e ```\n\n### `httpcheck` \u0026 `httpscheck`\n\nThose tools perform HTTP health checks. `httpscheck` includes TLS support, while `httpcheck` does not to reduce\nthe binary file size. Both tools share the same command-line interface, and even compile from the same source\ncode (but with different build flags).\n\n\u003e [!NOTE]\n\u003e `httpscheck` supports **protocol auto-detection**: when no protocol (`http://` or `https://`) is specified in the URL,\n\u003e it will first attempt an HTTPS connection. If the HTTPS connection fails (TLS handshake error), it will automatically\n\u003e fall back to HTTP. This is useful for applications that may have TLS enabled or disabled based on configuration.\n\n```\nOptions:\n  -h, --help                Show this help message\n  -m, --method              HTTP method to use (default: \"GET\") [$CHECK_METHOD]\n      --method-env          Change env variable name for --method\n  -u, --user-agent          User-Agent header value (default: \"healthcheck/0.0.0 (httpcheck)\") [$CHECK_USER_AGENT]\n      --user-agent-env      Change env variable name for --user-agent\n  -t, --timeout             Request timeout in seconds (default: \"5\") [$CHECK_TIMEOUT]\n      --timeout-env         Change env variable name for --timeout\n      --connect-timeout     TCP connect timeout in seconds (float, e.g. 0.5) (default: \"0.25\") [$CHECK_CONNECT_TIMEOUT]\n      --connect-timeout-env Change env variable name for --connect-timeout\n  -H, --header              Add custom HTTP header (can be used multiple times)\n      --basic-auth          Basic auth credentials (username:password) [$CHECK_BASIC_AUTH]\n      --basic-auth-env      Change env variable name for --basic-auth\n      --host                Override hostname from URL [$CHECK_HOST]\n      --host-env            Change env variable name for --host\n  -p, --port                Override port from URL [$CHECK_PORT]\n      --port-env            Change env variable name for --port\n```\n\n**URL Format Examples:**\n\n```shell\n# Explicit HTTP\nhttpcheck http://localhost:8080/health\n\n# Explicit HTTPS\nhttpscheck https://localhost:8080/health\n\n# Auto-detect (httpscheck only): tries HTTPS first, falls back to HTTP on TLS error\nhttpscheck localhost:8080/health\n```\n\n### `portcheck`\n\nThis tool checks if a TCP or UDP port is open on a given host (usually `127.0.0.1`). For TCP, it attempts to\nestablish a connection, while for UDP... Since UDP is connectionless - very frequently it may not be possible to\ndetermine if the port is open or closed.\n\n\u003e [!IMPORTANT]\n\u003e Most UDP servers respond only to valid protocol requests. This tool sends nearly empty UDP datagram,\n\u003e which may not receive a response from many services. Use UDP checks only when you are certain the target\n\u003e will respond appropriately.\n\n\u003e [!NOTE]\n\u003e You need to specify the target host and port explicitly via flags or environment variables. Don't try to pass\n\u003e them as positional arguments like `portcheck --port 80 example.com`, as this tool does not accept them that way.\n\u003e Use `--host` and `--port` options instead - `portcheck --port 80 --host example.com`.\n\n```\nOptions:\n  -h, --help        Show this help message\n      --tcp         Use TCP protocol (default)\n      --udp         Use UDP protocol\n      --host        Target hostname or IPv4 address (default: \"127.0.0.1\") [$CHECK_HOST]\n      --host-env    Change env variable name for --host\n  -p, --port        Target port number (required) [$CHECK_PORT]\n      --port-env    Change env variable name for --port\n  -t, --timeout     Check timeout in seconds (default: \"5\") [$CHECK_TIMEOUT]\n      --timeout-env Change env variable name for --timeout\n```\n\nExamples:\n\n```shell\n# Check TCP port 80 on localhost\nportcheck --port 80\n\n# Check UDP port 53 on example.com\nportcheck --udp --port 53 --host example.com\n```\n\n### `parallel`\n\nThis tool executes multiple commands in parallel and is designed specifically for Docker health checks where you\nneed to verify multiple conditions simultaneously. It returns exit code 0 only if all commands succeed, or the\nexit code of the first failed command otherwise.\n\nThe main use case is combining multiple health checks (HTTP endpoints, TCP ports, etc.) into a single\n`HEALTHCHECK` instruction. When any command fails, `parallel` immediately terminates all other running commands\nand returns the failure code, ensuring fast failure detection.\n\n```\nOptions:\n  -h, --help  Show this help message\n  -j, --jobs  Limit number of parallel jobs (has no effect, kept for backward compatibility\n```\n\nExamples:\n\n```shell\n# Check both HTTP endpoint AND port using parallel\nparallel \"httpcheck http://127.0.0.1:8080\" \"portcheck --port 8080\"\n\n# Check multiple HTTP endpoints\nparallel \"httpcheck http://127.0.0.1:8080/health\" \"httpcheck http://127.0.0.1:8080/status\"\n```\n\n#### Argument Parsing\n\nCommands can be specified as:\n\n- Unquoted words for simple commands: `parallel whoami id`\n- Quoted strings for commands with arguments: `parallel \"echo hello\" \"echo world\"`\n- Mixed quoted/unquoted parts that concatenate: `parallel cmd'arg1 arg2'\"arg3\"` (produces\n  a single argument: `cmdarg1 arg2arg3`)\n\nInside quoted strings:\n\n- Single quotes preserve everything literally (no escaping)\n- Double quotes allow backslash escaping\n- Spaces and tabs separate arguments\n- Adjacent quoted/unquoted parts concatenate into single argument\n\n### `pidcheck`\n\nThis tool checks whether a process specified in a PID file or directly by PID is currently running. It reads the PID\nfrom a file or a command line argument and verifies that the process exists using the `kill(pid, 0)` system call.\n\n\u003e [!NOTE]\n\u003e The zero signal (`kill(pid, 0)`) does not actually send a signal but performs error checking to determine whether\n\u003e the process exists and whether the current user has permission to send signals to it.\n\nIt may be useful for monitoring daemon processes inside containers that do not open any kind of network ports, but\nwrite their PID to a file.\n\n```\nOptions:\n  -h, --help     Show this help message\n  -f, --file     Path to PID file [$CHECK_PIDFILE]\n      --file-env Change env variable name for --file\n  -p, --pid      Process ID to check [$CHECK_PID]\n      --pid-env  Change env variable name for --pid\n```\n\n\u003e [!NOTE]\n\u003e The `--file` and `--pid` options are mutually exclusive and cannot be used together.\n\nHere is an example of how to create and write a PID file in your Go app:\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"strconv\"\n)\n\nfunc main() {\n\tpidFile := \"/var/run/myapp.pid\"\n\n\t// write the PID to the specified file\n\tif err := os.WriteFile(pidFile, []byte(strconv.Itoa(os.Getpid())), 0o644); err != nil {\n\t\tpanic(fmt.Errorf(\"failed to write PID file: %w\", err))\n\t}\n\n\tdefer func() { _ = os.Remove(pidFile) }() // remove PID file on exit\n\n\t// ... the rest of your app\n}\n```\n\nAnd then use `pidcheck` in your Dockerfile:\n\n```Dockerfile\nHEALTHCHECK --interval=5s CMD [\"pidcheck\", \"--file\", \"/var/run/myapp.pid\"]\n```\n\n#### PID File Format\n\nThe PID file should contain a single process ID number. Leading and trailing whitespace is automatically\nstripped. Any non-numeric content will result in an error.\n\n### Environment Variable Overrides\n\nMost options can be overridden via environment variables. This is useful in Docker containers, where you may\nwant to configure health checks without modifying the command line. For example:\n\n```shell\n# Use a custom method via environment variable\nCHECK_METHOD=HEAD httpcheck http://127.0.0.1\n\n# If the application already uses the APP_PORT variable, you can map it to override the port used by httpcheck\nAPP_PORT=8080 httpcheck --port-env=APP_PORT http://127.0.0.1\n```\n\n## 🐋 Docker image\n\n| Registry                           | Image                            |\n|------------------------------------|----------------------------------|\n| [GitHub Container Registry][ghcr]  | `ghcr.io/tarampampam/microcheck` |\n| [Red Hat Container Registry][quay] | `quay.io/tarampampam/microcheck` |\n| [Docker Hub][docker-hub]           | `tarampampam/microcheck`         |\n\n[docker-hub]:https://hub.docker.com/r/tarampampam/microcheck\n[ghcr]:https://github.com/users/tarampampam/packages/container/package/microcheck\n[quay]:https://quay.io/repository/tarampampam/microcheck\n\n\u003e [!IMPORTANT]\n\u003e Using the `latest` tag for the Docker image is highly discouraged due to potential backward-incompatible changes\n\u003e during **major** upgrades. Please use tags in the `X.Y.Z`, `X.Y`, or at least `X` format.\n\nThe following platforms for this image are available:\n\n```shell\n$ docker run --rm mplatform/mquery ghcr.io/tarampampam/microcheck:1\nImage: ghcr.io/tarampampam/microcheck:1\n * Manifest List: Yes (Image type: application/vnd.oci.image.index.v1+json)\n * Supported platforms:\n   - linux/386\n   - linux/amd64\n   - linux/arm/v6\n   - linux/arm/v7\n   - linux/arm64\n   - linux/ppc64le\n   - linux/s390x\n```\n\n## ⚙ Pre-compiled binaries\n\nPre-compiled static binaries are available on the [releases page][releases-page]. Download the appropriate binary\nfor your architecture and operating system.\n\n[releases-page]: https://github.com/tarampampam/microcheck/releases\n\n## 🔌 Usage examples\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🚀 Healthcheck for HTTP server\u003c/strong\u003e\u003c/summary\u003e\n\n```Dockerfile\n# use empty filesystem\nFROM scratch\n\n# import some executable application\nCOPY --from=docker.io/containous/whoami:v1.5.0 /whoami /whoami\n\n# import httpcheck from current repository image (exactly 'httpcheck' due\n# to we don't need TLS here)\nCOPY --from=ghcr.io/tarampampam/microcheck:1 /bin/httpcheck /bin/httpcheck\n\n# docs: \u003chttps://docs.docker.com/reference/dockerfile#healthcheck\u003e\nHEALTHCHECK --interval=5s --retries=2 CMD [\"httpcheck\", \"http://127.0.0.1:8080/health\"]\n\nENTRYPOINT [\"/whoami\", \"-port\", \"8080\"]\n```\n\nLet's build it and run:\n\n```shell\n$ docker build -t http-check:local - \u003c ./examples/http-check.Dockerfile\n$ docker run --rm -d --name http-check http-check:local\n$ docker ps --filter 'name=http-check' --format '{{.Status}}'\nUp 6 seconds (healthy)\n$ docker kill http-check\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🚀 Multiple health checks with parallel\u003c/strong\u003e\u003c/summary\u003e\n\nThis example shows how to use `parallel` to check multiple conditions simultaneously. The container is\nconsidered healthy only if all checks pass:\n\n```Dockerfile\nFROM scratch\n\n# import some executable application\nCOPY --from=docker.io/containous/whoami:v1.5.0 /whoami /whoami\n\n# import httpcheck, portcheck and parallel from microcheck image\nCOPY --from=ghcr.io/tarampampam/microcheck:1 /bin/httpcheck /bin/portcheck /bin/parallel /bin/\n\n# check both HTTP endpoint AND port using parallel (the port usually will differ from the HTTP port)\nHEALTHCHECK --interval=5s --retries=2 CMD [\"parallel\", \\\n    \"httpcheck http://127.0.0.1:8080\", \\\n    \"portcheck --port 8080\" \\\n]\n\nENTRYPOINT [\"/whoami\", \"-port\", \"8080\"]\n```\n\nLet's build it and run:\n\n```shell\n$ docker build -t parallel:local - \u003c ./examples/parallel.Dockerfile\n$ docker run --rm -d --name parallel parallel:local\n$ docker ps --filter 'name=parallel' --format '{{.Status}}'\nUp 6 seconds (healthy)\n$ docker kill parallel\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🚀 Healthcheck with protocol auto-detection\u003c/strong\u003e\u003c/summary\u003e\n\nThis example demonstrates the protocol auto-detection feature of `httpscheck`, which is useful when your application\nmay have TLS enabled or disabled based on configuration:\n\n```Dockerfile\n# use empty filesystem\nFROM scratch\n\n# import your application (example assumes it can run with or without TLS)\nCOPY --from=your-app:latest /app /app\n\n# import httpscheck to enable auto-detection\nCOPY --from=ghcr.io/tarampampam/microcheck:1 /bin/httpscheck /bin/httpscheck\n\n# healthcheck will try HTTPS first, fall back to HTTP if TLS is not available\n# note: no http:// or https:// prefix in the URL\nHEALTHCHECK --interval=5s --retries=2 CMD [\"httpscheck\", \"127.0.0.1:8080/health\"]\n\nENTRYPOINT [\"/app\"]\n```\n\n**How it works:**\n\n1. When no protocol is specified (`127.0.0.1:8080/health` instead of `https://...`), `httpscheck`\n   first attempts an HTTPS connection\n2. If the HTTPS handshake fails (TLS error), it automatically falls back to HTTP\n3. This happens silently without any output, making it transparent for health checks\n4. The fallback only occurs on connection/TLS errors, not on HTTP status codes (`4xx`, `5xx`)\n\nThis is particularly useful for:\n- Applications with optional TLS configuration\n- Development vs production environments\n- Gradual TLS rollouts\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🚀 Healthcheck for TCP server\u003c/strong\u003e\u003c/summary\u003e\n\nThe same as previous, but using `portcheck`:\n\n```Dockerfile\n# use empty filesystem\nFROM scratch\n\n# import some executable application\nCOPY --from=docker.io/containous/whoami:v1.5.0 /whoami /whoami\n\n# import portcheck because we need only TCP port check here\nCOPY --from=ghcr.io/tarampampam/microcheck:1 /bin/portcheck /bin/portcheck\n\n# docs: \u003chttps://docs.docker.com/reference/dockerfile#healthcheck\u003e\nHEALTHCHECK --interval=5s --retries=2 CMD [\"portcheck\", \"--port\", \"8080\"]\n\nENTRYPOINT [\"/whoami\", \"-port\", \"8080\"]\n```\n\nLet's build it and run:\n\n```shell\n$ docker build -t tcp-check:local - \u003c ./examples/tcp-check.Dockerfile\n$ docker run --rm -d --name tcp-check tcp-check:local\n$ docker ps --filter 'name=tcp-check' --format '{{.Status}}'\nUp 7 seconds (healthy)\n$ docker kill tcp-check\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🚀 Healthcheck for daemon process using pidcheck\u003c/strong\u003e\u003c/summary\u003e\n\nThis example demonstrates how to use `pidcheck` to monitor a daemon process inside a Docker container.\n\n\u003e [!NOTE]\n\u003e Since `nginx` exposes TCP port and even HTTP endpoint, we use here `pidcheck` just for demonstration purposes (better\n\u003e to use `portcheck` or `httpcheck` in real-world scenarios).\n\n```Dockerfile\nFROM docker.io/library/nginx:1.25-alpine\n\n# import pidcheck from microcheck image\nCOPY --from=ghcr.io/tarampampam/microcheck:1 /bin/pidcheck /bin/pidcheck\n\n# nginx writes its PID to /var/run/nginx.pid by default\nHEALTHCHECK --interval=5s --retries=2 CMD [\"pidcheck\", \"--file\", \"/var/run/nginx.pid\"]\n```\n\nLet's build it and run:\n\n```shell\n$ docker build -t pidcheck:local - \u003c ./examples/pidcheck.Dockerfile\n$ docker run --rm -d --name pidcheck pidcheck:local\n$ docker ps --filter 'name=pidcheck' --format '{{.Status}}'\nUp 8 seconds (healthy)\n$ docker kill pidcheck\n```\n\n\u003c/details\u003e\n\n## 🎁 Bonus level - adding healthcheck to popular images\n\nSince you're here, you might find it useful to know how to healthcheck some popular Docker images (you don't need\ntools from this repository for that, but it might be interesting anyway):\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🧪 PostgreSQL\u003c/strong\u003e\u003c/summary\u003e\n\n\u003e PostgreSQL, often simply \"Postgres\", is an object-relational database management system (ORDBMS) with an emphasis\n\u003e on extensibility and standards-compliance.\n\n```yaml\n# compose.yml\n\nservices:\n  postgresql:\n    image: docker.io/library/postgres:18-alpine\n    environment:\n      POSTGRES_DB: some_dbname # POSTGRES_DATABASE in older versions\n      POSTGRES_USER: some_user\n      POSTGRES_PASSWORD: some_password\n    ports: ['5432/tcp']\n    healthcheck:\n      test: ['CMD', 'pg_isready', '-U', 'some_user', '-d', 'some_dbname']\n      interval: 10s\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🧪 Temporal\u003c/strong\u003e\u003c/summary\u003e\n\n\u003e Temporal is a scalable and reliable runtime for durable function executions.\n\n```yaml\n# compose.yml\n\nservices:\n  temporal:\n    image: docker.io/temporalio/auto-setup:1.28.1\n    environment:\n      BIND_ON_IP: 0.0.0.0\n    ports: ['7233/tcp']\n    healthcheck:\n      test: ['CMD', 'tctl', '--address', '127.0.0.1:7233', 'workflow', 'list']\n      interval: 10s\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🧪 Jaeger\u003c/strong\u003e\u003c/summary\u003e\n\n\u003e Jaeger is an open-source, distributed tracing platform used to monitor and troubleshoot complex\n\u003e microservices architectures.\n\n```yaml\n# compose.yml\n\nservices:\n  jaeger:\n    image: docker.io/jaegertracing/all-in-one:1.60\n    ports: ['6831/udp', '16686/tcp', '4318/tcp']\n    healthcheck:\n      test: ['CMD', 'wget', '--spider', '-q', 'http://127.0.0.1:14269/healthz']\n      interval: 10s\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🧪 Minio\u003c/strong\u003e\u003c/summary\u003e\n\n\u003e MinIO is a high-performance, Kubernetes-native object storage system that is compatible with the Amazon S3 API.\n\n```yaml\n# compose.yml\n\nservices:\n  minio:\n    image: quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z\n    command: server /data --json --console-address ':9090'\n    ports: ['9000/tcp', '9090/tcp']\n    healthcheck:\n      test: ['CMD', 'curl', '-f', 'http://127.0.0.1:9000/minio/health/live']\n      interval: 10s\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🧪 MySQL\u003c/strong\u003e\u003c/summary\u003e\n\n\u003e MySQL is an open-source relational database management system (RDBMS).\n\n```yaml\n# compose.yml\n\nservices:\n  mysql:\n    image: docker.io/library/mysql:9\n    environment:\n      MYSQL_RANDOM_ROOT_PASSWORD: 'true'\n      MYSQL_DATABASE: some_dbname\n      MYSQL_USER: some_user\n      MYSQL_PASSWORD: some_password\n    ports: ['3306/tcp', '3306/tcp'] # use port 32601 for local development\n    healthcheck:\n      test: ['CMD', 'mysql', '-h', '127.0.0.1', '--user=some_user', '--password=some_password', '--execute', 'SELECT 1']\n      interval: 10s\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🧪 Redis\u003c/strong\u003e\u003c/summary\u003e\n\n\u003e Redis is an open-source, in-memory data structure store used as a database, cache, and message broker.\n\n```yaml\n# compose.yml\n\nservices:\n  redis:\n    image: docker.io/library/redis:8-alpine\n    ports: ['6379/tcp']\n    healthcheck:\n      test: ['CMD', 'redis-cli', 'ping']\n      interval: 10s\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🧪 Adminer (phpMinAdmin)\u003c/strong\u003e\u003c/summary\u003e\n\n\u003e Adminer (formerly phpMinAdmin) is a full-featured database management tool written in PHP.\n\n```yaml\n# compose.yml\n\nservices:\n  adminer:\n    image: docker.io/library/adminer:5\n    ports: ['8080/tcp']\n    healthcheck:\n      test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/\"]\n      interval: 10s\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🧪 Caddy\u003c/strong\u003e\u003c/summary\u003e\n\n\u003e Caddy 2 is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go.\n\n```yaml\n# compose.yml\n\nservices:\n  caddy:\n    image: docker.io/library/caddy:2-alpine\n    ports: ['80/tcp', '443/tcp']\n    healthcheck:\n      test: ['CMD', 'wget', '--spider', '-q', 'http://127.0.0.1:80/']\n      interval: 10s\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e🧪 Cassandra\u003c/strong\u003e\u003c/summary\u003e\n\n\u003e Apache Cassandra is an open source distributed database management system designed to handle large amounts of\n\u003e data across many commodity servers, providing high availability with no single point of failure.\n\n```yaml\n# compose.yml\n\nservices:\n  cassandra:\n    image: docker.io/library/cassandra:5\n    ports: ['9042/tcp']\n    healthcheck:\n      test: ['CMD', 'cqlsh', '-e', 'DESCRIBE KEYSPACES', '127.0.0.1', '9042']\n      interval: 10s\n      start_period: 60s # \u003c-- important\n```\n\n\u003c/details\u003e\n\n\u003e [!TIP]\n\u003e Feel free to contribute more examples via pull requests!\n\n## 🏗 Building from sources\n\nTo build the tools from sources, ensure you have the following dependencies installed:\n\n* `musl-gcc`\n* `cmake`\n* `wget`\n* `patch`\n* Standard build tools (`make`, `tar`)\n* Optionally - `clang-format`\n\n\u003e On Debian: `sudo apt install musl-tools cmake wget patch clang-format make tar`\n\nAfter cloning the repository, build the tools using the `Makefile` - execute `make`.\n\nFor testing, you need `python3` and `openssl` installed. Run tests with `make test`.\n\n## 🧠 A note on AI-assisted development\n\nAI tools are great assistants - they can autocomplete, review, summarize, and help you move faster. But they're not a\nsubstitute for understanding what's going on. If you're using AI to contribute here, please make sure you actually\nread, understand, and stand behind the changes you're proposing.\n\nI personally write my code myself, and I encourage others to do the same. Not because AI is \"bad\", but because blindly\ntrusting generated code tends to produce... let's say creative results.\n\nAnd honestly, I'm still waiting for the day \"AI-free software\" becomes a trend - like organic food, but for code 😄\nUntil then: trust, but verify.\n\n## 🤖 AI Agent Instructions\n\nSee [AGENTS.md](AGENTS.md) for detailed guidelines for AI agents working with this repository.\n\n## 👾 Support\n\n[![Issues][badge-issues]][issues]\n[![Issues][badge-prs]][prs]\n\nIf you encounter any bugs in the project, please [create an issue][new-issue] in this repository.\n\n[badge-issues]:https://img.shields.io/github/issues/tarampampam/microcheck.svg?maxAge=45\n[badge-prs]:https://img.shields.io/github/issues-pr/tarampampam/microcheck.svg?maxAge=45\n[issues]:https://github.com/tarampampam/microcheck/issues\n[prs]:https://github.com/tarampampam/microcheck/pulls\n[new-issue]:https://github.com/tarampampam/microcheck/issues/new/choose\n\n## 📖 License\n\nThis is open-sourced software licensed under the [MIT License][license].\n\n[license]:https://github.com/tarampampam/microcheck/blob/master/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarampampam%2Fmicrocheck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarampampam%2Fmicrocheck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarampampam%2Fmicrocheck/lists"}