feat: add Docker HEALTHCHECK

.github/workflows/test.yml

@@ -109,6 +109,7 @@ jobs:
             acme_hooks,
             ocsp_must_staple,
             certs_persistence,
+            container_health,
           ]
         setup: [2containers, 3containers]
         pebble-config: [pebble-config.json]

Dockerfile

@@ -44,5 +44,8 @@ RUN /app/install_scripts.sh
 
 WORKDIR /app
 
+HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
+    CMD [ "/bin/bash", "/app/healthcheck.sh" ]
+
 ENTRYPOINT [ "/bin/bash", "/app/entrypoint.sh" ]
 CMD [ "/bin/bash", "/app/start.sh" ]

app/healthcheck.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# Docker healthcheck: the container is healthy while both background services
+# started by start.sh (the certificates service and docker-gen) are alive.
+
+check_pid_file() {
+    local name="${1}" file="${2}" pid
+    # Read a single line and require a numeric PID so a malformed file is unambiguous.
+    read -r pid 2>/dev/null < "${file}"
+    if [[ ! "${pid}" =~ ^[0-9]+$ ]]; then
+        echo "unhealthy: ${name} PID file ${file} is missing or invalid" >&2
+        return 1
+    fi
+    if ! kill -0 "${pid}" 2>/dev/null; then
+        echo "unhealthy: ${name} (PID ${pid}) is not running" >&2
+        return 1
+    fi
+}
+
+rc=0
+check_pid_file letsencrypt_service /var/run/letsencrypt_service.pid || rc=1
+check_pid_file docker-gen /var/run/docker-gen.pid || rc=1
+exit "${rc}"

app/start.sh

@@ -17,11 +17,13 @@ trap 'term_handler' INT QUIT TERM
 
 letsencrypt_service &
 letsencrypt_service_pid=$!
+echo "${letsencrypt_service_pid}" > /var/run/letsencrypt_service.pid
 
 wait_default="5s:20s"
 DOCKER_GEN_WAIT="${DOCKER_GEN_WAIT:-${wait_default}}"
 docker-gen -watch -notify 'signal_le_service' -wait "${DOCKER_GEN_WAIT}" /app/letsencrypt_service_data.tmpl /app/letsencrypt_service_data &
 docker_gen_pid=$!
+echo "${docker_gen_pid}" > /var/run/docker-gen.pid
 
 # wait "indefinitely"
 while [[ -e /proc/${docker_gen_pid} ]]; do

docs/Docker-Compose.md

@@ -129,6 +129,27 @@ volumes:
 
 **Note:** don't forget to replace `/path/to/nginx.tmpl` with the actual path to the [`nginx.tmpl`](https://raw.githubusercontent.com/nginx-proxy/nginx-proxy/main/nginx.tmpl) file you downloaded.
 
+### Health check
+
+The **acme-companion** image ships with a Docker [`HEALTHCHECK`](https://docs.docker.com/reference/dockerfile/#healthcheck) that reports the container as healthy while both of its background services (the certificates service and the bundled docker-gen) are running.
+
+This lets you gate startup on the companion being up, for example with `docker compose up --wait`, or by having another service wait for it:
+
+```yaml
+services:
+  acme-companion:
+    image: nginxproxy/acme-companion
+    # ...
+
+  myapp:
+    image: myapp
+    depends_on:
+      acme-companion:
+        condition: service_healthy
+```
+
+You can override or disable the check per container with the [`healthcheck`](https://docs.docker.com/reference/compose-file/services/#healthcheck) key in your Compose file.
+
 ### Other (external) examples
 
 **Warning:** some of those examples might be outdated and not working properly with version >= `2.0` of this project.

test/config.sh

@@ -25,6 +25,7 @@ globalTests+=(
 	certs_default_renew_deprecated
 	ocsp_must_staple
 	certs_persistence
+	container_health
 )
 
 # The acme_eab test requires Pebble with a specific configuration

test/tests/container_health/run.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# Check that the companion container reports a 'healthy' Docker health status
+# once its background services are running (issue #709).
+
+if [[ -z ${GITHUB_ACTIONS} ]]; then
+  le_container_name="$(basename "${0%/*}")_$(date "+%Y-%m-%d_%H.%M.%S")"
+else
+  le_container_name="$(basename "${0%/*}")"
+fi
+run_le_container "${1:?}" "${le_container_name}"
+
+function cleanup {
+  # Cleanup the files created by this run of the test to avoid foiling following test(s).
+  docker exec "${le_container_name}" cleanup_test_artifacts
+  # Stop the LE container
+  docker stop "${le_container_name}" > /dev/null
+}
+trap cleanup EXIT
+
+# Wait for the container to report a healthy status.
+timeout="$(($(date +%s) + 120))"
+until [[ "$(docker inspect --format '{{.State.Health.Status}}' "${le_container_name}" 2>/dev/null)" == 'healthy' ]]; do
+  if [[ "$(date +%s)" -gt "${timeout}" ]]; then
+    status="$(docker inspect --format '{{.State.Health.Status}}' "${le_container_name}" 2>/dev/null)"
+    echo "Container ${le_container_name} did not become healthy within two minutes (status: ${status})."
+    exit 1
+  fi
+  sleep 1
+done