Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

FlagDefaultDescription
--docker-host <HOST>DOCKER_HOSTDocker 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 setDocker 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 ~/.dockerDirectory 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-verifyDOCKER_TLS_VERIFYUse 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 ~/.dockerDirectory 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 directoryThe 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 directoryThe 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 directoryThe 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’s ca.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-cert and --docker-tls-key, or else the directory’s cert.pem and key.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:// or https:// host, or a bare host: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:

  1. --docker-context <NAME> on the command line, if given.
  2. Otherwise, a host — --docker-host, then DOCKER_HOST — if either is set. No context is consulted at all.
  3. Otherwise a context, if one resolves: DOCKER_CONTEXT, then the active context.
  4. 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, a cert.pem/key.pem pair, or sets SkipTLSVerify. Otherwise it connects without TLS.
  • A stored ca.pem is the only certificate authority the daemon’s certificate is checked against. Without one, the system trust store is used.
  • A stored cert.pem/key.pem pair 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 match cert.pem, is an error naming the context and the file.
  • Only a tcp:// or https:// 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

VariableEffect
DOCKER_HOSTDocker 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_CONTEXTDocker CLI context to connect through — the default for --docker-context. Ignored when a host is set. Empty counts as unset.
DOCKER_CONFIGDirectory 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_PATHDirectory 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_VERIFY1, 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.

  1. Create a root CA. This is the one certificate you’ll trust from now on — keep ca-key.pem private; 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"
    
  2. 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")
    
  3. Configure dockerd to require TLS with this certificate (/etc/docker/daemon.json or the equivalent dockerd flags — see the Docker documentation linked above), using ca.pem/server-cert.pem/server-key.pem from steps 1–2.

  4. 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.pem
    

    ratect-compat takes the same three options, before the task name. Or set --docker-cert-path to a directory containing ca.pem (and cert.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 a ca.pem was 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.