Support for Docker® containers
Mutagen has support for synchronizing files and forwarding network traffic in and out of Docker® containers. This support extends to all Docker client platforms (Linux®, macOS, Windows, etc.), Docker daemon setups (local, remote, VM, Hyper-V, etc.), and Docker container types (both Linux and Windows containers are supported).
dockercommand to the Docker daemon is secure, and thus Mutagen provides no encryption on top of this transport. For information about securing the Docker daemon, please see the relevant documentation.
Mutagen requires the
docker command to be in the user’s path. Due to its use
-w/--workdir flag with the
docker exec command, Mutagen requires a
Docker client and daemon supporting API 1.35+. You can check the API version
support of your Docker client and daemon by using the
docker version command.
Docker container filesystem endpoints can be specified to the
mutagen sync create command using URLs of the form:
These URLs support Unicode names and paths and neither require nor support URL escape encoding (i.e. just type “ö”, not “%C3%B6”, etc.).
<user> component is optional and tells Mutagen to act as the specified
user inside the container. If unspecified, Mutagen uses the default container
root for Linux containers or
<container> component can specify any type of container identifier
docker cp and
docker exec, e.g. a name or hexidecimal
<path> component must be non-empty (i.e. at least a
/ character) and can
take one of four forms: an absolute path, a home-directory-relative path, a
home-directory-relative path for an alternate user, or a Windows absolute path:
# Example absolute path (/var/www) docker://container/var/www # Example home-directory-relative path (~/project) docker://container/~/project # Example alternate user home-directory-relative path (~otheruser/project) docker://container/~otheruser/project # Example Windows absolute path (C:\path) docker://container/C:\path
Docker containers must be running to create synchronization sessions and to allow synchronization to run.
Docker container network endpoints can be specified to the
mutagen forward create command using URLs of the form:
<container> components of this URL are the same those in the
synchronization URL format described above, while the
component is described in the
forwarding documentation. In the case of
relative Unix domain socket paths, path resolution will be performed relative to
the default working directory for the container.
The Docker client’s behavior is controlled by three environment variables:
Mutagen is aware of these environment variables and will lock them in at session
creation time (as seen by the
mutagen sync create and
mutagen forward create
commands), including locking in absent or empty values. These locked in values
will then be forwarded to any
docker commands executed by Mutagen.
If required, endpoint-specific versions of these variables (prefixed with
MUTAGEN_BETA_ for synchronization sessions and
MUTAGEN_DESTINATION_ for forwarding sessions) can be used to
override their values on a per-endpoint basis. This would be necessary to (e.g.)
create a synchronization session between two Docker containers hosted on
different Docker daemons. In that case, single global values for
environment variables can’t be used (since it would apply to both endpoint
URLs), and endpoint-specific variables such as
MUTAGEN_BETA_DOCKER_TLS_VERIFY would need to be used when invoking
mutagen sync create.
Docker Windows containers are run using Microsoft’s Hyper-V hypervisor, which
unfortunately does not allow
docker cp operations to copy files into running
containers. This means that Mutagen has to stop and restart Windows containers
in order to copy its agent executables. Mutagen will prompt the user if this is
necessary and allow the user to abort or proceed. If the user decides to
proceed, the stop and restart will be automatically performed by Mutagen. This
is only necessary if a compatible agent binary doesn’t already exist in the
container, so it won’t be necessary on subsequent connection operations.
This restriction does not apply to Linux containers.
Mechanism of action
Mutagen’s support for Docker containers is provided by the Docker client
executable on your system. Mutagen uses the
docker cp command to copy agent
binaries into containers and the
docker exec command to run and communicate
with the agent binaries over standard input/output streams.
Docker search path
Mutagen uses the first
docker executable found in the user’s path (and on
macOS includes a few other well-known search paths). This search strategy can be
overridden by setting the
MUTAGEN_DOCKER_PATH environment variable (for the
Mutagen daemon) to a path containing the desired Docker client executable.