Managing Docker Containers on a Raspberry Pi with Portainer: A Web UI for Your Home Lab

Once you're running more than two or three containers on a Raspberry Pi, whether that's OctoPrint, Pi-hole, a few self-hosted apps covered elsewhere on this site, or your own experiments, SSH and raw docker commands stop being the fastest way to manage them. Portainer puts a proper web UI in front of your Docker install: start, stop, and inspect containers, deploy multi-container stacks from a Compose file, browse volumes and networks, and watch logs, all from a browser instead of a terminal. This guide covers installing Portainer on a Pi and the day-to-day workflow once it's running.

Why Portainer Instead of Just the CLI

• One screen for everything: containers, images, volumes, and networks across your whole Pi in one dashboard, instead of chaining docker ps, docker inspect, and docker logs commands.
• Stacks: paste a docker-compose.yml (or point at a Git repo) and Portainer deploys the whole stack, then lets you redeploy or tear it down as a unit.
• Remote access without extra SSH tunnels: once it's running, you can manage the Pi's containers from your phone or laptop on the same network without opening a terminal.
• A safety net for less command-line-comfortable household members: if someone else in the house needs to restart a service, a web UI is a lot more forgiving than a Linux shell.

Installing Portainer

This assumes Docker is already installed on your Pi (Raspberry Pi OS 64-bit, via the official get.docker.com script). Create a persistent volume and run the container:

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

The portainer_data volume keeps your configuration across container restarts and updates. Port 9443 serves the HTTPS web UI; port 8000 is only needed if you plan to use Portainer's Edge Agent to manage additional remote Docker hosts from this instance, and can be dropped from a single-Pi setup if you'd rather not expose it.

First Login

1. Browse to https://<your-pi-ip>:9443. Your browser will warn about the self-signed certificate; that's expected for a LAN-only service, and you can safely proceed past it on a trusted home network.
2. Set the initial admin username and password on first load. Do this promptly; Portainer's setup window has a short timeout, and leaving it unconfigured on a network-reachable Pi is a real (if small) attack surface.
3. Choose "Get Started" to connect to the local Docker environment that's already mounted via the socket volume.

Day-to-Day: Containers, Stacks, and Volumes

SectionWhat you'll use it for ContainersStart/stop/restart individual services, view live logs, open a web console into a running container for quick debugging StacksDeploy a full Compose file (for example, the Audiobookshelf or BookStack setups covered elsewhere on this site) as a named unit you can redeploy or remove in one action ImagesSee what's actually pulled and taking up space, and prune unused images after you've cleaned up test containers VolumesConfirm which named volumes back which containers before you delete anything, so you don't lose data mounted in a volume you thought was disposable

A Practical Workflow

A common pattern once Portainer is running: keep your actual Compose files in a Git repo (see our guide on version-controlling CAD/CAM/G-code files with Git for the same discipline applied to shop files), and use Portainer's Stacks feature with the Git-repo option so a stack redeploys from source control rather than from whatever got pasted into the UI last. That keeps Portainer as the operational dashboard while your repo stays the source of truth.

Security Notes

Portainer has full control over your Docker socket, which means full control over the host if misused; treat its admin credentials with the same care as root on the Pi itself. Don't port-forward 9443 to the public internet without a VPN (Tailscale and WireGuard are both covered elsewhere on this site) in front of it, and if you're running Portainer on the same Pi as other self-hosted services, consider the VLAN segmentation approach from our maker-shop networking guide to keep it off a network segment shared with cameras or other IoT devices.