Skip to main content

141. Docker Group Membership for Non-Root Access

Status: Accepted Date: 2025-07-06

Context​

By default, running Docker commands requires root privileges. This means every docker command must be prefixed with sudo, which is cumbersome, annoying, and can lead to permission issues with files created inside containers.

The standard and recommended way to avoid this is to add the user to the docker group, which is created during Docker's installation. Members of this group are granted permission to communicate with the Docker daemon socket, effectively allowing them to run Docker commands without sudo.

Decision​

The 08_docker Ansible role will be responsible for managing membership of the docker group.

The role will take a list of usernames as a variable. It will then use Ansible's user module to ensure that each user in this list is added to the docker group. This is a simple, idempotent operation that establishes the standard, "rootless" Docker workflow for all specified users.

Consequences​

Positive:

  • Improved Developer Experience: This is a massive quality-of-life improvement. Developers can run docker, docker-compose, etc., directly, without sudo. This simplifies commands and avoids messy file permission problems.
  • Adheres to Best Practices: This is the official, recommended way to manage Docker permissions for users.
  • Centralized Management: The list of users who should have Docker access is managed centrally in our Ansible inventory, which is the correct place for it.

Negative:

  • Security Implications: It is critical to understand that adding a user to the docker group is functionally equivalent to giving them passwordless root access to the host machine. A user with Docker access can easily run a container that mounts the host's root filesystem (-v /:/host) and do anything they want to the system.

Mitigation:

  • Controlled Access: This is not a permission that is granted to all users by default. We are using this on developer machines and servers where the primary users are already trusted administrators of the system. We would not, for example, add a regular, non-privileged user to the docker group on a multi-user production server. The decision of who to add to this group is a security decision that is made consciously in the Ansible inventory.
  • Clear Understanding: This ADR exists to document this trade-off explicitly. We are choosing to accept this security consideration in exchange for the significant improvement in developer workflow, in the context of trusted users on development-focused machines.