How To Install and Setup Docker on a Raspberry Pi

2023-07-26 | By Maker.io Staff

A recent article introduced Docker, a tool that makes using lightweight Unix containers more convenient, allowing you to perform various tasks that come with deploying, installing, and managing software. This article, however, will explain how you can install Docker and download and run a pre-packaged container on a Raspberry Pi. While this article focuses on the Raspberry Pi, the process translates well to other Linux-based systems.

Installing Docker

Begin by running the apt update and upgrade command on the Raspberry Pi:

Copy Code

sudo apt update && sudo apt upgrade

While many methods exist to install docker on a Linux machine, the official convenience script is the most straightforward approach for beginners. After running the update and upgrade commands from above, type the following command into a terminal window on the Raspberry Pi:

Copy Code

sudo curl -sSL https://get.docker.com | sh

This action retrieves and immediately executes the script from the docker download page. Note that you shouldn’t normally use this approach, as you can’t review how the script functions. In this case, though, docker is a well-respected, trusted source, and using the script can save quite a bit of typing. Once downloaded, the script will run all necessary configuration and installation steps automatically and display the following message once complete:

How To Install and Setup Docker on a Raspberry Pi The script outputs a short summary once it finishes installing docker.

Adding a User to the Docker Group

Once installed, running any docker command without root privileges will result in the system showing an error message:

How To Install and Setup Docker on a Raspberry Pi Running any docker command without root privileges causes an error.

However, running the following command will add the pi user to the docker group, allowing you to execute docker commands:

Copy Code

sudo usermod -aG docker pi

Note that while you could run all docker commands using sudo, doing so is generally considered bad practice as it imposes potential security risks. Further, not all processes need root access, and therefore adding all affected users to the docker group is better. If you change the currently logged-in user, you must log out (using exit) and log back in for the changes to take effect:

How To Install and Setup Docker on a Raspberry Pi Follow these steps to add the pi user to the docker group, allowing that user to run docker commands without root privileges.

At this point, there are no running containers, and as a result, docker ps returns an empty list. Even so, using any docker command without the system reporting an error indicates that the installation was successful and docker is ready to use.

Installing and Running a Docker Container

While there are countless pre-packaged docker containers containing various valuable applications, this tutorial illustrates how to download and run a docker container using a pre-made version of WordPress for docker. Keep in mind that any other application from the docker hub would work just fine, and the hello-world example is also commonly used to test whether creating containers in docker works as expected.

Regardless, the following command downloads the latest version of the WordPress container:

Copy Code

docker pull wordpress

Once done, it can be run using the following command:

Copy Code

docker run wordpress

You could skip the docker pull step, as docker will attempt to find and download the latest version of an unknown container when running a container that docker can’t find locally. Whatever the case, using docker run without additional options starts the WordPress container as a new foreground process and assigns it a random name. Typically, you may want to run docker containers as so-called detached processes, allowing the started application to run in the background. For each process started in such a way, it’s advisable to assign an individual name. Doing so allows you to quickly identify the program, which makes stopping or restarting the background service easier. Both tasks can be accomplished using the following options:

Copy Code

docker run --name my-wordpress-website -d wordpress

In the command above, -d stands for detached, indicating that the WordPress container should run in the background. It’s also possible and often desired to configure how docker should automatically restart a container, should the program crash or the OS restart. A docker container’s restart behavior can be changed by using the restart option:

Copy Code

docker run --name my-wp-website --restart always -d wordpress

The possible options for automatically restarting a docker container are no, always, on-failure, and unless-stopped, and the docker documentation contains further details. Finally, check the status of the newly created container using docker ps, as shown below:

How To Install and Setup Docker on a Raspberry Pi This image shows that the ps command now lists the newly started WordPress container.

Summary

Installing docker on a Raspberry Pi can be done with only a few simple-to-follow steps, thanks to an automated installation script. First, begin by updating and upgrading the packages. Then, use curl to download the installation script. The pipe operation allows you to directly run the script without storing it on the Pi’s SD card.

After a while, the installer will inform you that the process is complete. It’s recommended to add all users who will use docker to the docker group, which can be achieved using the usermod command.

Finally, use docker pull to download containers, docker run to start them, and docker ps to check the container’s status. Refer to the container’s documentation page for further configuration parameters and options. Regardless of a container’s options, the -d flag can run a container in the background, and restart allows you to configure a container’s auto-start behavior.