Docker, Docker Compose and permissions

Introduction

Docker and Docker Compose are awesome. Just yesterday I had to install a software to create a user interface on top of the software's API. It took me only minutes to download the Dockerfile, add some configuration using Docker Compose, build the image and run the container. I am super happy Docker and Docker Compose exist, but I would like to see some improvements on macOS.

The concept of users, groups and file permissions is awesome, too. If you are new to this, I would recommend this article, that covers all the basics.

The problem

Last year I switched from macOS to Linux because of some performance issues. The switch definitely improved speed and stability of Docker volumes, but I kept running into a problem which did not occur on macOS: Broken file permissions.

When using Docker on macOS the file permissions do not get synchronized between your local machine and docker containers. On Linux file permissions get synchronized, which in my opinion is actually the way it should be for all operating systems.

This was a huge problem.

If I changed files locally, the file permissions would get changed inside of the container with user and group which did not even exist inside of the container.

If I changed files inside of the container using the only existing root user, the file permissions would also get changed on my local machine to root:root.

At the time a configuration looked roughly like the following:

{% details Click to open Dockerfile %}

# Define base image
FROM php:8.0-cli-buster

{% enddetails %}

{% details Click to open docker-compose.yml %}

version: '3.3'

networks:
  web:
    external: true

services:
  application:
    container_name: application
    build:
      context: .
      dockerfile: ./Dockerfile
    networks:
      - web
    volumes:
      - ./:/var/www/html/
    restart: always

{% enddetails %}

We used to run commands like this:

docker-compose exec application bash

The solution

Create a user and a group inside of the Docker container with the same IDs you are using locally. When this is done file permissions can be synchronized, because the same user and group is used.

At first you have to export your user and group ID in your shell configuration (e. g. ~/.zshrc or ~/.bashrc):

# Export variables for Docker and Docker Compose
export USER_ID=$(id -u)
export GROUP_ID=$(id -g)

Now our configuration looks roughly like this:

{% details Click to open Dockerfile %}

# Define base image
FROM php:8.0-cli-buster

# Define build arguments
ARG USER_ID
ARG GROUP_ID

# Define environment variables
ENV USER_ID=$USER_ID
ENV GROUP_ID=$GROUP_ID
ENV USER_ID=${USER_ID:-1001}
ENV GROUP_ID=${GROUP_ID:-1001}

# Add group and user based on build arguments
RUN addgroup --gid ${GROUP_ID} alice
RUN adduser --disabled-password --gecos '' --uid ${USER_ID} --gid ${GROUP_ID} alice

# Set user and group of working directory
RUN chown -R alice:alice /var/www/html

{% enddetails %}

{% details Click to open docker-compose.yml %}

version: '3.3'

networks:
  web:
    external: true

services:
  application:
    container_name: application
    build:
      context: .
      dockerfile: ./Dockerfile
      args:
        USER_ID: $USER_ID
        GROUP_ID: $GROUP_ID
    networks:
      - web
    volumes:
      - ./:/var/www/html/
    restart: always

{% enddetails %}

From now on you have to execute commands inside of the container using the newly generated user. We now run commands like this:

docker-compose exec --user alice application bash

Further reading

If you want to read more about our local development environment using Docker and Docker Compose, have a look at an article a colleague of mine wrote a while ago.

Dorien Grönwald

Accessible website: 7 steps to better accessibility and SEO performance

Web accessibility enables people with physical and/or mental disabilities to use the Internet with as...

Discover full article

Malte Riechmann

New git guidelines: We have switched to Conventional Commits

Giving teams as much autonomy as possible is a good idea, but having some company-wide guidelines can...

Discover full article

Cleo Pelte

One year of coding – recommendations for beginners from a beginner

This month one year ago I started my three year long journey as a web development trainee/apprentice...

Discover full article
View all articles