Setup a Docker environment with Raspberry PI OS Lite and Portainer

Check my RPI articles in Best Raspberry PI projects article or home page. Or subscribe my newsletter (top right in this page) to be notified when new projects are available! Also interested to start 3D printing with a cheap budget? Visit my cheap 3D printers list

Docker containers are the new trend in deploying micro services without the need of duplicating OS job on host machine. They are also fast and allow quick development techiques unavailable in classic development. It is possible (and useful) install Docker in Raspberry PI, getting container advantages in our powerful single board, credit sized computer

In this tutorial, I’ll show you how to setup a docker environment and Portainer (a powerful docker GUI) with Raspberry PI OS Lite.

With the new Raspberry PI OS, it’s interesting to check if some basilar installations are going to be as simple as with previous version.

One of my favourite RPI feature, was using containers to deploy in very simple ways services like nginx, python, linux distributions, web servers, IoT applications and so on.

With the open source docker engine, you can use docker containers to get with single line “docker run” commands. You can also use base images to customize your services with the “docker build” command and very simple dockerfiles. The docker-compose command enables you to deploy complete services defined in simple “docker-compose.yml” files. Finally, the “docker swarm” command will simplify Raspberry PI cluster creation to distribute load between different phisical boards.

RPI 3 model A+

When using Docker Hub images for your projects, you need to check that these are available for ARM architecture: Raspberry PI has arm processors, so only those docker images which are compiled for arm can be run on RPI. Sometimes also processor version can be crucial: for example, some docker images are compiled to run only with armv7 or newer.

This procedure have been tested on a Raspberry Pi model Zero W, PI 3 Model A+, PI 3 Model B/B+, PI 4, but the same steps should work for all other Raspberry Pi models with internet connectivity.

What we need

To setup our docker environment using the new Raspberry Pi model A+, we’ll not use keyboards or TV cables. Our OS installation will provide a basis having already WiFi and SSH ready to be used at first boot.


SANDISK Ultra 16GB MicroSD

I suggest adding from now to your shopping chart all needed hardware, so that at the end you will be able to evaluate overall costs and decide if continuing with the project or removing them from shopping chart.

Check hardware prices with following links:

Amazon raspberry pi boards box
Amazon Micro SD box
Amazon Raspberry PI Power Supply box

Step-by-step guide to setup Docker

Setup process is really simple.

Prepare Operating System

First step consists in installing Raspberry PI OS Lite, to get a fast and light operating system

Before going on docker engine installation, be sure to have an updated OS. From SSH command line, type following commands:

sudo apt update
sudo apt upgrade

Install Docker on Raspberry PI

The default (and suggested) docker engine installation comes with convenience script, a simplified bash installation script which makes all the work for you. This adds repositories to your apt file, download and installs dependencies and latest docker engine version. Type following commands from terminal:

curl -fsSL -o
sudo sh

It will take a few minutes to complete installation.

Some Raspberry PI models experienced an “E: Sub-process /usr/bin/dpkg returned an error code (1)” after “sudo sh” command. Ashley, in this post comments, found that adding “cgroup_enable=memory cgroup_memory=1 swapaccount=1” in /boot/cmdline.txt solved this error in Raspberry PI 4 Model B. This change requires a reboot.

At prompt, test it by typing following docker command:

sudo docker version

From here, your “docker run” commands are available to deploy your favourite docker containers.

You can also test by running the default hello-world docker image by docker run command:

sudo docker run hello-world

Since this is your very first container deployed and you haven’t any related image already downloaded, it will download requested docker container from Docker Hub, extract packages and run them.

If you would like to use Docker as a non-root user, you should now consider adding your user to the “docker” group. To accomplish it for default pi user:

sudo usermod -aG docker pi

You will need to logout and login (or reboot) to make it working or you will have still permission issues using docker without sudo.

Install Portainer

A graceful web GUI helping in managing containers is portainer. In our case, we need to install an arm compatible version and then launching it with the docker run command:

docker pull portainer/portainer:linux-arm
docker run -d -p 9000:9000 -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer:linux-arm

Now you can reach your docker server with a browser, just connecting to https://<<RaspberryIpAddress>>:9000.

You will be required to set your default password for admin user, then you will be prompted to portainer GUI:

Portainer new

Install Docker-compose

Docker-compose enables your Docker environment to use yaml files to compose and quickly boot complete services. Its official page suggest installation with pip3, but this sometimes results not working. So, I suggest to use the more resilient apt installation using default repositories, with following command from terminal:

sudo apt install docker-compose

Verify your docker-compose installation by typing:

docker-compose --version

Enjoy your Docker environment inside the Raspberry PI!

How useful was this post?

Click on a star to rate it anonymously!

Average rating 4.8 / 5. Vote count: 18

No votes so far! Be the first to rate this post.

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?