Deploy Portainer on Raspberry Pi: Visual Docker Container Management

Docker containers have fundamentally transformed self-hosting on Raspberry Pi. Instead of wrestling with conflicting system dependencies, compiling libraries from source, and scattering configuration files across /etc, Docker packages entire applications into isolated, disposable units. However, managing dozens of containers exclusively through terminal commands (docker ps, docker logs, docker exec) can quickly become cumbersome, especially when diagnosing service crashes or managing multi-container stacks on mobile devices.

Portainer Community Edition (CE) is the premier open-source container management GUI. It delivers a rich, intuitive web dashboard that gives you complete visual control over your Docker environment on Raspberry Pi. With Portainer, you can inspect real-time container CPU and memory charts, view streaming container logs, launch interactive web consoles, deploy multi-container Docker Compose stacks, and clean up dangling images with a single click.

This guide walks you through installing Docker Engine on Raspberry Pi OS, deploying Portainer CE with persistent volumes, securing initial administrative credentials, managing container lifecycles, deploying stacks, and monitoring your Docker host with Open Pi.

Hardware planning and prerequisites

• Supported Boards: Portainer is remarkably lightweight, requiring less than 50 MB of RAM. It runs smoothly on a Raspberry Pi 3, 4, 5, or Zero 2 W.
• Operating System: A clean 64-bit installation of Raspberry Pi OS (Bookworm) or Debian.
• Wired Network: A wired gigabit Ethernet connection ensures rapid image downloads from Docker Hub and GitHub Container Registry (GHCR).
• Storage: Use an A2-rated high-endurance microSD card or an external USB 3.0 SSD. Storing Docker image layers and container volumes on fast storage dramatically accelerates container startup times.

Step 1: Install Docker Engine on Raspberry Pi OS

If you have not already installed Docker, use the official Docker automated installation script:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Configure non-root Docker privileges

By default, Docker commands require sudo. Add your default user to the docker group to execute commands cleanly:

sudo usermod -aG docker "$USER"
newgrp docker

Verify that the Docker engine and Compose plugin are running:

docker version
docker compose version

Step 2: Deploy Portainer Community Edition

Portainer runs as a lightweight Docker container that communicates directly with the Docker daemon via the local Unix socket (/var/run/docker.sock).

Create a persistent Docker volume to store Portainer's database, user accounts, and environment configurations:

docker volume create portainer_data

Launch the Portainer Community Edition container:

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

Portainer exposes two ports: - Port 9443 (HTTPS): The encrypted web user interface equipped with a self-signed SSL certificate. - Port 8000 (TCP): An optional Edge Agent tunnel port used when connecting remote Docker nodes.

Inspect the startup logs:

docker logs -f portainer

Step 3: Secure initial administrator credentials

Open your web browser and navigate to:

https://<YOUR_PI_IP>:9443

Because Portainer uses a self-signed SSL certificate out of the box, your browser will display a security warning. Click Advanced -> Proceed to site.

Security Timeout Notice: For security, Portainer requires you to set your initial administrator password within 5 minutes of container creation. If the timeout expires before you create an account, restart the container:

docker restart portainer

Enter a strong administrator username and password (at least 12 characters). Click Create user.

On the next screen, select Get Started to connect Portainer directly to your local Raspberry Pi Docker environment.

Visual container management and diagnostics

Once logged in, click Live environment -> local to access your dashboard:

1. Inspecting real-time container metrics

Click Containers in the left sidebar to see all running, stopped, and unhealthy services. Click the Stats icon (bar chart) next to any container to view live streaming graphs of CPU utilization, RAM consumption, and network I/O. This immediately reveals which container is consuming excessive processor cycles.

2. Live streaming logs and search

Troubleshooting a failing container is effortless. Click the Logs icon next to any container. Portainer streams stdout and stderr logs in real time, with options to search log lines, display timestamps, and auto-scroll as new events occur.

3. Interactive in-browser console

Need to run a shell command inside a container without opening an SSH terminal? Click the Console icon (>_), select /bin/sh or /bin/bash, and click Connect. Portainer opens a full terminal session directly inside the container namespace.

Deploying multi-container Stacks

Portainer brings the full power of Docker Compose into a visual web editor:

1. Click Stacks -> Add stack in the left menu.
2. Name your stack (e.g., monitoring).
3. In the Web editor, paste your standard compose.yaml configuration.
4. Click Deploy the stack.

Portainer pulls the required images, creates isolated container networks, mounts volumes, and brings up the services in sequence. You can edit stack variables and redeploy updates directly from the browser at any time.

Pruning dangling images and reclaiming disk space

As you update Docker containers, old container layers and unused image builds remain on disk, consuming valuable storage.

In Portainer: 1. Navigate to Images. 2. Click Prune. 3. Portainer safely removes all unused and untagged images, freeing up gigabytes of disk space without touching active services.

Monitor your Docker host with Open Pi

Portainer manages containers, while Open Pi monitors the physical hardware host that keeps those containers running.

With the Open Pi mobile app on iOS and Android: - Host Resource Tracking: Monitor physical Raspberry Pi CPU core temperatures, load averages, and swap memory to ensure the Docker daemon has adequate system headroom. - Container Overview: Inspect container status, restart logs, and memory allocation straight from your phone. - Port Security: Verify that exposed container ports match your expected local network configuration.

Troubleshooting Portainer

• Cannot Access Web Interface at Port 9443: Ensure you are using https:// and not http://. Portainer defaults to strict HTTPS.
• Permission Denied on /var/run/docker.sock: Verify that the volume mount -v /var/run/docker.sock:/var/run/docker.sock is present in your run command and that your user belongs to the docker group.
• Container Keeps Restarting: Check container logs using docker logs portainer to identify port conflicts (e.g., another service already binding port 9443).

Sources and further reading

• Portainer: Official Documentation and Architecture
• Portainer CE: GitHub Repository and Release Notes
• Docker: Official Linux Installation Guide

Monitor your Raspberry Pi from your phone

Check real-time CPU, RAM, temperature, and service health for your home server projects with Open Pi for iOS and Android. Local-first, private, and no cloud account required.

Explore Open Pi ↗App StoreGoogle Play