Install Portainer on Raspberry Pi

Why Raspberry Pi for Portainer?

If you run Docker on one or more Raspberry Pis, Portainer gives you a visual dashboard to manage everything without SSH-ing into each one. Portainer has native ARM64 images, uses about 100 MB of RAM, and runs well on a Pi 3B+ or newer. With Portainer Agent, you can manage Docker across multiple Pis from a single UI. This guide covers the Pi-specific setup, memory considerations, and multi-node management.

Prerequisites

• Raspberry Pi 3B+, Pi 4, or Pi 5 (Pi Zero 2 W works but is tight on RAM)
• Raspberry Pi OS Lite (64-bit / ARM64)
• Docker and Docker Compose installed (guide)
• 512 MB of free RAM (Portainer + Docker overhead)
• 500 MB of free disk space
• SSH access enabled
• Docker socket access (/var/run/docker.sock)

Install Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Log out and back in, then verify:

docker run --rm hello-world
uname -m   # Should show: aarch64

Docker Compose Configuration

Create the project directory:

mkdir -p ~/portainer && cd ~/portainer

Create docker-compose.yml:

services:
  portainer:
    image: portainer/portainer-ce:2.39.1
    container_name: portainer
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer-data:/data
    ports:
      # HTTPS web UI
      - "9443:9443"
      # HTTP web UI (optional)
      - "9000:9000"
      # Edge Agent tunnel
      - "8000:8000"

volumes:
  portainer-data:

Start it:

docker compose up -d

Verify:

docker compose ps
curl -sk https://localhost:9443/api/status

First-Time Setup

1. Open https://your-pi-ip:9443 in a browser
2. Accept the self-signed certificate warning
3. Create your admin account within 5 minutes of starting the container
4. Click Get Started to connect to the local Docker environment

Your Pi’s Docker containers, images, volumes, and networks are now visible in the Portainer dashboard.

Managing Multiple Pis

The real power of Portainer on a Pi is managing a fleet of Pis from one place. Deploy the Portainer Agent on each additional Pi:

On Each Remote Pi

docker run -d \
  --name portainer-agent \
  --restart unless-stopped \
  -p 9001:9001 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  portainer/agent:2.39.1

The Agent uses about 30 MB of RAM — negligible even on a Pi Zero 2 W.

Connect from the Main Portainer Instance

1. In Portainer, go to Environments > Add environment
2. Select Docker Standalone > Agent
3. Enter the remote Pi’s IP address and port 9001
4. Name it (e.g., pi-media-server, pi-pihole)
5. Click Connect

You can now manage containers on all your Pis from the single Portainer instance. Deploy stacks, view logs, restart containers — all from one browser tab.

Portainer Edge Agent (For Remote Pis)

If your Pis are on different networks (e.g., at a different location), use the Edge Agent instead. It initiates an outbound connection to your Portainer server, so no port forwarding is needed on the remote network:

docker run -d \
  --name portainer-edge-agent \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  -v /:/host \
  -e EDGE=1 \
  -e EDGE_ID=<generated-id> \
  -e EDGE_KEY=<generated-key> \
  -e EDGE_INSECURE_POLL=1 \
  portainer/agent:2.39.1

Get the EDGE_ID and EDGE_KEY from Portainer’s Environments > Add environment > Edge Agent page.

Raspberry Pi Optimization

Memory management. Portainer uses ~100 MB of RAM. On a Pi with 1 GB (Pi 3B+), this is significant if you are running other containers. Monitor memory:

free -m
docker stats --no-stream

If you are tight on RAM, add swap:

sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Disable telemetry. Portainer collects anonymous usage data by default. Disable it under Settings > General > Enable edge compute features and uncheck analytics.

Disable HTTP. Once you confirm HTTPS works, remove the port 9000 mapping. On a home network, self-signed HTTPS is fine. For external access, put Portainer behind a reverse proxy with a real certificate.

Docker log rotation. Add to /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "5m",
    "max-file": "2"
  }
}

SD card vs SSD. Portainer’s writes are minimal (settings changes, stack deployments). An SD card is fine for Portainer data. If you run many other containers, consider moving Docker’s data root to a USB SSD.

Practical Use Cases on Pi

Deploy stacks from the UI. Instead of SSH-ing in and writing Compose files, paste your docker-compose.yml content into Portainer’s Stacks > Add Stack and deploy from the browser.

Quick container management. Restart a stuck container, check logs for an error, or pull an updated image — all without opening a terminal.

Container resource monitoring. Portainer shows real-time CPU and memory usage per container. Useful for identifying which container is eating your Pi’s limited resources.

Template deployments. Portainer’s App Templates let you deploy popular containers with one click. Not all templates have ARM64 images, but the most popular ones (Pi-hole, Nextcloud, Vaultwarden) do.

Troubleshooting

”Your Portainer instance timed out” on first access

You have 5 minutes to create the admin account after starting. If you miss the window:

docker compose restart portainer

Wrong architecture image pulled

If Docker pulls an amd64 image on your ARM Pi:

    platform: linux/arm64

Verify with: docker inspect portainer | grep Architecture

High memory usage after many containers

Portainer caches container metadata. With 20+ containers, memory usage can climb to 200 MB. This is normal. If you are on a 1 GB Pi and running out of memory, reduce the number of containers or upgrade to a Pi 4 with more RAM.

Cannot access Portainer remotely

Ensure the port is not blocked. On Raspberry Pi OS, iptables is typically open by default, but check:

sudo iptables -L -n | grep 9443

Also verify your router is not blocking the Pi’s IP on that port.

Agent connection drops between Pis

If the Portainer Agent on a remote Pi disconnects periodically, check network stability. Wired Ethernet is more reliable than WiFi for persistent connections. Also verify the remote Pi’s IP has not changed (use a static IP or DHCP reservation).

Resource Requirements

• RAM: ~100 MB for Portainer, ~30 MB per Agent on remote Pis
• CPU: Low. Brief spikes when loading the UI.
• Disk: ~200 MB for the Docker image, minimal data volume usage
• Power: Negligible addition to Pi baseline (~3W)

Related

• How to Self-Host Portainer with Docker
• Install Portainer on Ubuntu Server
• Install Portainer on Proxmox VE
• Best Self-Hosted Docker Management Tools
• Docker Compose Basics
• Reverse Proxy Explained