Connecting to Docker
Every command that reaches a Docker daemon takes the same set of connection
options, on both binaries: ratect run, ratect caches, ratect resources
and ratect doctor each accept them (ratect tasks list, ratect includes
and ratect config never connect, so they don’t), and ratect-compat accepts
them on every invocation and uses them whenever the invocation actually
connects (a --list-tasks run never does) — though it checks a Docker config
or certificate directory given by an option or DOCKER_CONFIG/DOCKER_CERT_PATH,
and a file given to a TLS option, on every one. On both binaries, --docker-context beside --docker-host or a
TLS option is refused whether or not the command connects — ratect caches
with the directory store, or a ratect-compat --list-tasks, included — and
ratect doctor reports it as a problem. This
page is the one description
of those options; the ratect and
ratect-compat CLI references only
link here.
With none of them given, Ratect connects to DOCKER_HOST if it is set,
otherwise through a Docker context if one resolves (DOCKER_CONTEXT, then the
active context), otherwise to Docker’s own platform default, the Unix socket
unix:///var/run/docker.sock — see Which daemon is used.
Options
| Flag | Default | Description |
|---|---|---|
--docker-host <HOST> | DOCKER_HOST | Docker host to connect to, e.g. unix:///var/run/docker.sock or tcp://1.2.3.4:5678. An https:// host connects over TLS as if --docker-tls-verify were given. Cannot be combined with --docker-context. |
--docker-context <NAME> | DOCKER_CONTEXT, then the active context, unless a host is set | Docker CLI context to connect through — read from the Docker CLI’s own context store (~/.docker/contexts/, or --docker-config’s directory). The active context is ~/.docker/config.json’s currentContext. Cannot be combined with --docker-host or any of the TLS options below. Errors clearly if the named context doesn’t exist in the store. |
--docker-config <PATH> | DOCKER_CONFIG, then ~/.docker | Directory containing the Docker CLI’s own configuration files (context store, config.json). A directory given here or by DOCKER_CONFIG must exist and be a directory; ~/.docker needn’t exist. |
--docker-tls | — | Use TLS when connecting to the Docker host. Behaves identically to --docker-tls-verify — the daemon’s certificate is always fully verified; there is no way to skip verification. |
--docker-tls-verify | DOCKER_TLS_VERIFY | Use TLS when connecting to the Docker host, verifying its certificate. Needs a host: --docker-host or DOCKER_HOST. |
--docker-cert-path <PATH> | DOCKER_CERT_PATH, then --docker-config/DOCKER_CONFIG, then ~/.docker | Directory containing any of ca.pem/cert.pem/key.pem to authenticate to the Docker host and verify it, unless overridden individually by the three options below. A directory given here or by DOCKER_CERT_PATH must exist and be a directory, whether or not TLS is used. None of the three files has to be there — see TLS through the options. |
--docker-tls-ca-cert <PATH> | ca.pem in the certificate directory | The TLS CA certificate used to verify the Docker host’s own certificate — the only certificate authority it is checked against. The file must exist. Without this option and without a ca.pem, the system trust store is used. |
--docker-tls-cert <PATH> | cert.pem in the certificate directory | The TLS certificate used to authenticate to the Docker host. The file must exist, and so must the key. |
--docker-tls-key <PATH> | key.pem in the certificate directory | The TLS key used to authenticate to the Docker host. The file must exist, and so must the certificate. |
A path given to --docker-config, --docker-cert-path, --docker-tls-ca-cert,
--docker-tls-cert or --docker-tls-key, or by DOCKER_CONFIG or DOCKER_CERT_PATH,
has a leading ~ expanded to your home directory, and . and .. removed, before it
is used, as in Batect. The Docker CLI takes the two variables as written. Your home
directory, here and for ~/.docker, is $HOME when it is set and absolute, else
your passwd entry’s: the Docker CLI’s rule, so Ratect reads the ~/.docker that
docker login writes to. The Docker CLI also takes a relative $HOME; Ratect
doesn’t. With no home from either, as under a numeric docker run -u with HOME
unset, there is no ~/.docker: Ratect connects with no stored credentials, and
refuses a named context or TLS that would read its certificates from there
unless --docker-config or DOCKER_CONFIG names a directory instead.
TLS through the options
With --docker-tls or --docker-tls-verify (or DOCKER_TLS_VERIFY), or an
https:// host, the certificate directory is --docker-cert-path, then DOCKER_CERT_PATH, then
the Docker config directory if one was given (--docker-config, then
DOCKER_CONFIG), then ~/.docker (an empty DOCKER_CERT_PATH counts as
unset). A directory given by any of those four sources must exist, and every
command that connects checks it first; ~/.docker must exist unless all
three files are named by their own options. What it holds
decides how the connection is made:
--docker-tls-ca-cert, or else the directory’sca.pem, is the only certificate authority the daemon’s certificate is checked against. With neither, the system trust store is used — for a daemon whose certificate a public certificate authority signed.--docker-tls-certand--docker-tls-key, or else the directory’scert.pemandkey.pem, are presented as the client certificate. With neither option and neither file, none is presented. Only one of the two files in the directory is an error, and so is giving one option when the directory doesn’t hold the other file.- A file named by an option must exist and not be a directory, whether or not
TLS is used: every command that takes the option checks it before it runs.
It needn’t be a regular file — a pipe, such as
<(cat key.pem), is read like one, once. - An encrypted key, or one that doesn’t match the certificate, is an error naming the option or the directory, and the file.
- Only a
tcp://orhttps://host, or a barehost:port, can be connected to over TLS.
If the daemon’s certificate fails verification and no certificate authority
was given, the error says where a ca.pem was looked for. A daemon with a
self-signed or privately signed certificate needs one — see
TLS with a private certificate authority.
A Docker context follows the same file rules with the files it stores — see below.
Which daemon is used
A flag always wins over its environment variable. Between the two ways of naming a daemon, the order is:
--docker-context <NAME>on the command line, if given.- Otherwise, a host —
--docker-host, thenDOCKER_HOST— if either is set. No context is consulted at all. - Otherwise a context, if one resolves:
DOCKER_CONTEXT, then the active context. - Otherwise Docker’s own platform default.
This is the Docker CLI’s own order. A context named default — from any of the
three sources — means “no context”, as in the Docker CLI: Ratect connects to
DOCKER_HOST if it is set, otherwise to the platform default. An
empty DOCKER_HOST or DOCKER_CONTEXT counts as unset, also as in the Docker
CLI.
The active context is the currentContext in the Docker config directory’s
config.json, read only when step 3 gets that far. A config.json that can’t
be read, or isn’t valid JSON, has none to give: Ratect warns, naming the file,
and goes on to step 4, as the current Docker CLI does.
A connection through a context uses the endpoint that context stores; the TLS
options only apply to a host connection. Naming one alongside
--docker-context is an error; when step 3 picks the context instead, the TLS
options are ignored, as in Batect.
A context brings its own TLS settings instead — the ones docker context create
stored for it — used as the Docker CLI uses them:
- The context connects over TLS if it stores a
ca.pem, acert.pem/key.pempair, or setsSkipTLSVerify. Otherwise it connects without TLS. - A stored
ca.pemis the only certificate authority the daemon’s certificate is checked against. Without one, the system trust store is used. - A stored
cert.pem/key.pempair is presented as the client certificate. Without one, none is. Storing only one of the two is an error. - An encrypted
key.pem, or one that doesn’t matchcert.pem, is an error naming the context and the file. - Only a
tcp://orhttps://host can be connected to over TLS.
A context naming an https:// host also connects over TLS, storing TLS material
or not — the same as --docker-host https://…, and unlike the Docker CLI, which
connects to such a host without TLS unless the context stores some.
SkipTLSVerify is not honoured: the daemon’s certificate is always fully verified,
as with --docker-tls. If verification fails for a context that sets it, the error
says so — see TLS with a private certificate authority
for making the certificate verifiable instead.
What is checked on connecting
Before asking the daemon for anything else, Ratect checks three things, and stops with an error if any fails:
- That it answers. When no connection can be made at all — nothing
listening, a host name that doesn’t resolve, no route to it — the error says
the daemon couldn’t be reached, names the host tried and what chose it
(
--docker-host,DOCKER_HOST, a context, or the platform default), and suggests checking that Docker is running and that the host or context is the right one. The underlying reason follows as its cause. - That it is Docker 20.10 or newer (API 1.41) — see Installation for why.
- That it runs Linux containers. A daemon in Windows containers mode is refused, naming the operating system it reports: switch Docker to Linux containers to use Ratect.
Environment variables
| Variable | Effect |
|---|---|
DOCKER_HOST | Docker host to connect to — the default for --docker-host. Setting it means no context is used unless --docker-context is given. Empty counts as unset. |
DOCKER_CONTEXT | Docker CLI context to connect through — the default for --docker-context. Ignored when a host is set. Empty counts as unset. |
DOCKER_CONFIG | Directory containing the Docker CLI’s own configuration files — the default for --docker-config, and for --docker-cert-path when DOCKER_CERT_PATH is unset. Must exist and be a directory when set and not empty. A leading ~ is your home directory, as for the option. |
DOCKER_CERT_PATH | Directory containing any of ca.pem/cert.pem/key.pem for TLS — the default for --docker-cert-path. Empty counts as unset; otherwise it must exist and be a directory. A leading ~ is your home directory, as for the option. |
DOCKER_TLS_VERIFY | 1, yes or true enables TLS, fully verified, and 0, no or false leaves it off, in any case — the default for --docker-tls-verify. Empty counts as unset. Any other value is an error when connecting to a host, unless --docker-tls or --docker-tls-verify is given; a command that doesn’t connect, or connects through a context, never reads it — though ratect doctor reports one as a problem whichever way it connects. |
TLS with a private certificate authority
--docker-tls/--docker-tls-verify always fully verify the Docker daemon’s
certificate — there is no flag or environment variable that skips verification, unlike
Batect’s own bare --docker-tls (which sets Go’s tls.Config.InsecureSkipVerify,
disabling chain-of-trust, expiry, and hostname checks all at once, not just the
hostname check). This isn’t just inherited from a missing feature: rustls, the
library Ratect’s TLS support is built on, takes the same position deliberately —
there’s no boolean toggle for skipping verification in rustls either, only a
dangerous() accessor that requires implementing the ServerCertVerifier trait from
scratch to bypass it. Ratect doesn’t reach for that. If you reach for --docker-tls
(skip-verify) because your daemon’s certificate is self-signed —
including for local development or CI — the fix isn’t to skip verification, it’s to
make the certificate verifiable: run your own certificate authority, and trust that,
rather than trusting nothing.
The daemon side of this (configuring dockerd to require TLS, generating its
server certificate) is standard Docker documentation, not Ratect-specific — see
Protect the Docker daemon socket.
What follows is the client side: a self-contained, worked example of generating a
private root CA, signing a server certificate for the daemon with it, and pointing
Ratect at the result.
-
Create a root CA. This is the one certificate you’ll trust from now on — keep
ca-key.pemprivate; it’s the only thing standing between “verified” and “not”.openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \ -keyout ca-key.pem -out ca.pem -subj "/CN=my-docker-ca" -
Generate and sign the daemon’s own certificate, naming every hostname/IP clients will actually connect through as a Subject Alternative Name (SAN) — verification checks this, not the certificate’s
CN:openssl req -newkey rsa:4096 -sha256 -nodes \ -keyout server-key.pem -out server-req.pem -subj "/CN=docker-daemon" openssl x509 -req -in server-req.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial \ -out server-cert.pem -days 3650 -sha256 \ -extfile <(printf "subjectAltName=DNS:docker-daemon.example.com,IP:203.0.113.10") -
Configure
dockerdto require TLS with this certificate (/etc/docker/daemon.jsonor the equivalentdockerdflags — see the Docker documentation linked above), usingca.pem/server-cert.pem/server-key.pemfrom steps 1–2. -
Point Ratect at the CA (client certificate/key are only needed if the daemon itself also requires client auth — generate a second cert signed by the same CA for that, following step 2’s pattern):
ratect run test \ --docker-host tcp://docker-daemon.example.com:2376 \ --docker-tls-verify \ --docker-tls-ca-cert ./ca.pemratect-compattakes the same three options, before the task name. Or set--docker-cert-pathto a directory containingca.pem(andcert.pem/key.pem, if the daemon requires client auth) instead of naming each file individually — see Options. Leave the CA out altogether and the daemon is checked against the system trust store, which a private CA is not in: verification fails, and the error says where aca.pemwas looked for. A Docker context created with the same files (docker context create my-daemon --docker "host=tcp://docker-daemon.example.com:2376,ca=./ca.pem") works too, through--docker-context my-daemon— see Which daemon is used.
If verification fails, the error names the problem (expired, wrong host, untrusted issuer) rather than silently connecting anyway — that’s the entire point of not supporting skip-verify. Regenerate whichever certificate is actually at fault, rather than reaching for a flag Ratect doesn’t have.