Installing Docker and Portainer on Raspberry Pi for a Homelab

Raspberry Pi systems are useful little machines for homelab work, especially when you want to run lightweight services without dedicating a full desktop or server to the job.

In Realm Labs, Raspberry Pi devices are used for a mixture of automation, monitoring and experimental projects. Adding Docker and Portainer makes them much more flexible, because services can be deployed, managed and rebuilt without turning the Pi into a mess of manually installed applications.

In this guide, I’ll walk through installing Docker and Portainer on a Raspberry Pi so it can be used as a lightweight container host for homelab and self-hosted services.

Why use Docker on Raspberry Pi?

Docker makes it possible to run services inside containers rather than installing everything directly onto the operating system.

That has a few clear benefits on a Raspberry Pi:

  • services stay more isolated
  • applications are easier to deploy and remove
  • rebuilds are simpler
  • updates are often easier to manage
  • multiple services can share the same device without creating as much clutter
  • configuration becomes more repeatable

For a homelab, that is useful because a Pi can quickly become overloaded with test software, scripts and old packages if everything is installed directly onto the OS.

Why add Portainer?

Docker can be managed entirely from the command line, and that is still useful to understand, but Portainer adds a much friendlier web interface on top.

With Portainer, you can:

  • view running containers
  • start and stop services
  • inspect logs
  • deploy stacks
  • manage images
  • check volumes and networks
  • connect to multiple Docker hosts

That makes it particularly useful if you are running several services and want a quick way to manage them without remembering every Docker command.

What you need

Before starting, make sure you have:

  • a Raspberry Pi with Raspberry Pi OS installed
  • network connectivity
  • an account with sudo access
  • the system fully updated
  • a static IP or reliable DHCP reservation if you plan to keep using it on the network

This guide is aimed at Raspberry Pi OS, but the same process is similar on other Debian-based systems.

Update the Raspberry Pi

Before installing anything, update the operating system.

Run:

sudo apt update && sudo apt upgrade -y

If a reboot is required afterwards, do that before continuing:

sudo reboot

Once the Pi comes back online, reconnect over SSH or continue from the local terminal.

Install Docker

The easiest way to install Docker on Raspberry Pi is using Docker’s official convenience script.

Download and run it with:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

This installs Docker Engine and its required components.

Once complete, check that Docker is installed correctly:

docker --version

You should see the installed Docker version returned.

Allow your user to run Docker

By default, Docker commands may require sudo.

To allow your normal user account to run Docker directly, add it to the docker group:

sudo usermod -aG docker $USER

Then either log out and back in, or reboot the Pi:

sudo reboot

After reconnecting, test Docker without sudo:

docker ps

If it works without permission errors, the group change has applied correctly.

Test Docker with a container

Before installing Portainer, it is worth confirming Docker can actually run a container.

A quick test is:

docker run hello-world

Docker will download the test image and display a confirmation message if everything is working properly.

Install Portainer

Portainer is deployed as a Docker container, so once Docker is running, the installation is straightforward.

First, create the Portainer data volume:

docker volume create portainer_data

Then start Portainer:

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

This launches Portainer Community Edition and sets it to restart automatically if the Pi reboots.

Access Portainer

Once the container is running, open a browser and go to:

https://YOUR-PI-IP:9443

For example:

https://192.168.68.50:9443

The first time you open Portainer, you may see a browser warning because it uses a self-signed certificate by default. That is normal for a local install.

Create the initial admin account and then continue into the dashboard.

For a Raspberry Pi running local Docker only, select the local Docker environment when prompted.

What Portainer gives you

Once logged in, you can manage the Pi through a much cleaner interface.

You should be able to:

  • see the Portainer container itself
  • deploy new containers
  • create Docker Compose stacks
  • browse images
  • manage networks
  • view persistent volumes
  • check logs and container health

This is where Docker on Raspberry Pi starts to become genuinely useful for a homelab rather than just a one-off installation exercise.

Useful first containers

Once Docker and Portainer are installed, there are lots of services that can run happily on a Raspberry Pi depending on the model and available resources.

Common examples include:

  • Pi-hole
  • Uptime Kuma
  • Homepage
  • MQTT brokers such as Mosquitto
  • lightweight web applications
  • Node-RED
  • small dashboards
  • custom scripts wrapped as containers

That said, it is worth being realistic about the Pi’s limits. A Raspberry Pi is ideal for lightweight and low-power workloads, but it is not the right host for everything.

Using Docker Compose stacks in Portainer

One of the most useful ways to deploy services in Portainer is through stacks.

A stack lets you define a service in a Compose file rather than launching it manually with a long docker run command.

For example, Portainer itself could be represented like this:

version: "3.8"

services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: always
    ports:
      - "8000:8000"
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:

Using stacks makes services easier to document, recreate and move to another system later.

Keeping data persistent

One of the key things to remember with containers is that the container itself is not where your important long-term data should live.

Where possible, use:

  • Docker volumes
  • mapped folders
  • backup locations on NAS or shared storage

That way, if a container is deleted or rebuilt, the important application data is still preserved.

This matters even more in a homelab where you may be testing and changing things regularly.

Backups and recovery

Running containers on a Raspberry Pi is convenient, but it is still worth thinking about recovery.

At minimum, I would recommend keeping:

  • a backup of the Raspberry Pi itself
  • copies of your Compose files
  • backups of important container volumes or mapped data
  • a note of which services are running and why

A container host is easy to rebuild if the deployment is documented well. It becomes much harder if everything only exists as a memory or a few manually typed commands.

Monitoring resource usage

Docker itself does not make the Pi infinitely powerful, so keep an eye on system resources.

You can check usage from the command line with:

docker stats

Or use Portainer’s interface to get a quick view of running containers and their health.

If the Pi is also doing other jobs such as GPIO control, MQTT publishing or automation, you do not want containers consuming all available CPU or memory.

Security notes

For internal homelab use, the default setup is often enough to get started, but there are still a few good habits worth following:

  • keep Raspberry Pi OS updated
  • keep Docker and Portainer updated
  • do not expose Portainer directly to the internet without proper protection
  • use strong credentials
  • avoid running unnecessary containers
  • document what is deployed

If remote access is required, use a safer method such as a VPN or a properly secured reverse proxy rather than simply forwarding Portainer to the public internet.

Why this setup works well in a homelab

A Raspberry Pi with Docker and Portainer sits in a useful middle ground.

It is more structured than manually installing everything directly on the Pi, but it is still lightweight, low power and inexpensive to run.

For Realm Labs, that makes it ideal for experimentation, small self-hosted services and utility workloads that do not justify using a bigger virtual machine or server.

It also helps standardise the way services are deployed. Once you are comfortable with Docker and Portainer on a Pi, the same ideas carry across to larger Linux hosts and other homelab platforms.

Final thoughts

Installing Docker and Portainer on Raspberry Pi is one of the most useful upgrades you can make if the device is going to do more than a single dedicated job.

It turns the Pi into a more flexible service host, makes applications easier to manage and reduces the pain of rebuilding or changing things later.

For a homelab, that is exactly the sort of setup that pays off over time.

The Raspberry Pi remains small and efficient, while Docker and Portainer provide a far more capable platform for running self-hosted tools and lightweight services.