Setup a Docker environment with Raspberry PI OS Lite and Portainer


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

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 computer boards, getting container advantages in our powerful single board, credit sized computer

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

One of my favourite RPI features 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 the 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 the load between different physical 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 has 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 continue with the project or remove them from the shopping cart.

Check hardware prices with the following links:

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

Step-by-step guide to setup Docker

The setup process is really simple.

Prepare Operating System

The first step consists of installing Raspberry PI OS Lite, to get a fast and light operating system

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

sudo apt update -y && sudo apt upgrade -y

Install Docker on Raspberry PI

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

curl -fsSL -o
sudo sh

It will take a few minutes to complete the 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 the 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 the docker run command:

sudo docker run hello-world

Since this is your very first container deployed and you haven’t any related images already downloaded, it will download the 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 the default pi user:

sudo usermod -aG docker pi

You will need to logout and login (or reboot) to make it work 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 launch it with the docker run command:

docker run -d -p 9000:9000 -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest

It will download and install the latest available container version for your Raspberry PI and OS. After this, 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 the 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 suggests installation with pip3, but this sometimes results in not working. So, I suggest using the more resilient apt installation using default repositories, with the following command from the 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: 42

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?