Setup a Docker environment with Raspberry PI OS Lite and Portainer
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
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.
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.
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.
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.
- Raspberry PI 3 Model A+ (including proper power supply or using a smartphone micro usb charger with at least 3A) or newer Raspberry PI Computer Board
- high speed micro SD card (at least 16 GB, at least class 10)
Check hardware prices with the following links:
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 https://get.docker.com -o get-docker.sh sudo sh get-docker.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 get-docker.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.
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:
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:
Enjoy your Docker environment inside the Raspberry PI!
We are sorry that this post was not useful for you!
Let us improve this post!
Tell us how we can improve this post?
17 thoughts on “Setup a Docker environment with Raspberry PI OS Lite and Portainer”
running “sudo sh get-docker.sh”
I got the following error message:
E: Sub-process /usr/bin/dpkg returned an error code (1)
I’m using a pure
Raspberry Pi OS Lite
Release date: August 20th 2020
Kernel version: 5.4
What Raspberry PI model are you using?
I ran into the same thing trying to install on my Pi 4 Model B+
I found that we need to add
“cgroup_enable=memory cgroup_memory=1 swapaccount=1”
to the command line arguments for the kernel in /boot/cmdline.txt
I found this from
Thank you Ashley.
I wasn’t able to reproduce, but I added your note as warning after installation script row.
This worked on my Pi3 Model B, too.
Thanks for this guide!
I really prefer the idea of the apt install over pip. However, the apt docker-compose package was version 1.21.0. Which according to the docker page https://docs.docker.com/compose/release-notes/ is from 2018!
I followed the pip instructions at https://dev.to/rohansawant/installing-docker-and-docker-compose-on-the-raspberry-pi-in-5-simple-steps-3mgl and got v1.27.4
Also, there’s a typo above 🙂 wirking should be working.
thank you for your typo note, corrected.
Regarding docker-compose installation, my previous tutorial version was using pip (as you correctly noted), but in some periods (also during new minor releases in Raspberry PI OS) it sometimes resulted not working. Instead of frustrating users with something they couldn’t explain why their installation failed, I preferred a more stable way with default package manager for RPI OS. You are also correct noting that compose version could have some years of delay, but how many of these new features could be useful to RPI users? I think very very few.
Hello peppe80, thanks for an amazing guide, i was able to run the HA container on port 8125, but when i logged out, it turned off the container i couldn’t get it to work, can you please share solutions. Also, i’m unable to see the HA supervisor, any thing i’m missing?
I suppose you are writing about https://peppe8o.com/install-home-assistant-in-raspberry-pi-with-docker/ and your container stopped is the test one.
When you log-in again, you can restart your container with “docker start homeAssTest”. You can also check your stopped container with “docker ps -a”.
Consider that Test container (as defined in my post) is set to run as a test environment and only with terminal attached. To run it detached from terminal you have to add “-d” option on docker run command. To make it starting again after reboots you have to add the restart policy on docker run command (for example –restart unless-stopped).
Please refer to Production container references later on same post (https://peppe8o.com/install-home-assistant-in-raspberry-pi-with-docker/)
After running this:
docker run -d -p 9000:9000 -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer:linux-arm
I get this as response:
$ The requested image’s platform (linux/amd64) does not match the detected host platform (linux/arm/v7)
I am currently running pi os 32bit. I have seen one similar message on github with some foggy replies. Am I the only one? Eveything is standard here, pi is 8GB (not that this matters)
I used your command in my RPI3 and RPI4 and it works in my boards (standard RPI OS too). From what I’ve now checked in docker hub, I’m afraid that some confusion arised around the new “portainer-ce” container (with final “-ce” added): I can see that they still taggeg their image “linux-arm”, but OS/ARCH results amd64. So, if you previously pulled portainer-ce you could suffer this problem. Solution should be removing image (“docker image rm portainer/portainer-ce:linux-arm”) and then using their “portainer/portainer-ce:alpine” (but this evening I can’t download it, seems that there are problems on remote servers) or old image “portainer/portainer:linux-arm” (which works correctly for the moment).
As said,I’ve just tested old image (without “-ce”) and it currently works. As ce image will be available again, I will test this too.
Thanks for your efforts! This was all done for the first time so I guess the problem is on their end. However, since this is just a pet project (and there are locked up holidays ahead) I’ll wipe everything and start over again. Self education…
If I have any success I’ll let you know here!
So I did it again (w/o uups), this time using the commands from the portainer site:
docker volume create portainer_data
docker run -d -p 8000:8000 -p 9000:9000 –name=portainer –restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce
and there was the exact same error message. However, I tried to run it nevertheless and it worked. So it might well be that it would have worked yesterday as well but I simply gave up after the error…
After running this:
docker run -d -p 9000:9000 -v
I get this as response:
flag needs an argument: ‘v’ in -v
Plese copy an use the entire row from “docker run” to “linux-arm”
well, I am not able to get Odoo docker Image on Rasperrypi, with or without portainer. there is always errores. I wonder if Rancher can handle the issue. keep in mind that install Odoo on Ubuntu without Docker works fine. I hope you can help with new experiment to be able to install odoo docker image on rasberrypi Ubuntu or maybe Rancher. Thank you
Hi Tarek. Currently Odoo doesn’t releases docker containers for ARM (you can check in OS/ARCH column from tag section in docker hub, https://hub.docker.com/_/odoo?tab=tags&page=1&ordering=last_updated). For this reason, if you want Odoo into a container you have to build it from scratch or from a ubuntu/debian base image