Run Docker Containers on Raspberry Pi
Running Docker containers on a Raspberry Pi allows you to transform a compact, low-power credit-card-sized computer into a versatile home server or development environment. By leveraging containerization, you can deploy self-hosted applications, databases, and microservices efficiently without worrying about conflicting software dependencies. This guide walks you through the step-by-step process of preparing your Raspberry Pi, installing the Docker engine, managing containers, and implementing best practices for ARM-based architectures.
Prerequisites and System Preparation
Before installing Docker, ensure your Raspberry Pi is set up correctly and running a supported operating system.
- Hardware: A Raspberry Pi 3, 4, or 5 is highly recommended due to better CPU and RAM specifications.
- Operating System: Raspberry Pi OS (64-bit is preferred for optimal container compatibility).
- Access: A terminal session via SSH or direct desktop access with sudo privileges.
To start, open your terminal and update your system packages to ensure you have the latest security patches and software repositories.
sudo apt update && sudo apt upgrade -yInstalling Docker on the Raspberry Pi
The most reliable way to install Docker on Raspberry Pi OS is by using the official convenience script provided by Docker. This script automates the repository setup and installation process.
Step 1: Download and Run the Script
Execute the following command to download and run the installation script:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.shStep 2: Manage Docker as a Non-Root User
By default, running Docker commands requires sudo
privileges. To avoid typing sudo before every Docker
command, add your current user (typically pi or your custom
username) to the Docker group.
sudo usermod -aG docker $USERLog out and log back in, or run the following command to apply the group changes immediately:
newgrp dockerVerifying the Installation
To confirm that Docker is installed correctly and running on your system, execute the standard hello-world container.
docker run hello-worldIf successful, Docker will download a test image, run it inside a container, print a confirmation message, and then exit.
Installing Docker Compose
Docker Compose is an essential tool for defining and running multi-container applications using a single YAML file. On modern Docker installations, Compose is included as a plugin.
Verify that Docker Compose is available by checking its version:
docker compose versionIf it is not installed, you can add it using the package manager:
sudo apt install docker-compose-plugin -yFinding and Running Pi-Compatible Containers
Because the Raspberry Pi uses an ARM processor architecture (ARMv7 or ARM64), it cannot run containers compiled exclusively for x86/AMD64 desktop architectures.
When searching for images on Docker Hub, always look for the ARM or ARM64 tags under the OS/Arch section. Most popular official images (such as Nginx, Python, and Node) are multi-architecture and will automatically download the correct version for your Raspberry Pi.
Example: Running an Nginx Web Server
To deploy a quick web server container, run the following command:
docker run -d -p 8080:80 --name my-web-server nginx-druns the container in detached mode (in the background).-p 8080:80maps port 8080 of your Raspberry Pi to port 80 inside the container.--nameassigns a friendly name to the container.
You can now access the web server by navigating to
http://<your-raspberry-pi-ip>:8080 in any web browser
on your local network.
Basic Container Management Commands
Managing your Docker environment involves a few core commands to monitor resources and control container states.
- List running containers:
docker ps - List all containers (including stopped ones):
docker ps -a - Stop a running container:
docker stop <container_name> - Start a stopped container:
docker start <container_name> - Remove a container:
docker rm <container_name> - View container logs:
docker logs <container_name>