Some links in this post may be affiliate links. We may get paid if you buy something or take an action after clicking one of these, but without addictional costs for you compared to direct buying.

Setup a Docker environment with Raspberry PI OS Lite and Portainer

raspberry pi docker portainer featured image

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.

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 continuing with the project or removing 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

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 docker engine installation, be sure to have an updated OS. From SSH command line, type the following commands:

sudo apt update
sudo apt upgrade

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 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 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 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 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 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: 24

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?


  1. Hello
    running “sudo 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


    1. 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

    1. Hi Tyler,
      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.

  2. 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?

    1. Hi yshariff,
      I suppose you are writing about 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 (

  3. Hi,
    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)


    1. Hi Robert,
      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.

  4. Hi,
    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!

    1. Hi,
      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…

  5. Hi,
    After running this:
    docker run -d -p 9000:9000 -v
    I get this as response:
    flag needs an argument: ‘v’ in -v

    Any idea?

  6. 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

Leave a Reply

Your email address will not be published. Required fields are marked *

I accept the Privacy Policy