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 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 is my current recommendation for the best performance, but any model will do for this tutorial.
• 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: Installing and Starting Portainer

Installing Portainer is so simple. It’s just two commands that you need to execute on your terminal and that’s it! Let’s walk through the process together:

• The first step is getting the latest version of Portainer on your system. To do that with Docker, just type in the following command:
  
  docker pull portainer/portainer-ce:latest
  
  The “latest” at the end allows fetching the latest version. The output for this command will look something like this:
  
  
  
• Once the image has been downloaded, we can start Portainer with Docker. This will require a few additional configurations, which we will tell Docker through the command we use to run it. Here is the command you will need to execute in a terminal window:
  
  sudo docker run -d -p 9000:9000 --name=portainer_app --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest
  
  You might be thinking, that’s a pretty complex command. Don’t worry, let’s break it down to understand it better:
  
  – “-d” allows us to run the container in the background and prints the container id for the running application.
  – “-p 9000:9000” allows Docker and our Pi to establish a network connection so we can access the Portainer UI available on port 9000.
  – “–name” lets us name our container, which I have aptly named portainer_application.
  – “–restart” allows us to configure the app’s behaviour if it fails. For now, we have configured it so that the Docker manager always restarts the app on failure.
  – “-v” mounts a volume (i.e. a physical storage location on our Pi) to our container.
  
  That was all for the command. Running it should print a long string with random characters, which is essentially your container ID.
  
  
  
• That completes the installation for Portainer! You can verify that it is running by running the docker ps command in the terminal, which should display your portainer_application container.
  
  

Now, let’s see how to access the Portainer web interface and complete the initial setup process.

Step 3: 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: 9000. 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).

• To keep things simple, we will do everything on the Pi through localhost. For this, open a new browser window on your Pi and open the page with the URL: “http://localhost:9000“. This should open the following welcome page:
  
  
  Fill in the details and then press the Create user button. Remember this password as it is the credentials for your admin user (the user who has access to everything).
  
• This will open the Environment Wizard window, which lets you choose what environment Portainer should connect to. Here, you can either use your local Docker environment or remove Docker or Kubernetes environment.
  
  
  For now, we will manage our local Docker environment where we have deployed Portainer. For this, just click the big button highlighted in the above image.
  
• This will take you to the Portainer home screen. You should now see your local environment in the Environments tab. That completes the initial setup and first-time access to our Portainer web UI.
  
  

Now, let’s deploy our first container with Portainer.

Portainer in Action: Deploying our First Container

Now that we have Portainer set up, let’s deploy our first container, which is using the Portainer’s web interface. So, let’s walk through the process of doing just that.

• The first step is accessing our local environment’s interface. You can do that by clicking on the highlighted area in the above image.
• This will open the Docker dashboard for your local environment. You can manage almost everything in your environment through this interface. To deploy a new container, open the Containers tab by clicking the highlighted button below.
  
  
  
• This will open the Containers window for your environment, where you should see your Portainer container listed. We can create a new container from this window using the + Add container button on the top-right side of the screen.
  
  
  
• We will deploy the “hello-world” container in our Docker environment. To do this, we need to fill in some information in the “Add container” window that opens.
  
  
  The following information is required to deploy this container:
  
  – Name of the container.
  – The image of the container: “hello-world” in this case.
  – Network configuration (similar to the -p command we used to expose port 9000 for the Portainer UI).
  – Access control management. We will disable it for now.
  
  Finally, deploy this container by pressing the Deploy this container button.
  
• 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.
  
  
  
• We are interested in the logs for this container. You can easily access them through this interface as well. Just click on the container name, which should take you to a new window. There you can access the container Logs by pressing on the Logs option.
  
  
  
• Once you open the logs, you should see the welcome logs that the container is supposed to print. This means that our deployment was successful!
  
  

Related: 11 Docker Projects Every Raspberry Pi Owner Should Try

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!

Whenever you’re ready, here are other ways I can help you:

Test Your Raspberry Pi Level (Free): Not sure why everything takes so long on your Raspberry Pi? Take this free 3-minute assessment and see what’s causing the problems.

The RaspberryTips Community: Need help or want to discuss your Raspberry Pi projects with others who actually get it? Join the RaspberryTips Community and get access to private forums, exclusive lessons, and direct help (try it for just $1).

Master your Raspberry Pi in 30 days: If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.

Master Python on Raspberry Pi: Create, understand, and improve any Python script for your Raspberry Pi. Learn the essentials step-by-step without losing time understanding useless concepts.

You can also find all my recommendations for tools and hardware on this page.