tl;dr: If a container produces build artefacts in a mounted directory, enable
run_as_current_user, otherwise they'll be owned by the
On Linux, by default, the Docker daemon runs as
root, and so all containers run as
root. This means that when a container writes a file to a mounted directory,
it is owned by the
root Unix user, making it difficult for other users to modify or delete the files. In particular, when a build task produces an artefact
and writes that artefact to a mounted directory, the artefact would be written as
(On macOS and Windows, the Docker daemon runs as the currently logged-in user and so any files created in mounted directories are owned by that user, so this is not an issue.)
To fix this issue, Batect can run containers in run as current user mode, ensuring that all files written to a
mounted directory are created by the current user, not
This mode can be enabled on a per-container basis with the
run_as_current_user option, for example::
When run as current user mode is enabled, the following configuration changes are made:
The container is run with the current user's UID and GID (equivalent to passing
--user $(id -u):$(id -g)to
An empty directory is mounted into the container at
home_directoryfor the user's home directory.
If the directory given by
home_directoryalready exists inside the image for this container, it is overwritten.
/etc/passwdfile is mounted into the container with two users:
rootand the current user. The current user's home directory is set to the value of
home_directory. (If Batect is running as
root, then just
rootis listed and it takes the home directory provided in
This means that any other users defined in the container's image are effectively lost. Under most circumstances, this is not an issue.
Similarly, a new
/etc/groupfile is mounted into the container with two groups:
rootand the current user's primary group (usually
staffon macOS, and the user's name on Linux). If Batect is running as
root, then just
Again, this means that any other groups defined in the container's image are effectively lost. Under most circumstances, this is not an issue.
While run as current user mode is really only useful on Linux, for consistency, Batect makes the same configuration changes regardless of the host operating system. These configuration changes are harmless on macOS and Windows.
On Windows, the container is run with UID 0 and GID 0 and the user and group name
root. This is because any mounted directories
are always owned by
root when running on Windows, and so running as another user can cause issues interacting with mounted directories.
root's home directory inside the container is set to match the directory specified by
Run as current user mode is not applicable for Windows containers.