Beginner Docker Stack on Raspberry Pi 5 with Portainer

So you grabbed a Raspberry Pi 5, you’re hearing people talk about Docker, and someone on Reddit said, “Just install Portainer, it’s easy.” And now you’re here, wondering why your tiny computer sounds like it’s about to launch a satellite. Here’s the deal: the Pi 5 isn’t just a toy anymore. With its ARM64 architecture, extra RAM, and faster storage options, it can absolutely run a basic Docker stack. If you’ve never touched a container image, don’t know what headless setup means, and think YAML might be a sandwich ingredient, you’re in the right place. This guide sticks to the basics, skips the fluff, and helps you install a real home server stack with SSH access, static IP config, and useful tools like Portainer CE for managing your containers like a pro, even if you still call the terminal “the black box.”

Key Takeaways

Docker runs well on the Raspberry Pi 5 with ARM64-compatible containers
Raspberry Pi OS Lite (64-bit) is the ideal operating system for headless setups
Portainer makes container management easier for beginners with a clean web interface
Docker Compose simplifies managing multiple containers and persistent configurations
Use USB SSDs instead of SD cards for reliability and longer lifespan
Assign a static IP to avoid network connection issues after reboots
Monitor system resources to prevent overheating or performance drops
Automate container updates with Watchtower and backups with cron and rsync
Most beginner errors stem from permissions, image architecture mismatches, or YAML formatting
With a working stack, you can easily expand to run smart home tools, media servers, and dashboards

Getting the Raspberry Pi 5 Ready

Hardware Setup

You don’t need a tech shrine to get this thing running, but you do need a few essentials. The Raspberry Pi 5 needs a 27W USB-C power supply, a decent microSD card (think Samsung EVO Plus 64GB or bigger), or better yet, a USB SSD if you’re serious about speed and data retention. Keep the CPU temperature in check with a basic heatsink or fan shim, these boards can get hotter than your uncle at a barbecue when Docker starts spinning containers. Cases like the FLIRC Pi 5 case or Argon ONE give you passive or active cooling plus bonus ports.

Installing the OS

Use Raspberry Pi Imager from your desktop. Pick Raspberry Pi OS Lite (64-bit), no GUI, less bloat. Enable SSH during setup, add your Wi-Fi credentials (if you’re not on Ethernet), and flash the card. Once the OS boots, you’ll connect remotely via SSH. No keyboard, no screen. This is a headless setup, because obviously, your Pi doesn’t need a monitor to run containers.

Initial Configuration

Connect to the Pi using a terminal command like ssh pi@raspberrypi.local. First order of business: change the default password, because everyone and their dog knows “raspberry”. Then, run:

sudo apt update && sudo apt full-upgrade -y

Set a static IP either in your router or by editing /etc/dhcpcd.conf so your Pi doesn’t play hide-and-seek on your network. You can also set up SSH keys for secure access instead of typing your password every time. It’s 2025, treat yourself.

Installing Docker on Raspberry Pi 5

ARM64 and Docker Compatibility

Here’s something you might not know: Docker works just fine on ARM64, which is what the Pi 5 uses. But not all container images are built for ARM. If you try to run something built only for x86, your Pi will stare at you blankly and do nothing. Always double-check the image architecture before pulling. Look for tags like arm64 or linux/arm64 when you’re browsing Docker Hub. Saves a lot of head-scratching.

Installation Steps

There are a hundred ways to install Docker, but the official script is the lazy and effective way. On your Pi, run:

curl -sSL https://get.docker.com | sh

After installation, add your user to the docker group so you don’t need sudo every time:

sudo usermod -aG docker $USER

Log out and back in, or reboot. Also enable Docker to start at boot:

sudo systemctl enable docker

Verifying Installation

To make sure everything actually installed correctly, run:

docker --version

Then do a quick test:

docker run hello-world

If you get a friendly welcome message and not a cryptic error about permissions or networks, you’re good.

Setting Up Portainer for Visual Management

Installing Portainer

Docker is great, but let’s be honest, not everyone loves the command line. That’s where Portainer comes in. It gives you a web-based interface to manage your containers, images, volumes, and networks. First, create a volume to hold Portainer’s persistent data:

docker volume create portainer_data

Then pull the Portainer CE image and run the container:

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

Accessing Portainer UI

Once that container is running, fire up a browser on your laptop and go to:

https://[your.pi.ip]:9443

You’ll get a self-signed certificate warning (because it’s using HTTPS out of the box). Accept it, and you’ll land on the setup screen. Create an admin user and password. No email required. No ads. Just good clean container control.

Adding Your Docker Environment

When it asks what environment you want to manage, select the local Docker engine. Boom, your Pi is now a mini container server with a nice control panel. From here, you can browse running containers, see logs, and even deploy stacks using a web form.

Running Your First Docker Stack

Installing Docker Compose

Most real-world setups use more than one container. Docker Compose makes it easier to manage multiple containers that work together, like a web server, a database, and a dashboard. Install the Compose plugin using:

sudo apt install docker-compose-plugin

You’ll now be able to use the docker compose command instead of the older docker-compose.

Creating a Compose File

Create a new folder to store your project, then add a docker-compose.yml file. Here’s a simple one that spins up Pi-hole (a network-wide ad blocker):

version: '3'

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    environment:
      TZ: 'America/New_York'
      WEBPASSWORD: 'changeme'
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80"
    restart: unless-stopped

Run it using:

docker compose up -d

Other Beginner Stack Ideas

You don’t have to stop at Pi-hole. Here are a few popular options that run well on the Pi 5:

Nginx (reverse proxy or static file server)
Watchtower (automatic container updates)
Home Assistant (if you’re into smart homes)
Node-RED (visual automation tool)
Grafana (for dashboards and system monitoring)

Networking and System Optimization

Network Configuration

Let’s not pretend your Pi is running in a datacenter, it’s probably tucked behind a couch or sitting next to your router. Still, some networking basics go a long way. Assign your Pi a static IP in your router’s DHCP settings so your browser isn’t hunting for it every time you reboot. If you’re forwarding ports from your router, stick with non-defaults to avoid conflicts. Keep common ports like 80, 443, and 22 clean unless you’re using them for something specific.

You can also tweak your firewall rules with ufw if you want a bit more peace of mind. Portainer, by default, listens on 9443, so you don’t need to mess with certs or proxies right away.

Monitoring System Resources

Running containers on the Pi is cool, until something chokes. Keep an eye on CPU, memory, and temperature. Use commands like htop to see system load, and docker stats to monitor container performance. If things start crawling, you’re either running too much or your containers need fine-tuning. For temperatures, try:

vcgencmd measure_temp

If the CPU is cooking over 80°C, it’s time for better cooling or fewer containers. Probably both.

Storage and Volumes

Docker writes a lot of stuff. Logs, volumes, containers, all of it takes up space. If you’re still on a microSD card, you’re living dangerously. Those things wear out fast. Use a USB SSD and mount it properly using /etc/fstab or bind it directly into your Compose files. You can create named volumes for things like databases, so they don’t vanish when containers restart.

Common Errors and How to Avoid Them

YAML Formatting

If Docker Compose ever yells at you about “unexpected character” or “mapping values,” congratulations, you’ve just joined the club of people who forgot YAML hates tabs. Always use spaces, usually two or four per level. And yes, indentation matters more here than it did in high school English class.

Architecture Mismatches

Not all images are created equal. If you try to run an x86-only image on your ARM64 Pi, you’ll see errors like “exec format error.” That’s your Pi telling you, “I don’t speak that language.” Always look for ARM64-compatible images.

Permission Errors

Running into “permission denied” while mounting a volume? It’s probably because Docker runs as root inside the container, but your Pi user owns the files. Fix it by using UID and GID environment variables in your Compose file.

Storage Issues

Check your available disk space. Run:

df -h

And don’t ignore warnings like “no space left on device”. Prune old containers and volumes with:

docker system prune -a

Automating Updates and Maintenance

Using Watchtower

Watchtower runs as a container and checks for updates to your other containers. When it finds a newer image, it pulls it and restarts the container automatically:

docker run -d \
  --name watchtower \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower

Backup Strategies

Use rsync to copy Docker volumes to another drive:

rsync -a /var/lib/docker/volumes/ /mnt/backup/docker_volumes/

Set up a cron job to automate this.

Update Docker and Portainer

Update Docker:

sudo apt update && sudo apt install docker-ce docker-ce-cli

Update Portainer:

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

Final Thoughts and Next Steps

So now your Raspberry Pi 5 isn’t just blinking aimlessly on a shelf, it’s running Docker, managing containers through Portainer, and updating itself while you sleep. You’ve got a working beginner stack, complete with a static IP, persistent storage, and automated updates.

If you’re feeling confident, here are a few ideas to level up:

Add a reverse proxy like Nginx or Traefik
Deploy complex stacks like Nextcloud, Jellyfin, or Uptime Kuma
Use GitHub to version-control your compose files
Create a private container registry
Explore Docker Swarm for clustered deployments

You’ve got the base system working. Now it’s just a matter of stacking more containers on top until your Pi starts filing union paperwork.

Frequently Asked Questions (FAQ)

Can the Raspberry Pi 5 handle multiple Docker containers at once?
Yes. The Pi 5 has enough CPU and RAM to run several lightweight containers at once, especially if you use a USB SSD for storage.

Do I need to use Portainer, or can I manage Docker without it?
Portainer is optional. It’s a helpful visual interface for beginners, but everything it does can be done from the command line.

Is Docker Compose required?
Not strictly, but it’s highly recommended if you’re running more than one container. It simplifies deployment, especially when using YAML stack files.

How do I make sure containers restart if the Pi reboots?
Use the --restart unless-stopped flag when starting containers or include it in your docker-compose.yml.

What if I install an x86 image by mistake?
It won’t run. You’ll likely see an “exec format error.” Always use images compatible with ARM64.

Can I install Docker on Raspberry Pi OS with a GUI?
Yes, but the Lite version is better suited for performance. You don’t need a desktop environment to run containers.

Will Docker wear out my SD card quickly?
Yes, if you write to it frequently. Use a USB SSD or set up log rotation and external volume mounts.

Do I need to open any ports on my router?
Only if you want to access services externally (from outside your home network). For local use, nothing needs to be forwarded.

Is Watchtower safe to use?
Generally, yes — but it will auto-update your containers. If you need strict version control, use manual updates or pin your image tags.

What is the easiest way to back up my stack?
Back up your volumes and Compose files. Use rsync, cron jobs, or scripts to automate regular backups to another drive.