Microcheck
🧪 Lightweight health check utilities for Docker containers
Install / Use
/learn @tarampampam/MicrocheckREADME
Lightweight health check utilities for Docker containers
Minimal, statically linked tools designed for container health checks. Built with musl for minimal size and zero dependencies.
A common use case is to include these tools in HEALTHCHECK instructions in Dockerfiles, allowing Docker to
monitor the health of applications running inside containers. Typically, you
don't need them in Kubernetes (because Kubernetes has its own health check mechanisms, where the
kubelet periodically checks the container's status), but in vanilla Docker or other container runtimes without
built-in health checks, these tools can be very useful.
You might say, "But why? There are already tools like curl or wget!". That's true, but those tools are often
quite large because they include many features and dependencies. Using them only for health checks can
unnecessarily increase the size of your Docker images. These tools are designed to be as small as possible
while still providing the required functionality, especially for scratch or distroless images (curl and
wget won't work there at all, since they rely on shared libraries). In addition, their exit codes are
designed to match Docker's expectations for health checks (0 = healthy, 1 = unhealthy), whereas curl and
wget do not follow this convention.
Just to illustrate the size difference, here is a comparison of adding httpcheck versus curl or wget:
COPY --from=... /bin/httpcheck [▌--------------------------------------] 75Kb
apk add wget [███████████████████--------------------] 3.3Mb // 44× larger
apt install wget [█████████████████████------------------] 4Mb // 53× larger
apk add curl [██████████████████████████-------------] 5.2Mb // 69× larger
apt install curl [███████████████████████████████████████] 9.3Mb // 124× larger
So, think of this as an alternative to:
-# install curl for health checks (+~10MB)
-RUN apt update && apt install -y curl && rm -r /var/lib/apt/lists/*
-
-HEALTHCHECK --interval=5m --timeout=3s CMD curl -f http://localhost:8080/ || exit 1
+# add httpcheck binary (+~75KB)
+COPY --from=ghcr.io/tarampampam/microcheck:1 /bin/httpcheck /bin/httpcheck
+
+HEALTHCHECK --interval=5m --timeout=3s CMD ["httpcheck", "http://localhost:8080/"]
[!NOTE] By the way - the first approach also creates a shell process (adding unnecessary overhead) and depends on the shell being present in the container, which may not be the case in minimal images.
🔥 Features
- Statically linked: Works in minimal containers (e.g.,
scratch,distroless) - Pretty fast: Written in pure
C, compiled withmusl - Multi-arch and cross-compiled (x86_64, ARM, etc.), even for macOS you may find precompiled binaries in the releases
- Distributed as single binaries (see the releases page) and Docker image
- Minimal size: Optimized for small Docker images
- TLS support: Uses
mbedTLSfor HTTPS (accepts self-signed certificates and does NOT verify SSL/TLS certificates) - Protocol auto-detection (
httpscheckonly): Automatically tries HTTPS first, falls back to HTTP on TLS errors - Flexible configuration: Command-line flags and environment variables
- Docker-friendly: Handles signals (
SIGTERM,SIGINT) gracefully
🧩 Tools
| Tool | Size | Use case |
|--------------|:------:|-------------------------------------------|
| httpcheck | ~75KB | Check HTTP (only) endpoints |
| httpscheck | ~500KB | Check HTTP and HTTPS endpoints |
| portcheck | ~70KB | Check TCP/UDP ports |
| parallel | ~50KB | Run multiple commands in parallel |
| pidcheck | ~40KB | Check if process from PID file is running |
httpcheck & httpscheck
Those tools perform HTTP health checks. httpscheck includes TLS support, while httpcheck does not to reduce
the binary file size. Both tools share the same command-line interface, and even compile from the same source
code (but with different build flags).
[!NOTE]
httpschecksupports protocol auto-detection: when no protocol (http://orhttps://) is specified in the URL, it will first attempt an HTTPS connection. If the HTTPS connection fails (TLS handshake error), it will automatically fall back to HTTP. This is useful for applications that may have TLS enabled or disabled based on configuration.
Options:
-h, --help Show this help message
-m, --method HTTP method to use (default: "GET") [$CHECK_METHOD]
--method-env Change env variable name for --method
-u, --user-agent User-Agent header value (default: "healthcheck/0.0.0 (httpscheck)") [$CHECK_USER_AGENT]
--user-agent-env Change env variable name for --user-agent
-t, --timeout Request timeout in seconds (default: "5") [$CHECK_TIMEOUT]
--timeout-env Change env variable name for --timeout
-H, --header Add custom HTTP header (can be used multiple times)
--basic-auth Basic auth credentials (username:password) [$CHECK_BASIC_AUTH]
--basic-auth-env Change env variable name for --basic-auth
--host Override hostname from URL [$CHECK_HOST]
--host-env Change env variable name for --host
-p, --port Override port from URL [$CHECK_PORT]
--port-env Change env variable name for --port
URL Format Examples:
# Explicit HTTP
httpcheck http://localhost:8080/health
# Explicit HTTPS
httpscheck https://localhost:8080/health
# Auto-detect (httpscheck only): tries HTTPS first, falls back to HTTP on TLS error
httpscheck localhost:8080/health
portcheck
This tool checks if a TCP or UDP port is open on a given host (usually 127.0.0.1). For TCP, it attempts to
establish a connection, while for UDP... Since UDP is connectionless - very frequently it may not be possible to
determine if the port is open or closed.
[!IMPORTANT] Most UDP servers respond only to valid protocol requests. This tool sends nearly empty UDP datagram, which may not receive a response from many services. Use UDP checks only when you are certain the target will respond appropriately.
[!NOTE] You need to specify the target host and port explicitly via flags or environment variables. Don't try to pass them as positional arguments like
portcheck --port 80 example.com, as this tool does not accept them that way. Use--hostand--portoptions instead -portcheck --port 80 --host example.com.
Options:
-h, --help Show this help message
--tcp Use TCP protocol (default)
--udp Use UDP protocol
--host Target hostname or IPv4 address (default: "127.0.0.1") [$CHECK_HOST]
--host-env Change env variable name for --host
-p, --port Target port number (required) [$CHECK_PORT]
--port-env Change env variable name for --port
-t, --timeout Check timeout in seconds (default: "5") [$CHECK_TIMEOUT]
--timeout-env Change env variable name for --timeout
Examples:
# Check TCP port 80 on localhost
portcheck --port 80
# Check UDP port 53 on example.com
portcheck --udp --port 53 --host example.com
parallel
This tool executes multiple commands in parallel and is designed specifically for Docker health checks where you need to verify multiple conditions simultaneously. It returns exit code 0 only if all commands succeed, or the exit code of the first failed command otherwise.
The main use case is combining multiple health checks (HTTP endpoints, TCP ports, etc.) into a single
HEALTHCHECK instruction. When any command fails, parallel immediately terminates all other running commands
and returns the failure code, ensuring fast failure detection.
Options:
-h, --help Show this help message
-j, --jobs Limit number of parallel jobs (has no effect, kept for backward compatibility
Examples:
# Check both HTTP endpoint AND port using parallel
parallel "httpcheck http://127.0.0.1:8080" "portcheck --port 8080"
# Check multiple HTTP endpoints
parallel "httpcheck http://127.0.0.1:8080/health" "httpcheck http://127.0.0.1:8080/status"
Argument Parsing
Commands can be specified as:
- Unquoted words for simple commands:
parallel whoami id - Quoted strings for commands with arguments:
parallel "echo hello" "echo world" - Mixed quoted/unquoted parts that concatenate:
parallel cmd'arg1 arg2'"arg3"(produces a single argument:cmdarg1 arg2arg3)
Inside quoted strings:
- Single quotes preserve everything literally (no escaping)
- Double quotes allow backslash escaping
- Spaces and tabs separate arguments
- Adjacent quoted/unquoted parts concatenate into single argument
pidcheck
This tool checks whether a process specified in a PID file or directly by PID is currently running. It reads the PID from a file or a command line
