Docker

Get Started with Docker - Part 2a: Raspberry Pi Install Guide

Repro Dev

Apr 4, 2023 • 9 min read

Logos Property of Raspberry Pi https://www.raspberrypi.com & Docker https://www.docker.com

Running Docker is pretty straightforward on Linux and makes using a Raspberry Pi, in my opinion a lot easier. It's really helpful when trying to squeeze out every last bit of performance from the lil computer that can.

❓

If you're looking to install this on Windows then click the link below for our Windows Setup Guide : "Get Started with Docker - Part 2b: Windows Install Guide"

Personally, I’ve found Raspberry Pi OS to be most the stable distribution when using the Pi. You can of course use your preferred Linux flavour like Ubuntu, Fedora etc as the operating system for your Pi.

In this guide, we'll install Docker onto a Raspberry Pi 4B 4GB using Raspberry Pi OS.

We're going to:

Update your Raspberry Pi and Raspberry Pi OS Linux
Install Docker and all it’s required components using the convenience script
Install Docker Compose
Add your Pi user to the Docker group
Test the installation with your first test Docker Container

via GIPHY

💡

If you want to know how to "Set up Your Raspberry Pi with Rasperry Pi OS" then check out the below Beginner's Guide to Get Started and then you can continue along with the rest of the guide below.

Using GUI or SSH?

In my case I like to use SSH to connect from another machine, as it uses less resources than the GUI.

Using SSH means you don't have to have a monitor plugged into your Pi to run commands which can help devices like the Pi Zero.

You’re welcome to use the commands in this guide either in the terminal using the GUI, or connecting via SSH.

This guide will also assume that you've connected to your Pi using SSH once already and know it's IP address or can find it.

via GIPHY

The Beginner's Guide walks you through how to find your Pi's IP address if you need a refresher or are unsure.

First, let's make sure the Pi's updated.

💡

The example IP address for the Pi in this guide, is 192.168.0.177 but yours will probably be different so please replace that below as needed.

💡

We're also going to be using the username pi in this guide but if you've changed yours then please replace it for the username as needed to.

Update Your Pi

via GIPHY

Connect to your Pi using SSH

Open up Windows Terminal and enter the below with your username and IP Address

ssh [email protected]

You'll then be prompted for your password to login.

Run an update and upgrade on the Pi using the sudo command below

sudo apt-get update && sudo apt-get upgrade

This will take a few minutes depending on your internet connection and the last time your Pi was updated.

Type "Y" and Press Enter to continue and install the updates.
Installing the updates will take a lot longer than checking for them so this is the perfect time to grab a coffee and come back later.

Once updated you'll come back to the command line.
Type the below command to reboot your PI to commit the updates, wait for it to start back up and connect again by using SSH for the next step.

sudo systemctl reboot

❗

Please Note: If your Pi hangs, become unresponsive and doesn’t reboot here. Then you may need to disconnect the power cable from the back of the Pi, wait about 15 seconds and reconnect it. This will power cycle the Pi and shouldn’t damage anything but may be the only way to get it to fully reboot as a last resort.

Install Docker

Docker on Raspberry Pi OS is officially supported and that means we can use an install script to automate most of the setup, provided by Docker.

Once you've updated and rebooted then connect back to the Pi using SSH

Credit to this article from PiMyLife for the suggestion of piping the script directly into the terminal using the below one liner.

via GIPHY

I'd also suggest adding on the sudo command at the beginning as I've had some issues with the curl command failing to download on an Azure Ubuntu VM installation.

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

This will take a lot longer than the previous update took earlier and the script will download all files and dependencies needed for your Docker installation.

You may want to grab another coffee and let the script do it's work

You now have Docker with the Docker Engine installed on your Raspberry Pi.
Type the below line and Press Enter to check for any running docker containers

sudo docker ps

via GIPHY

Install Docker Compose

You’ve almost got all of the basic components for Docker installed but if you want to use Docker Compose YAML files then you’ll need to have Docker Compose installed.

Type the below command and Press Enter to get it installed

sudo apt install docker-compose

Type "Y" and Press Enter to continue and install the updates.

This will remove any extra parts to Docker that were installed using the Automated script and also install what we need to get Docker Compose running.

Once that’s installed, you can check your Docker Compose version with the below command.

sudo docker-compose version

Then type "clear" and Press Enter to clear the terminal for our next step.

clear

Now that we’ve installed Docker, Docker Engine and Docker Compose, we need to set up our Docker permissions.

Add Pi User to Docker

You've now got Docker installed but when you try to run a Docker command you get a permissions issue.

We have a few options here.

You can add sudo before every command, su - to become root or add the Pi user to the Docker group.

We’re going to go for the third option.

via GIPHY

Open a New Terminal or if you're continuing from our last step it should look like this

If you HAVEN'T used the convenience script then you need to create the docker group first using the below command

sudo groupadd docker

If you HAVE used the convenience script then type the below line and Press Enter to add the Pi user to the Docker group.

sudo usermod -aG docker pi

To apply the changes you’ll need to log out and back in via SSH.
Type "logout" and Press Enter to logout

logout

💡

Please note: If you are using a VM then you will probably need to reboot the VM for these changes for your user changes to apply

Connect back to Log back in, using the Pi user and password

Run the below command to see which groups the Pi user is currently a member of

groups

You should see docker as one of the groups listed for Pi with a line similar to this in the terminal output.

We need to apply the changes to the running Docker Service.
We can do this by restarting that service only, without restarting the whole Pi
Run the below command and Press Enter to restart the docker service

sudo service docker restart

Run the below docker command to check for running containers again. This time without using sudo before it

docker ps

Congratulations, the Pi user is now part of the docker group.

via GIPHY

This means you can now run docker commands without running sudo or being logged in as root.

Testing your Docker Installation - Hello World

We should now have Docker and Docker Compose installed. In addition, the Pi user should be able to use Docker commands.

To test this all out run the below command in your terminal

docker run hello-world

This should then download the "hello world" docker image from Docker Hub, create the container locally and output some text to the terminal.

If you look in the output you'll see this message and then a brief explanation of what this just did.

Hello from Docker!
This message shows that your installation appears to be working correctly.

Congratulations, you've successfully set up Docker on your Raspberry Pi. We're finally ready to spin up some applications and services.

via GIPHY

Next up, we’ll set up our first Docker Container on the Raspberry Pi 4 to help block ads and malicious websites on your whole network, Pi-Hole.

Don't forget to explore the rest of our website as we build out more content. Stay tuned for more tutorials, tips, and tricks to help you make tech work for you.

If you want to stay up-to-date with regular updates, make sure to subscribe to our free mailing list.