Running applications with Docker as a daily routine can become a nightmare when you run into an error such as Docker permission denied while trying to connect. But don’t worry, this article will help you get back running in no time.
In this tutorial, you will learn many ways to resolve the dreaded Docker permission denied error message.
Prerequisites
This tutorial comprises hands-on demonstrations. To follow along, be sure you have the following in place:
- The demos in this tutorial run on Ubuntu 20.04, but other Linux distributions will also work.
- The Docker engine, with the tutorial running version 20.10.8, build 3967b7d.
Running Elevated Docker Commands
Many factors could lead to a permission denied error while connecting to Docker. One of those factors is that you may be running Docker commands without prepending the sudo
command. The sudo
command is what gives you elevated administrative rights along with security privileges when running commands.
Below, you can see the dreaded permission denied error while trying to run a docker
command.
Launch your terminal and prepend sudo
to the docker
command below to run
the hello-world
Docker image. Since you’re running an elevated command, you’ll need to enter your password to proceed.
sudo docker run hello-world
You’ll see an output similar to that shown below that indicates that Docker is installed correctly.
Restarting the Docker Engine
If running elevated Docker commands does not fix the permission denied error, verify that your Docker Engine is running. Similar to running a docker
command without the sudo
command, a stopped Docker Engine triggers the permission denied error. How do you fix the error? By restarting your Docker engine.
Run the systemctl
command below to confirm the Docker Engine’s status (status docker
) and if it’s running.
sudo systemctl status docker
Below, you can tell the Docker Engine is running from the returned status that shows active (running).
If the Docker Engine isn’t active, run the systemctl
command below to start the Docker Engine (start docker
).
sudo systemctl start docker
Now, run the hello-world Docker command as you did in the “Running Elevated Docker Commands” section to verify that the error is resolved.
sudo docker run hello-world
Adding User Account to a Group with Non-Root User Access
You’ve confirmed your Docker engine is working, but you’re still getting a Docker permission denied error? If so, you need to add your user account to a group with non-root user access. Why? Because any Docker command you run on a Linux machine not in the user group triggers permission denied error.
- Run the
groupadd
command below to create a new group calleddocker
. Enter your password to continue running the command.
sudo groupadd docker
If the docker group exists in the user group, you will see an output like the one below.
2. Next, run the usermod
command below where the -aG
options tell the command to add your user account (programmer
) to the (docker
) group. This command causes your user account to have non-user access.
sudo usermod -aG docker programmer
3. Run the newgrp
command below to change the current real group ID to the docker
group.
Run this command each time you want to run Docker as a non-root user.
sudo newgrp docker
4. Finally, rerun the hello-world Docker image to confirm that you no longer see the error. If, at this point, you’re still getting an error, then consider giving more access to the docker.sock file. The docker.sock file is the UNIX socket, a way to communicate process information between the user and the system, that the Docker daemon listens to as the Docker API’s entry point.
Run the chmod
command below to grant all users read/write (666
) access to the /var/run/docker.sock
file. Now run the hello-world Docker image again to see if the error is resolved.
sudo chmod 666 /var/run/docker.sock
Editing the Docker Service Unit File
If running Docker as a non-root user is not enough to fix the error, try editing the Docker SystemD, a service control system, service unit file. The Docker service file contains sensitive parameters that may alter the behavior of the Docker daemon. You can modify the Docker unit file’s default behavior by adding an extra command to change the service default behavior.
1. Run the command below to open the Docker service unit file in your favorite text editor. For this example, the Docker service file opens in the nano text editor.
sudo nano /usr/lib/systemd/system/docker.service
2. Locate the area with the [Service] header inside the Docker service unit file, as shown below. Copy/paste the commands below to the Docker service unit file and save the changes.
Below, the SupplementaryGroups
command sets the supplementary Unix groups to where the processes are executed. At the same time, the ExecStartPost
command cleans up operations that are executed even if the service fails to start up correctly.
SupplementaryGroups=docker
ExecStartPost=/bin/chmod 666 /var/run/docker.sock
3. Now, run the commands below to restart and enable the Docker service. Doing so lets you start the Docker service anew to avoid getting errors when you run Docker commands.
# Reloads all the Docker unit files and recreates the entire dependency tree.
sudo systemctl daemon-reload
# Restarts the Docker service
sudo systemctl start docker
# Enable the Docker to run on your computer.
sudo systemctl enable docker
4. Finally, rerun the hello-world
Docker image and see if you still get the permission denied error.
Running Docker in Privilege Mode
Last but not least, on the list of fixing the Docker permission denied error is running Docker in privileged mode. Doing so grants a Docker container root access to the system.
Running Docker in privileged mode is risky and vulnerable to attacks from hackers. So be cautious and only run the Docker in privileged mode when you know exactly what you’re doing.
1. Run the command below to list all Docker containers in your system, and get the ID of the container you want to run.
sudo docker ls -a
2. Next, run the docker inspect
command below to check if the container you want to run is already in privileged mode (--format='{{.HostConfig.Privileged}}'
). Replace CONTAINER_ID
below with the actual container ID that you took note of in step one.
docker inspect --format='{{.HostConfig.Privileged}}' CONTAINER_ID
If the container is in privileged mode, the command returns a true value to the console. But if the command returns a false value, as shown below, move on to the next step.
3. Finally, run the docker
command below to run
the Docker container in privileged mode (--privileged hello-world
).
sudo docker run --privileged hello-world
Conclusion
Throughout this tutorial, you’ve learned many ways to solve the Docker permission denied error, from running elevated commands to running Docker in privileged mode.
Now you know how to rid of an error when building Docker-powered applications; perhaps you also want to keep your Docker images clean at all times?