Docker® container endpoints

Mutagen has support for synchronizing files and forwarding network traffic to and from 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).

Tip: This page describes Mutagen’s low-level Docker transport. This transport is useful if you want to integrate Mutagen into a script or tool that targets Docker containers. For turnkey containerized development options, check out the Mutagen extension for Docker Desktop and/or Mutagen Compose.

Caution: Mutagen assumes that the transport from the docker command 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.

Requirements

Mutagen requires the docker command to be in the user’s path. Due to its use of the -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.

Synchronization

Docker container filesystem endpoints can be specified to the mutagen sync create command using URLs of the form:

docker://[<user>@]<container><path>

These URLs support Unicode names and paths and neither require nor support URL escape encoding (i.e. just type “ö”, not “%C3%B6”, etc.).

The <user> component is optional and tells Mutagen to run as the specified user inside the container. If unspecified, Mutagen operates as the default container user (usually root for Linux containers or ContainerAdministrator for Windows containers). In either case, the user should be chosen in such a way as to allow access permissions to the target path and to generate files with the correct permissions. Using an administrative user (such as root) for access and setting permissions explicitly is often the most robust strategy with containers.

The <container> component can specify any type of container identifier understood by docker cp and docker exec (for example, a container name or hexidecimal identifier).

The <path> component must be non-empty and must start with a /. It 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. In the case of a Windows path, the / character is still requird at the start of the path.

Docker containers must be running to create synchronization sessions and to allow synchronization to run.

Example Docker container synchronization URLs

docker://project_container_1/var/www
Target an absolute path in the container named project_container_1.
docker://9ba4bcda42fe/~/project
Target a path relative to the default container user's home directory in the container with the ID 9ba4bcda42fe.
docker://george@9ba4bcda42fe/~/project
Target a path relative to the george user's home directory in the container with the ID 9ba4bcda42fe.
docker://project_container_1/~otheruser/project
Target a path relative to a specific user's home directory in the container named project_container_1.
docker://windows_container_1/C:\path
Target an absolute path in a Windows container named windows_container_1. Note that, in POSIX shells, the backslash character will require quoting or escaping.

Forwarding

Docker container network endpoints can be specified to the mutagen forward create command using URLs of the form:

docker://[<user>@]<container>:<network-endpoint>

The <user> and <container> components of this URL are the same those in the synchronization URL format described above, while the <network-endpoint> component is described in the forwarding documentation. As with synchronization, the <user> component (or absence thereof) should be chosen to ensure the necessary in-container capabilities (e.g. binding to privileged ports). In the case of relative Unix domain socket paths in network endpoints, path resolution will be performed relative to the home directory of the container user (i.e. the user specified in the URL or the default container user if none is specified in the URL).

Docker containers must be running to create forwarding sessions and to allow forwarding to run.

Example Docker container forwarding URLs

docker://project_container_1:tcp::8080
Bind to all network interfaces on port 8080 in the container named project_container_1.
docker://george@project_container_1:tcp:localhost:8080
Bind to or target the loopback interface on port 8080 as the user george in the container named project_container_1.
docker://project_container_1:tcp6:localhost:8080
Bind to or target the IPv6 loopback interface on port 8080 in the container named project_container_1.
docker://george@project_container_1:tcp:10.0.1.25:6060
Bind to or target 10.0.1.25 on port 6060 as the user geroge in the container named project_container_1.
docker://9ba4bcda42fe:unix:/path/to/socket.sock
Bind to or target a Unix domain socket using an absolute path in the container with the ID 9ba4bcda42fe.
docker://project_container_1:unix:path/to/socket.sock
Bind to or target a Unix domain socket using a relative path in the container named project_container_1. Path resolution in this case is relative to the home directory of the default container user.
docker://project_container_1:unix:~/path/to/socket.sock
Bind to or target a Unix domain socket relative to the default container user's home directory in the container named project_container_1.
docker://project_container_1:unix:~otheruser/path/to/socket.sock
Bind to or target a Unix domain socket relative to a specific user's home directory in the container named project_container_1.

Environment variables

The Docker client’s behavior is controlled by several environment variables:

DOCKER_HOST
DOCKER_TLS_VERIFY
DOCKER_CERT_PATH
DOCKER_API_VERSION
DOCKER_CONTEXT (in Mutagen v0.12+)

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_ALPHA_/MUTAGEN_BETA_ for synchronization sessions and MUTAGEN_SOURCE_/MUTAGEN_DESTINATION_ for forwarding sessions) can be used to override their values on a per-endpoint basis. This would be necessary to, for example, create a synchronization session between two Docker containers hosted on different Docker daemons. In that case, single global values for DOCKER_* environment variables can’t be used (since it would apply to both endpoint URLs), and endpoint-specific variables such as MUTAGEN_ALPHA_DOCKER_HOST or MUTAGEN_BETA_DOCKER_TLS_VERIFY would need to be used when invoking mutagen sync create.

Implementation

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.

Windows containers

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.

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.

Windows and Chocolatey

If you’re using Chocolatey to install the Docker CLI on Windows, please be aware that Chocolatey generates shim executables that break the standard input/output streaming that Mutagen uses. Fortunately, you can point Mutagen to the unshimmed executables to avoid this breakage by setting the MUTAGEN_DOCKER_PATH environment variable. This setting should look like:

MUTAGEN_DOCKER_PATH=C:\ProgramData\chocolatey\lib\docker-cli\tools

You may need to adjust this path depending on your Chocolatey installation. You can also use the %ChocolateyInstall% environment variable as part of this definition, for example:

MUTAGEN_DOCKER_PATH=%ChocolateyInstall%\lib\docker-cli\tools