Install Portainer on Raspberry Pi for Easy Docker Control

If you’re using a Raspberry Pi to run multiple Docker containers, managing them can quickly get complicated. That’s where Portainer comes in! It allows you to organize and control your containers from a graphical web interface, simplifying the process.

Portainer can be installed on a Raspberry Pi as a simple Docker container. Once started, the web interface is directly accessible for managing all other Docker containers on the system.

This might feel too technical if you are just getting started with the Pi. But don’t worry — I will walk you through the entire process, and by the end, you will deploy your first Docker container on your Pi using Portainer!

If you’re new to Raspberry Pi or Linux, I’ve got something that can help you right away!
Download my free Linux commands cheat sheet – it’s a quick reference guide with all the essential commands you’ll need to get things done on your Raspberry Pi. Click here to get it for free!

What is Portainer and Why Use it?

Docker containers are a great way to run or test a program or an application on different systems without worrying about various dependencies (which is the software the program needs). However, if you are like me and you don’t like the CLI, it won’t be easy for you to use Docker on a Pi.

That is where Portainer helps: it provides a sleek user interface that can help you manage the various Docker containers running on your Raspberry Pi. This includes features like access to live container logs, access to the container’s terminal, and much more!

One of the best things about this software is that it gets deployed as a very lightweight Docker container on your Pi, so you don’t need to worry about any dependencies. Now that we know what Portainer is, let’s look at what you’ll need to follow along with me in this article.

The list for this is really small, which is good! You will only need the following:

• Raspberry Pi: Of course! You will need a Raspberry Pi. I suggest using a Raspberry Pi 5 with at least 2 GB RAM, which is what I used. However, anything above a Raspberry Pi 3 will do.
• A computer with an SD card reader (can be a Raspberry Pi with Imager on it).
  If you don’t have one, you can use a cheap USB adapter (like this one on Amazon).
• Wired/Wireless Connection: In this tutorial, I will assume that you have your Pi connected to your home network through a wired Ethernet connection or Wi-Fi.
• A micro-SD card to install the latest Raspberry Pi OS on the Raspberry Pi.
  Here’s my current recommendation for the best performance, but any model will do.
• Raspberry Pi Imager: We will use it to flash the latest Raspberry Pi OS image on our SD card.

Once you have a Raspberry Pi running the latest version of Raspberry Pi OS and a way to connect to the terminal/screen (I highly recommend using Raspberry Pi Connect for this), you are ready to dive into this tutorial!

Installing Portainer on Raspberry Pi

The first thing we will need to do is install Portainer on the Pi. However, as mentioned earlier, it is a Docker container so we will first need to set up Docker on our Pi and then start Portainer as a container.

Step 1: Installing Docker on Raspberry Pi

Setting up Docker on the Raspberry Pi is quite straightforward. I have already covered how to do this in an earlier article, so start there if you don’t have it installed yet, and return when once it is.

Note: If you want to see these steps in action, I have a video lesson available just for community members. Join here to watch it directly! Becoming a member gives you access to 30+ other lessons for Raspberry Pi and comes with many other benefits.

Once you have completed the installation, you should be able to run Docker commands on your terminal.

Great, now that we have Docker installed and configured, let’s install and start Portainer on our Pi.

Step 2: Configuring Portainer

Portainer is a container manager that runs as a Docker container itself. So in this section, we’ll be creating a container configuration for Portainer. I’ll be showing you how by using Docker Compose conventions. I think it’s easier to follow and modify later as you need.

Here’s how to create the Docker configuration for Portainer:

• Create a folder to store your Portainer project.
  (I like to put this in my home directory.)
  mkdir portainer
• In that folder, create a compose.yaml file to hold our Portainer configuration:
  cd portainer
nano compose.yaml
  
  
• Paste the following lines into compose.yaml:
  (Important: the indentation matters!)

services:
  portainer:
    container_name: portainer
    image: portainer/portainer-ce:sts
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    ports:
      - 9443:9443
      - 8000:8000  # Remove if you do not intend to use Edge Agents

volumes:
  portainer_data:
    name: portainer_data

networks:
  default:
    name: portainer_network

• Finally, save & exit (CTRL+X).

Tip: Command lines can be a pain to memorize. I put the essential Linux commands on a printable cheat sheet so you don't have to keep googling them. You can grab the PDF here if you want to save some time.

You might be thinking that this Portainer configuration looks pretty complex. Don’t worry, let’s break it down to understand it better:

• image: portainer/portainer-ce:sts – this line downloads the Portainer image.
• restart:always – allows us to configure the app’s behaviour if it fails. For now, we have configured it so that Portainer always restarts on failure.
• portainer_data:/data – this folder mapping creates a folder to store application data in your Portainer directory.
• 9443:9443 – this port mapping allows Docker and our Pi to establish a network connection so we can access the Portainer UI available on port 9443.
• 8000:8000 – this port mapping is useful for remote access. If you’re only using Portainer on your local network like I am, I recommend removing this line to keep things simple.

(To learn more about what these lines do, check out our article on Docker configuration.)

You’re all done with the Portainer configuration.
Now let’s move on to launching Portainer.

Step 3: Starting Portainer

All you need is one command to launch Portainer:
docker compose up

This command tells Docker to read your compose.yaml file for instructions.
It downloads the image and starts Portainer according to the rest of your configuration.

Important! Copy the “setup-token” that appears on your screen for later.
In my example above, it’s “8403586527aa728239ce40355562f5bd58fe9a440d15df0c…”

Note: The setup-token is a security measure, like a temporary password. It will expire if you take too long to access the web interface in the next step. To get a new token, you can simply relaunch the container.

Once you get everything working later, press D to send the container to the background.
But for now, let’s see how to access the Portainer web interface to complete the initial setup.

Accessing the Portainer Web Interface

Once you have the Portainer container running, you should be able to access it within the local network on the port that we configured: 9443. Here you have two options: either access it through localhost on your Pi or any other device connected within your network (through Pi’s IP address).

• Open a browser and visit the Pi’s IP address:
  https://<RaspberryIP>:9443
  (Make sure you type https explicitly in the address bar.)
  You’ll get a privacy warning, which is normal. Click Advanced > Proceed to continue.
• If you get a timeout error, like in the image below, then go back to Step 3.
  Stop the container by pressing CTRL+C and relaunch the container with “docker compose up”.
  You’ll need to copy the setup-token again because it’s different each time.
  
  
  
• If everything was done timely, then you should get the following welcome page:
  
• Create a password and write it down, as it’s the admin credentials to access everything.
  Paste the setup token you got earlier from launching the container.
  Press Create user when you’re all done.
• This will open the Environment Wizard window, which lets you choose what environment Portainer should connect to. Let’s use the default by clicking Get Started.
  
  (Adding an environment lets you do complex things like using a Kubernetes cluster.)
• This will take you to the home screen where you can see a summary of your current Docker containers you have on your Raspberry Pi.
  
  

That completes the initial setup for Portainer.
Now, let’s see how easy it is to deploy a container using Portainer’s graphical interface.

Portainer in Action: Deploying our First Container

Now that we have everything set up, let’s deploy our first container using the Portainer’s web interface:

• Access your local environment by clicking the summary box (the only one you have).
• Click the Containers tab to open it.
  
• If this is first time, you’ll only have 1 listed here, your Portainer container.
  Click the “+ Add container” button to create a new container.
  
• Let’s deploy the “hello-world” container as a test.
  
  Give your container a Name.
  Fill in “hello-world” for the image, which will pull this specific application.
  Click Deploy the container.
  
• The deployment process will take a few seconds. We are deploying a container that runs once and then exits. So, you will see that the status of our container will be “exited – code 0”, the code that indicates success.
  
  
• You can also easily access logs for your containers.
  Just click the container name to open its details, and click the Logs button.
  
• Once you open the logs, you should see the welcome message that the container is supposed to print. This means that our deployment was successful!
  

Related:

• 11 Docker Projects Every Raspberry Pi Owner Should Try
• 7 Docker Mistakes That Will Eventually Break Your Raspberry Pi

Congratulations! You just deployed your first Docker container using Portainer. This allowed you to get familiar with its interface and recognize the true potential of this software. Moreover, this is just the beginning! You can do a lot more than this using Portainer.

I recommend starting with Portainer’s official documentation to learn more about it. That’s it for this article. See you in the next one!

Not getting the same result?

Even when you follow every step, small differences in OS version, hardware or config can change the outcome. Instead of wasting time guessing, get help from people who have already fixed the same kind of issue.

Ask your question now →

🔒 No risk. Cancel anytime.

• Get help on your exact issue
• Access step-by-step videos for tricky setups
• Browse the website without ads