Installing Portainer to the Raspberry Pi

In this guide, we will show you how to install Portainer to your Raspberry Pi.

Raspberry Pi Portainer

Portainer is a lightweight and open-source container management tool.

Using this tool, you can create, manage and delete your Docker containers running on your Raspberry Pi with ease.

Not only is the software straightforward to use, but it is also dead easy to install as it runs entirely within a Docker container.

As Portainer is built to have relatively low overhead, there isn’t much of a performance impact to using the software.

It is a perfect way of managing your docker containers without having to fiddle around with the command line.

Equipment

You can use our list of parts below to see what we used when setting up Portainer on our Raspberry Pi.

Recommended

Optional

This tutorial on setting up Portainer was tested on the Raspberry Pi 400 running on the latest available release of Raspberry Pi OS Buster.

There project can be done on a headless Raspberry Pi. This means that you can do all of the following steps by using a SSH connection to your Raspberry Pi.

Preparing your Raspberry Pi for Portainer

There are a few tasks we need to complete to prepare your Raspberry Pi to run Portainer.

While the software is straightforward to get up and running, you just can’t run it on a brand new clean installation.

1. Your first task is to install Docker to your Raspberry Pi.

Our guide shows you how to install Docker and how to configure it correctly for the Raspberry Pi.

Once you have Docker installed, you can safely continue to the next step.

2. If you already have Docker installed, let us make sure our Pi is entirely up to date.

You can run the following two commands on your device to update both the package list and the packages themselves.

sudo apt update
sudo apt upgrade

Once the upgrade completes, we can move on to getting Portainer to run on the Raspberry Pi.

Installing Portainer on to the Raspberry Pi

Now that we have prepared our Raspberry Pi, we can finally install the Portainer software.

Luckily for us, this is a very simple process as Portainer runs within a Docker container.

1. With Docker set up and configured, we can use it to install Portainer to our Raspberry Pi.

As Portainer is available as a Docker container on the official Docker hub, we can pull the latest version using the following command.

sudo docker pull portainer/portainer-ce:latest

This command will download the docker image to your device, which will allow us to run it.

Using “:latest” at the end of the pull request, we explicitly ask for it to download the latest version of the container.

2. Once Docker finishes downloading the Portainer image to your Raspberry Pi, we can now run it.

Telling Docker to run this container requires us to pass in a few extra parameters.

In the terminal on your Pi, run the following command to start up Portainer.

sudo docker run -d -p 9000:9000 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest

A few of the big things we do here is first define the ports we want Portainer to have access to. In our case, this will be port 9000.

We assign this docker container the name “portainer” so we can quickly identify it if we ever needed.

Additionally, we also tell the Docker manager that we want it to restart this Docker if it is ever unintentionally offline.

Using Portainer’s Web User Interface

This section will show you how you can access the Portainer web interface that is running on your Raspberry Pi.

We will also show you how to complete the initial setup experience of the software.

Accessing the Web Interface

Before we can do anything with the software, you will need to connect to its web interface.

To do this, you will need a web browser of your choice and know your Raspberry Pi’s IP address.

1. If you don’t know your Raspberry Pi’s local IP address, it is relatively straightforward to retrieve it.

By using the hostname command, we can have it print out the local IP assigned to our Pi.

hostname -I

Make sure to use a capital I when using this command.

2. Now, all you need to do to access Portainer is to go to the following in your browser.

You can see that in this address, we have referenced the port “:9000” at the end. This is the port that Portainer makes itself available at.

http://[PIIPADDRESS]:9000

Make sure that you replace “[PIIPADDRESS]” with the local IP of your Raspberry Pi. You should have retrieved this IP in the previous step.

Configuring Portainer on your Raspberry Pi

When you first connect to the Portainer web interface, you will need to do some initial setup steps.

Don’t worry, as these are incredibly straightforward to follow and helps ensure it will run as we want it to.

1. Upon first launching Portainer’s web interface, you will need to create an admin account.

To create this admin account, you need to give it a username (1.).

Next, you will need to assign this new account a password (2.). Portainer requires you to have passwords that are at least 12 characters long.

Once you have set the username and password you want, click the “Create user” button to finalize its creation.

Creating an administrator user

2. We now need to select what sort of container environment we want Portainer to manage.

In our case, we need to select the Docker option (1.).

Once you have this option selected, click the Connect button (2.).

Choose Portainer Docker Environment

3. You should now successfully have Portainer up and running on your Raspberry Pi.

You can now use it to manage the Docker containers running on your device.

Raspberry Pi Portainer Web UI Opened

Basic Usage of the Portainer UI

This section will show the basics of using the Portainer UI to create a new Docker container.

By following these steps, Portainer will download the container image to your Raspberry Pi and set it up.

1. When you access the Portainer interface, you should see a screen like below.

You can see that our Raspberry Pi Docker installation is listed as a Portainer endpoint. Click this endpoint to open its settings.

Open Docker Endpoint

2. Here, you will see a quick overview of Docker running on your system.

This screen will list the number of containers, volumes, images, and networks on your system.

To see what containers are running on your Raspberry Pi, click the “Containers” option in the sidebar.

Change to Containers Tab

3. Portainer will now be presented with a list of containers currently set up on your device (1.).

When you select a container, you will be able to control it by choosing whether you want to start, stop, kill the container (2.).

If you want to add a brand new container, you can click the “Add container” button (3.).

Container List Overview

3. Finally, this screen is the one that will let you create new containers within Portainer.

Using this option, you can choose a variety of settings.

First, you must define the name that you want to give this container (1.).

Then you must select the image that you want Portainer to pull to your Raspberry Pi (2.).

It is even possible to set up the network ports you want your Docker container to use (3.).

Additionally, you can also control who can manage this container within the Portainer web interface (4.).

Finally, there is a variety of advanced options that you can set using the box at the bottom of the page (5.). The one you will likely configure the most is the “Restart Policy“.

Using this, you can ensure that your docker container is automatically restarted when your Raspberry Pi reboots.

Once you are happy with all of your new Docker container settings, you can click the “Deploy the container” button (6.)

Create New Containers in Portainer For Raspberry Pi

Conclusion

At this point, you should now have successfully gotten Portainer up and running on your Raspberry Pi.

Portainer is a nifty piece of software that allows you to manage your Docker containers easily.

Using the web interface, you can create, edit and delete your containers.

If you have any issues with getting Portainer to run on your Raspberry Pi, please leave a comment below.

You should also check out our other Raspberry Pi projects to see how else you can put your Pi to use.

9 Comments

  1. Avatar for bongo fury
    bongo fury on

    Hi Emmet! Thanks again for another phenomenally great and straightforward tutorial. Tiny buglet: the installation command line in section 1 was updated to use :latest, but the text below still refers to :linux-arm, which was slightly confusing until I saw Andrea’s comment above.

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Bongo fury,

      Thank you very much for pointing out that mistake, in my rush to update the tutorial originally I had completely skimmed over that line.

      I have now corrected it so it also references “:latest” and refers to it downloading the latest version of the container.

      Cheers,
      Emmet

  2. Avatar for Ben
    Ben on

    Thanks for the write-up. Always appreciate the helpful walk-throughs. As an FYI, for my install (in June 2022) with the latest image, portainer asks for 12-character passwords, not 8.

  3. Avatar for Monte
    Monte on

    Just tried this on a RPi 4B+ 4GB, running Ubuntu 20.04.3 LTS.

    me@rahvin:~$ sudo docker pull portainer/portainer-ce:linux-arm
    linux-arm: Pulling from portainer/portainer-ce
    no matching manifest for linux/arm64/v8 in the manifest list entries
    me@rahvin:~$

    Had to change the pull command to this:

    sudo docker pull portainer/portainer-ce:latest

    as apparently that is a multi-arch package (https://github.com/portainer/portainer/issues/4465#issuecomment-727764773),

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Monte,

      Thank you for letting me know about this issue.

      I have updated the tutorial so that it now references “portainer-ce:latest” rather than picking a specific build for the architecture.

      Cheers,
      Emmet.

  4. Avatar for Andrea
    Andrea on

    Hi,
    just a note: using the tutorial on a raspberry with Ubuntu server (in my case 20.04LTS), the command at point 1 of the chapter “Installing Portainer on to the Raspberry Pi” should be changed from
    sudo docker pull portainer/portainer-ce:linux-arm
    to
    sudo docker pull portainer/portainer-ce

    Otherwise you could receive this error message:
    no matching manifest for linux/arm64/v8 in the manifest list entries

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Andrea,

      Thank you for bringing this issue to my attention.

      I have updated the tutorial to reference the multi-arch package rather than the specific one we were using previously.

      Cheers,
      Emmet

  5. Avatar for Mike Smith
    Mike Smith on

    You should have a note stating any ARM build of Portainer is restricted from using only compose version less then 3.

  6. Avatar for Raul Libório
    Raul Libório on

    Thanks for all of yours tutorials. Works a charm!

Leave a Reply

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