Deploy Portainer on Raspberry Pi: Visual Docker Container Management

Docker has become the standard way to run self-hosted applications on a Raspberry Pi. It isolates software dependencies, makes updates repeatable, and prevents conflicts between libraries. However, managing dozens of containers, images, volumes, and networks strictly through command-line flags can quickly become overwhelming.

Portainer Community Edition (CE) provides a responsive web-based management dashboard for Docker. With Portainer, you can see container resource usage in real time, inspect container logs, launch Compose stacks, and open shell consoles directly from your web browser.

Prerequisites and Docker installation

Portainer is lightweight and runs efficiently on any 64-bit Raspberry Pi model (Pi 4, Pi 5, Pi 3, or Pi Zero 2 W). You need Docker Engine installed on Raspberry Pi OS.

If Docker is not already installed on your system:

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

Log out and back in to apply the group permissions, then verify the Docker daemon is active:

docker version

Create persistent storage and launch Portainer

Portainer stores its internal configuration, user databases, and environment settings in a persistent Docker volume.

Create the volume and launch the official Portainer CE container:

sudo docker volume create portainer_data
sudo 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

Key configuration details: - Port 9443: The encrypted HTTPS administrative interface. Portainer automatically generates a self-signed TLS certificate. - Port 8000: Optional edge agent tunnel port for managing remote Docker instances. - /var/run/docker.sock: Mounting the host's Docker socket allows Portainer to communicate with the local Docker daemon and manage containers.

Verify that the container is running:

sudo docker ps

Complete initial setup and create your administrator account

Open your web browser and navigate to:

https://PI_ADDRESS:9443

Note: Because Portainer uses a self-signed certificate out of the box, your browser will display a certificate warning. You can safely bypass this warning on your trusted home network, or configure a valid Let's Encrypt certificate using Nginx Proxy Manager.

Security requirement: Portainer shuts down its web interface if an administrator account is not created within five minutes of startup. If this timeout expires, restart the container:

sudo docker restart portainer

Enter a username and choose a secure password (at least 12 characters). Click Create user to access the main dashboard.

Exploring the Portainer dashboard

Once logged in, select the local environment. Portainer immediately displays an overview of your Raspberry Pi Docker host: 1. Containers: View all running, stopped, and unhealthy containers. 2. Images: Review downloaded container images and clean up unused dangling layers with one click to recover SD card or SSD storage. 3. Volumes: Inspect named persistent volumes and verify disk utilization. 4. Networks: Inspect bridged networks and container IP allocations.

Clicking on any container gives you live charts showing CPU, memory, and network throughput. The Logs tab lets you stream container output with live tailing, and the Console button opens a functional bash or sh terminal inside the container without requiring SSH access.

Deploying multi-container applications with Stacks

Portainer brings the full power of Docker Compose into the browser via its Stacks feature. Rather than editing files via terminal on the Pi, you can manage Compose declarations visually:

1. Click Stacks in the left sidebar and choose Add stack.
2. Name your stack (e.g. monitoring).
3. In the web editor, paste your Compose definition (such as our Uptime Kuma guide configuration).
4. Click Deploy the stack.

Portainer pulls the necessary container images, provisions the networks and volumes, and starts the services in the proper dependency order.

Security considerations for Docker socket access

Mounting /var/run/docker.sock grants Portainer root-equivalent administrative privileges on your Raspberry Pi. Anyone with access to your Portainer web interface could potentially execute commands with host-level permissions.

To protect your system: - Never expose port 9443 directly to the open internet via router port forwarding. - Use a secure private overlay network like Tailscale when accessing Portainer outside your home. - Keep the Portainer image updated by pulling the latest release regularly:

sudo docker stop portainer
sudo docker rm portainer
sudo docker pull portainer/portainer-ce:latest

Re-running the docker run command with the existing portainer_data volume restores all your settings, stacks, and user accounts instantly.

Sources and further reading

• Portainer Official Website
• Portainer CE Installation Documentation
• Portainer Community Forum and GitHub

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