feat: add Docker API TLS client-certificate support

[JamBalaya56562]

What

Add support for connecting to a TLS-protected Docker daemon over tcp:// using client-certificate authentication.

This revives and completes #673, which has been open since 2020, addressing the maintainer's requested changes.

Why

When the Docker daemon is only reachable over a tcp:// endpoint secured with --tlsverify, docker_api previously always used plain http://, so every API call failed. acme-companion could not be used against a remote/secured Docker host.

How

Mirrors the Docker CLI and docker-gen convention so a single certificate directory can be shared across containers:

• DOCKER_TLS_VERIFY — set to true (or True/TRUE/1) to enable TLS client auth.
• DOCKER_CERT_PATH — in-container directory containing ca.pem, cert.pem, key.pem.

Changes:

• app/functions.sh — docker_api gains a mutually-exclusive TLS branch (after the unix-socket branch) that appends --cert/--key/--cacert and switches the scheme to https://. It is gated by the existing parse_true helper, so only true/True/TRUE/1 enable it (addresses the review request to not accept any non-empty value).
• app/entrypoint.sh — check_docker_socket now validates, when TLS is enabled, that DOCKER_CERT_PATH is set and the three certificate files are readable, failing fast with an actionable error (with a -v mount example) instead of a silent curl failure.
• docs/Container-configuration.md — documents the variables and emphasises that DOCKER_CERT_PATH is an in-container path that must be volume-mounted.
• test/tests/docker_api_tls/ — new test that stubs curl and asserts the exact invocation docker_api builds for each transport (TLS GET/POST, TLS disabled, unix socket), verifying both the cert flags and the parse_true gating. It needs no external TLS daemon, so it is deterministic on CI runners. Registered in test/config.sh and added to the CI matrix (.github/workflows/test.yml).

Maintainer requests from #673 addressed

1. ✅ DOCKER_TLS_VERIFY validated via the project's true/True/TRUE/1 convention (parse_true).
2. ✅ Docs clarify the path is in-container and requires a volume mount.
3. ✅ Tests added (resolves status/pr-needs-tests).

Testing

• docker_api_tls passes under both 2containers and 3containers (the test is transport-focused and produces identical output regardless of the setup).
• Negative control (corrupted expected output) correctly fails — comparison is effective.
• Existing docker_api test passes under both setups (no regression).
• shellcheck clean on all modified scripts.

Closes #754

Supersedes #673 (revives that proposal with the maintainer's requested changes).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds support for connecting acme-companion to a remote TLS-protected Docker daemon over tcp:// using Docker-style client certificates (DOCKER_TLS_VERIFY + DOCKER_CERT_PATH). This extends the existing docker_api transport handling (unix-socket vs TCP) and documents/tests the new behavior so users can run without mounting the Docker socket.

Changes:

• Add a TLS branch to docker_api that switches to https:// and passes --cert/--key/--cacert when DOCKER_TLS_VERIFY is true.
• Fail fast at startup when TLS is enabled but required cert files are missing/unreadable.
• Add docs + a new test suite (and CI registration) to validate the curl invocation and optionally perform a real TLS handshake via a socat sidecar.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
app/functions.sh	Adds TLS client-certificate support to docker_api for TCP Docker hosts.
app/entrypoint.sh	Validates DOCKER_CERT_PATH and required PEM files when TLS is enabled.
docs/Container-configuration.md	Documents DOCKER_HOST, DOCKER_TLS_VERIFY, and DOCKER_CERT_PATH usage and mounting expectations.
test/tests/docker_api_tls/run.sh	New test verifying docker_api curl arguments and optional end-to-end TLS handshake.
test/tests/docker_api_tls/expected-std-out.txt	Expected output for the deterministic curl-stub portion of the new test.
test/config.sh	Registers the new docker_api_tls test in the global test list.
.github/workflows/test.yml	Adds docker_api_tls to the CI test matrix.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[buchdag]

@JamBalaya56562 looks like there is an issue with the test 🤔

[JamBalaya56562]

Thanks for the heads-up! Two things were going on:

• The docker_api_tls/run.sh test script had lost its executable bit, so the harness skipped the test and failed the job. I work on the branch locally with Sapling on Windows, where the exec bit gets silently dropped on rebase — I've restored it (100755) and double-checked the other scripts.
• I also rebased onto main to resolve the merge conflict introduced once feat: IPv6 support for standalone challenge config #1267 was merged.

Both should be sorted now. 🙏