fixuid

by boxboat

boxboat / fixuid

Go binary to change Docker container user/group and file permissions at runtime

250 Stars 22 Forks Last release: 4 months ago (v0.5) MIT License 37 Commits 6 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

fixuid

Build Status

fixuid
is a Go binary that changes a Docker container's user/group and file permissions that were set at build time to the UID/GID that the container was started with at runtime. Primary use case is in development Docker containers when working with host mounted volumes.

fixuid
was born because there is currently no way to remap host volume UIDs/GIDs from the Docker Engine, see moby issue 7198 for more details.

Check out BoxBoat's blog post for a practical explanation of how

fixuid
benefits development teams consisting of multiple developers.

fixuid should only be used in development Docker containers. DO NOT INCLUDE in a production container image

Overview

  • build a Dockerfile with user/group
    dockeruser:dockergroup
    that has UID/GID
    1000:1000
  • host is running as UID/GID 1001:1002, host mounted volume has permissions 1001:1002
  • run the docker container with argument
    -u 1001:1002
    so that container is now running with same UID/GID as host
  • fixuid
    can run as an entrypoint or in a startup script and performs the following:
    • changes
      dockeruser
      UID to 1001
    • changes
      dockergroup
      GID to 1002
    • changes all file permissions for old
      dockeruser:dockergroup
      to 1001:1002
    • updates $HOME inside container to
      dockeruser
      $HOME
  • now container UID/GID matches host UID/GID and files created in the container on the host mount will be correct

Motivation

Common Docker development workflows involve mounting source code into a container via a host volume. Build tools such as

gradle
,
yarn
,
webpack
, etc. download dependencies and create files in the host mount.

Many times the UID/GID of the build tools running in the Docker container do not match the UID/GID of the mounted host volume, and files generated in the container do not match files in the host volume. This can lead to problems, such as an IDE running on the host not able to modify a file that was created by the container due to a file ownership mismatch.

In large development teams, it is possible to have many developers running as different UIDs/GIDs on their host systems. With

fixuid
, individual developers can run the same container using the appropriate UID/GID for their host environment.

Install fixuid in Dockerfile

  1. Create a non-root user and group inside of your docker container. Use any UID/GID, 1000:1000 is a good choice.

    Note: some images already create UID/GID 1000:1000 for you, e.g.

    nodejs
    creates user/group
    node:node
    as UID/GID 1000:1000. In this case you can skip this step and use the
    node:node
    user/group.
# sample command to create user/group on different base images
# creates user "docker" with UID 1000, home directory /home/docker, and shell /bin/sh
# creates group "docker" with GID 1000

alpine

RUN addgroup -g 1000 docker &&
adduser -u 1000 -G docker -h /home/docker -s /bin/sh -D docker

debian / ubuntu

RUN addgroup --gid 1000 docker &&
adduser --uid 1000 --ingroup docker --home /home/docker --shell /bin/sh --disabled-password --gecos "" docker

centos / fedora

RUN groupadd -g 1000 docker &&
useradd -u 1000 -g docker -d /home/docker -s /bin/sh docker

  1. Install

    fixuid
    in the container, ensure that root owns the file, make it execuatble, and enable the setuid bit. Create the file
    /etc/fixuid/config.yml
    with two lines,
    user: 
    and
    group: 
    using the user and group from step 1.

    Note: this command must be run as root and requires that

    curl
    is installed in the container
RUN USER=docker && \
    GROUP=docker && \
    curl -SsL https://github.com/boxboat/fixuid/releases/download/v0.5/fixuid-0.5-linux-amd64.tar.gz | tar -C /usr/local/bin -xzf - && \
    chown root:root /usr/local/bin/fixuid && \
    chmod 4755 /usr/local/bin/fixuid && \
    mkdir -p /etc/fixuid && \
    printf "user: $USER\ngroup: $GROUP\n" > /etc/fixuid/config.yml
  1. Set the default user/group to
    user:group
    and set the entrypoint to
    fixuid
    .
USER docker:docker
ENTRYPOINT ["fixuid"]
  1. Run the container using UID/GID of your host. Replace
    1000:1000
    with your host's
    UID/GID
    :
docker run --rm -it -u 1000:1000  sh

Set Default Values inside of Docker Compose

Set a default UID and GID for the container to run as inside of the

docker-compose.yml
file. Developers who are running as a different UID/GID on their host can override the defaults using environment variables or a .env file
nginx:
  image: my-nginx
  user: ${FIXUID:-1000}:${FIXGID:-1000}
  volumes:
    - ./nginx:/etc/nginx
    - ./www:/var/www

Specify Paths and Behavior across Devices

The default behavior of

fixuid
is to start at the root path
/
and recursively scan each file and directory on the same devices as
/
. In the configuration file
/etc/fixuid/config.yml
, you can specify specify the directories that should be recursively scanned:
user: docker
group: docker
paths:
  - /home/docker
  - /tmp

fixuid
will only recurse into a directory as long as it is on the same initial device specified in
paths
and will not recurse into directories mounted on other devices. This includes Docker volumes. If you want
fixuid
to run on the root Docker filesystem and a Docker volume at
/home/docker/.cache
, your configuration should include:
user: docker
group: docker
paths:
  - /
  - /home/docker/.cache

Run in Startup Script instead of Entrypoint

You can run

fixuid
as part of your container's startup script.
fixuid
will
export HOME=/path/to/home
if $HOME is the default value of
/
, so be sure to evaluate the output of
fixuid
when running as a script.
#!/bin/sh

UID/GID map to unknown user/group, $HOME=/ (the default when no home directory is defined)

eval $( fixuid )

UID/GID now match user/group, $HOME has been set to user's home directory

Command-Line Flags

fixuid
has the following command-line flags:
Usage of ./fixuid:
  -q    quiet mode

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.