Installing Docker and Docker Compose on Raspberry Pi

Want to unleash the full potential of your Raspberry Pi? Docker is the secret sauce! In this guide, I’ll walk you through installing both Docker and Docker Compose on your Raspberry Pi, opening up a world of containerized applications like Pi-hole, Home Assistant, and hundreds more self-hosted solutions.

Why Docker on Raspberry Pi?

Docker lets you run applications in isolated containers, making it super easy to:

1. Run Multiple Services: Host several applications without them interfering with each other
2. Simplify Updates: Update applications with minimal downtime and risk
3. Backup Everything: Back up entire applications by simply copying a few files
4. Get Going Quickly: Deploy complex applications with just a few commands
5. Improve Security: Each container provides isolation from other services

And with Docker Compose, you can manage multiple containers as a single service—perfect for applications that have several components.

Prerequisites

• A Raspberry Pi (4 with at least 2GB RAM recommended for optimal Docker performance)
• Raspberry Pi OS installed and updated (Lite version works great for headless servers)
• Stable internet connection
• Basic command-line knowledge

Step 1: Update Your Raspberry Pi

Always start with a fully updated system to ensure compatibility and security:

sudo apt update
sudo apt upgrade -y

Step 2: Install Docker

The easiest way to install Docker on your Pi is using the official convenience script:

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

This script detects your OS and installs the appropriate version of Docker. The process might take a few minutes to complete.

Step 3: Add User Permissions

By default, you need to use sudo every time you run a Docker command. Let’s fix that by adding your user to the Docker group:

sudo usermod -aG docker $USER

For this change to take effect, you’ll need to log out and back in, or you can apply it to your current session with:

newgrp docker

Step 4: Test Docker Installation

Let’s make sure Docker is working correctly by running the classic “Hello World” container:

docker run hello-world

If everything is working, you’ll see a message confirming that your installation appears to be working correctly.

Step 5: Install Docker Compose

Now let’s install Docker Compose, which makes managing multi-container applications much easier. The installation process differs depending on your Raspberry Pi model:

For Raspberry Pi 3 and 4 (64-bit OS)

sudo apt-get install -y python3-pip libffi-dev
sudo pip3 install docker-compose

For Older Raspberry Pi Models (32-bit OS)

Docker Compose v2 doesn’t support 32-bit systems, so we’ll install version 1.29.2:

sudo apt-get install -y python3-pip libffi-dev
sudo pip3 install docker-compose==1.29.2

Step 6: Test Docker Compose

Let’s verify that Docker Compose is installed correctly:

docker-compose --version

You should see the version number of Docker Compose, confirming it’s installed properly.

Step 7: Enable Docker to Start on Boot

To make sure Docker starts automatically when your Raspberry Pi boots up:

sudo systemctl enable docker

Step 8: Create a Simple Docker Compose Project

Let’s create a simple project to test everything:

1. Create a new directory for your test project:

mkdir ~/docker-test
cd ~/docker-test

2. Create a docker-compose.yml file:

nano docker-compose.yml

3. Add the following content to create a simple web server:

version: '3'

services:
  web:
    image: nginx:alpine
    ports:
      - '8080:80'
    restart: unless-stopped

4. Save and exit (Ctrl+X, then Y, then Enter)

5. Start the container:

docker-compose up -d

6. Test the web server by visiting http://your_raspberry_pi_ip:8080 in a browser. You should see the default Nginx welcome page.

7. When you’re done testing, stop and remove the container:

docker-compose down

What’s Next? Installing Pi-hole with Docker

Now that you have Docker and Docker Compose running on your Raspberry Pi, you’re ready to install Pi-hole! Check out my guide on Protecting Your Home Network with Pi-hole for detailed instructions.

Here’s a quick preview of what a Pi-hole Docker Compose configuration looks like:

version: '3'

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - '53:53/tcp'
      - '53:53/udp'
      - '80:80/tcp'
    environment:
      TZ: 'Your/Timezone'
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    cap_add:
      - NET_ADMIN
    restart: unless-stopped

Bonus Tips for Docker on Raspberry Pi

Managing Docker Disk Space Efficiently

Docker can use a lot of disk space over time. To check how much space Docker is using:

docker system df

To clean up unused containers, images, and volumes:

docker system prune -a

Monitoring Container Resource Usage

To see which containers are using the most resources in real-time:

docker stats

Limiting Container Resources for Optimal Performance

Raspberry Pis have limited resources, so it’s good practice to limit what containers can use to prevent system instability:

services:
  myservice:
    image: myimage
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 256M

This limits the container to using half a CPU core and 256MB of RAM, ensuring your Raspberry Pi remains responsive.

Troubleshooting Common Docker Issues on Raspberry Pi

Problem: “Permission denied” errors when running Docker commands

• Solution: Make sure you added your user to the Docker group and logged out and back in

Problem: Docker containers using too much RAM

• Solution: Limit resources in your docker-compose.yml file and avoid running too many containers simultaneously

Problem: Slow container performance

• Solution: Consider using a Raspberry Pi 4 with at least 4GB of RAM for better Docker performance

Problem: Container networking issues

• Solution: Check that port mappings are correct and not conflicting with other services

Conclusion

Congratulations! You’ve successfully installed Docker and Docker Compose on your Raspberry Pi. This powerful containerization platform opens up endless possibilities for self-hosting applications, from network-wide ad blocking with Pi-hole to home automation with Home Assistant and much more.

The beauty of Docker on Raspberry Pi is that you can try out complex applications with minimal setup and keep your Raspberry Pi’s base system clean and tidy. Each application stays in its own container, making it easy to add, remove, or update without affecting anything else.