Docker on Raspberry Pi turns a small, silent, low-power ARM board into a capable home server that can run dozens of applications simultaneously — each isolated in its own container, easy to update, and trivial to back up or migrate. Pi-hole for network-wide ad blocking, Nextcloud for private cloud storage, Gitea for self-hosted Git, Portainer for a web-based container dashboard, Jellyfin for media streaming — all of these run beautifully in Docker on a Raspberry Pi 5.
This guide walks through the complete Docker setup on Raspberry Pi OS (64-bit), explains the ARM architecture considerations that differ from x86 Docker, and shows you how to run real-world stacks with Docker Compose.
Why Run Docker on Raspberry Pi?
Docker solves a painful problem in self-hosting: dependency conflicts. Without containers, installing Pi-hole might break your Node.js project because they share system libraries. With Docker, each application lives in its own container with its own dependencies, completely isolated from everything else.
Other benefits for Pi users:
- Reproducibility: A
docker-compose.ymlfile captures your entire stack. Rebuilding after an SD card failure takes minutes, not hours. - Easy updates:
docker compose pull && docker compose up -dupdates all containers to the latest versions. - Resource limits: Set CPU and RAM limits per container so one misbehaving app cannot starve the others.
- Rollback: Pin containers to specific image versions (e.g.,
nextcloud:27.1.0) and roll back by changing one line. - Community images: Thousands of pre-built images support ARM64 — you rarely need to build anything yourself.
Prerequisites: Preparing Your Raspberry Pi
Before installing Docker, ensure your Pi is running a clean 64-bit OS. Docker on Raspberry Pi requires 64-bit ARM (aarch64/arm64) to access the full range of Docker Hub images. 32-bit Raspberry Pi OS works but limits you to armhf images, which are less commonly maintained.
Install 64-bit Raspberry Pi OS
Download Raspberry Pi OS Lite (64-bit) from the official site. Flash it using Raspberry Pi Imager. In the Imager’s advanced options, enable SSH, set your hostname, WiFi credentials (or use Ethernet), and create a user account before flashing.
Update the system
sudo apt update && sudo apt full-upgrade -y
sudo reboot
Boot from SSD (strongly recommended)
Docker containers generate frequent writes to storage. A microSD card will degrade quickly. Use the Raspberry Pi Imager to flash the OS to a USB SSD, then configure the Pi’s bootloader to boot from USB: sudo raspi-config → Advanced Options → Boot Order → USB Boot.
Installing Docker on Raspberry Pi
Use the official Docker convenience script — it detects your architecture and installs the correct packages automatically:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
After installation, add your user to the docker group so you can run Docker commands without sudo:
sudo usermod -aG docker $USER
newgrp docker
Verify the installation:
docker run --rm hello-world
You should see the Hello from Docker! message confirming everything works.
Install Docker Compose Plugin
Docker Compose V2 is now a Docker CLI plugin rather than a separate binary. It is included automatically by the convenience script. Verify:
docker compose version
ARM Architecture Considerations
Raspberry Pi uses ARM architecture (arm64/aarch64 on 64-bit OS), whereas most cloud servers and desktop machines use x86_64/amd64. This matters when pulling Docker images.
Modern Docker images on Docker Hub use multi-architecture manifests — when you run docker pull nginx, Docker automatically pulls the arm64 variant if one exists. Most popular images (nginx, postgres, redis, node, python, nextcloud, jellyfin, portainer, etc.) have arm64 support.
You can verify an image’s supported architectures on Docker Hub before pulling. Look for linux/arm64 in the OS/Arch column. If only linux/amd64 is listed, the image will not run natively (Docker will error or attempt emulation via QEMU, which is extremely slow).
Images that commonly lack ARM64 support: some older enterprise tools, some niche media applications. Always check before planning a stack around a specific image.
Running Your First Stack: Pi-hole + Portainer
Let us deploy a practical two-container stack: Pi-hole (network-wide DNS-based ad blocker) and Portainer (Docker web UI). Create a directory and a Compose file:
mkdir ~/docker && cd ~/docker
nano docker-compose.yml
version: '3.8'
services:
pihole:
image: pihole/pihole:latest
container_name: pihole
restart: unless-stopped
ports:
- "53:53/tcp"
- "53:53/udp"
- "8080:80/tcp"
environment:
TZ: 'Asia/Kolkata'
WEBPASSWORD: 'yourpassword'
volumes:
- ./pihole/etc-pihole:/etc/pihole
- ./pihole/etc-dnsmasq.d:/etc/dnsmasq.d
portainer:
image: portainer/portainer-ce:latest
container_name: portainer
restart: unless-stopped
ports:
- "9000:9000"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./portainer_data:/data
Start the stack:
docker compose up -d
Access Pi-hole admin at http://<pi-ip>:8080/admin and Portainer at http://<pi-ip>:9000. Configure your router to use the Pi’s IP as its primary DNS server — all devices on your network will now benefit from ad blocking without any per-device configuration.
Essential Docker Commands for Daily Management
docker compose up -d— Start all services in backgrounddocker compose down— Stop and remove containers (data volumes preserved)docker compose pull— Pull latest images for all servicesdocker compose logs -f <service>— Follow live logs for a specific containerdocker compose restart <service>— Restart a single containerdocker stats— Live CPU and RAM usage across all running containersdocker system prune -a— Remove all unused images, containers, and networks (free up disk space)docker exec -it <container> bash— Open a shell inside a running container
Popular Self-Hosted Applications for Raspberry Pi Docker
The following applications run well on Raspberry Pi with Docker and have active ARM64 image support:
- Nextcloud: Google Drive replacement. Sync files, contacts, and calendar across all your devices. Needs at least 2 GB RAM for comfortable use.
- Jellyfin: Plex alternative — streams your movie and music collection to any device. Hardware video transcoding is limited on Pi, but direct play of H.264 content is smooth.
- Gitea: Self-hosted GitHub alternative. Lightweight Git server — runs comfortably even on a Pi 3.
- Uptime Kuma: Monitors the uptime of your websites and services, sends alerts via Telegram, email, or Slack.
- Vaultwarden: Bitwarden-compatible password manager server. Lightweight Rust implementation, very low resource usage.
- Heimdall: Application dashboard — a single page with icons linking to all your self-hosted services.
- Grafana + InfluxDB: Beautiful dashboards for sensor data, server metrics, and Home Assistant history.
Monitoring and Maintenance
Long-running Docker hosts need monitoring. Install the Watchtower container to automatically pull and restart containers when new image versions are released:
docker run -d --name watchtower
-v /var/run/docker.sock:/var/run/docker.sock
containrrr/watchtower --schedule "0 0 4 * * *"
This runs Watchtower at 4 AM daily. For production services you may prefer to disable auto-update and update manually using docker compose pull && docker compose up -d during maintenance windows.
Monitor disk usage regularly with df -h and use docker system df to see how much space Docker images, containers, and volumes are consuming. On a Pi with a 256 GB SSD, running out of space takes months — but on a 32 GB SD card, old images accumulate quickly.
Frequently Asked Questions
Can Raspberry Pi 4 2GB RAM run Docker?
Yes, but with limitations. A Pi 4 with 2 GB can run Pi-hole, Portainer, and a couple of lightweight services comfortably. For Nextcloud with a database, Jellyfin, or anything involving Java (like Gitea), 4 GB is the practical minimum to avoid constant swapping. The Pi 5 is worth the extra cost for a home server role.
Does Docker work on Raspberry Pi OS 32-bit?
Docker installs on 32-bit (armhf) Pi OS, but you are limited to images that ship an armv7 or armhf variant. Many modern images are arm64-only. Strongly recommend flashing 64-bit Pi OS from the start — there is no compelling reason to use 32-bit on Pi 4/5.
How do I back up Docker container data?
Always store persistent data in Docker volumes or bind mounts (mapped to a specific directory on the host, like ./nextcloud_data:/var/www/html). Back up by copying these directories. Use rsync or a dedicated backup tool like Duplicati (also available as a Docker container). Never rely on the container’s internal writable layer for data you care about.
Can I run Kubernetes on Raspberry Pi?
Yes — K3s is a lightweight Kubernetes distribution designed for ARM. A cluster of 3–5 Raspberry Pi boards makes an excellent home Kubernetes lab. For a single Pi, however, Docker Compose is simpler and uses far less overhead than Kubernetes.
How do I expose my Docker services to the internet safely?
Use a reverse proxy like Nginx Proxy Manager (available as a Docker image) or Traefik. These handle HTTPS certificate issuance via Let’s Encrypt and route requests to the correct container by subdomain. Combine with Cloudflare Tunnel (no open ports required) for maximum security.
Conclusion
Docker transforms a Raspberry Pi into a versatile home server capable of running everything from DNS filters to cloud storage to Git repositories — all isolated, easy to manage, and reproducible. The Pi 5 with 4 GB or 16 GB RAM gives you the computational headroom to run serious workloads, while Docker Compose makes managing multi-container stacks as simple as editing a text file.
Start with Pi-hole and Portainer, get comfortable with the Compose workflow, then gradually add the applications that matter to you. Your self-hosted stack is limited only by your imagination and your Pi’s storage capacity.
Get your Raspberry Pi 5 and accessories from Zbotic.in — fast delivery across India with expert support for makers and developers.
Add comment