Docker on Raspberry Pi: Install, Configure and Deploy Your First Container

Why Docker changes how you run services on a Pi

Without Docker, installing software on a Pi involves managing conflicting dependencies, dealing with outdated packages in the default repositories, and writing custom init scripts. Docker packages each application with everything it needs inside a self-contained image. Two apps requiring different versions of Python or a database driver coexist without conflict.

Updating a Docker container takes one or two commands. Rolling back is equally straightforward. And because containers are isolated, a broken service cannot crash the rest of your system.

Requirements

A Raspberry Pi 3B+, 4, or 5 running Raspberry Pi OS 64-bit (Lite is recommended for servers). Older 32-bit images work but some Docker images are only published for ARM64.

Step 1: Install Docker

The official Docker convenience script installs the correct version and packages for your architecture:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Add your user to the docker group so you do not need sudo for every docker command:

sudo usermod -aG docker $USER
newgrp docker

Step 2: Verify the installation

Check that Docker is installed and the service is running:

docker --version
sudo systemctl status docker

Run the test container to verify end-to-end functionality:

docker run hello-world

Docker pulls the hello-world image, runs it, and prints a success message. The installation is working.

Step 3: Core Docker commands

These commands cover nearly all day-to-day use:

# Run a container in the background, name it, map port 8080 to internal port 80
docker run -d --name webserver -p 8080:80 nginx

# List running containers
docker ps

# View container logs
docker logs webserver

# Stop a container
docker stop webserver

# Remove a stopped container
docker rm webserver

# List downloaded images
docker images

# Remove an image
docker rmi nginx

Step 4: Install and use Docker Compose

Docker Compose lets you define multi-container setups in a YAML file and manage them as a unit. It is installed automatically with Docker when using the official script. Verify:

docker compose version

A basic compose file structure:

services:
  myapp:
    image: nginx:latest
    container_name: myapp
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./data:/data

Start, stop, and restart all services in the file:

docker compose up -d    # start in background
docker compose down     # stop and remove
docker compose restart  # restart all services

Step 5: Deploy Portainer as your first real service

Portainer gives you a web UI to manage all Docker containers without typing commands. Create a directory and compose file:

mkdir ~/portainer && cd ~/portainer
nano docker-compose.yml

services:
  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

volumes:
  portainer_data:

docker compose up -d

Open http://your-pi-ip:9000 and complete the Portainer setup wizard. From here you can manage all containers, images, volumes, and networks through a browser.

Day-to-day container management

Update a service to the latest image version:

docker compose pull
docker compose up -d

Monitor resource usage across all running containers:

docker stats

Reclaim disk space by removing unused images and stopped containers:

docker system prune