A Full-stack Developer‘s Guide to Installing Docker Compose on Raspberry Pi

Docker Compose is an indispensable tool for running multi-container dockerized apps on a Raspberry Pi. This 2600+ word guide will take you through installing it, as well as best practices for using compose on Raspberry Pi.

What is Docker Compose and Why Use It?

Before jumping into the installation, you may be wondering what exactly Docker Compose is and why is it useful?

Docker Compose is a tool that was developed to help define and share multi-container Docker applications. With Compose, you can create a YAML file to configure application services. Then, with a single command, you can spin everything up or tear it all down.

Here are some of the major features and benefits:

• Simpler app configuration – Configure the whole application in a single docker-compose.yml file where all service dependencies are declared
• Single-command control – Start, stop and rebuild the application with simple commands like docker-compose up/down
• Multi-container apps – Define multiple container services to create complex applications
• Portability – The compose file works across different environments
• Resource optimization – Containers share resources defined volumes and networks for efficiency

For small home projects, Compose makes it very straightforward to package together the frontend, backend, database, caching and more for your application.

According to Docker‘s 2021 survey, over 75% of Docker developers now use Docker Compose. And that usage continues to grow rapidly.

Running Compose on a Raspberry Pi enables you to leverage the flexibility of Docker without needing extensive container orchestration knowledge. Let‘s look at how to install it!

Prerequisites for Installing Docker Compose on Raspberry Pi

Before installing Docker Compose, there are a couple requirements:

Docker Engine

Since Compose relies on Docker Engine, you need to have Docker installed first:

sudo apt install docker.io

This will install the latest Docker Engine release candidate for your Raspberry Pi OS.

Note: On 64-bit Raspberry Pi OS, substitute docker.io for docker-ce in the command above

Raspberry Pi OS

An operating system based on Debian Linux is also required. The official Raspberry Pi OSimage works perfectly.

Now that the prerequisites are out of the way, let‘s move on to installing Docker Compose!

Step 1 – Update Package Lists

First we should update our package list to ensure we pull down metadata for the latest available version of Docker Compose:

sudo apt update
sudo apt upgrade

These commands will connect to the package repositories and update them.

If any packages can be upgraded, the second command will prompt you to install newer versions.

Step 2 – Install Docker Compose Package

With our package index updated, we can now install the Docker Compose package:

sudo apt install docker-compose

The command will install docker-compose and any required dependencies.

On 64-bit Raspberry Pi OS, use docker-compose-plugin instead, since the docker-ce package conflicts with docker-compose.

The installation process will show a progress bar:

Once finished, Docker Compose is installed and ready to use!

Step 3 – Verify the Installation

To check that Docker Compose is properly installed, we can print the version string:

docker-compose --version

This should output the version number you now have:

docker-compose version 1.29.2, build unknown

So in my case, Docker Compose version 1.29.2 is now installed.

Step 4 – Create a Sample Docker Compose File

With Docker Compose in place, let‘s create a simple project to test it out.

First, make a project directory:

mkdir docker-compose-test 
cd docker-compose-test

Then create this docker-compose.yml file to define a single service web app:

version: "3.9"

services:

  web:
    image: nginx
    ports:
      - "8080:80"

This configures an Nginx container and exposes port 80 to the host‘s port 8080.

Step 5 – Start Up the Containers

With our docker-compose.yml file created, let‘s start up the services:

sudo docker-compose up -d 

The -d flag runs the services in detached mode.

Our single container should now be running!

Step 6 – Verify Containers Running

Check that the Nginx container started:

sudo docker ps

We should see our web service container in the list:

And if we view http://localhost:8080 in a web browser, the default Nginx welcome page should load.

Congratulations! Our Docker Compose setup works.

This validates that:

1. Docker Compose is installed
2. A docker-compose.yml file works
3. Containers are successfully started

With that, the core installation is complete. But there‘s more we can discuss to leverage Docker Compose effectively.

Post-Installation Best Practices

Now that Docker Compose is working on your Pi, you likely want some advice on best practices:

Run Compose as a Non-root User

By default, running Docker commands requires root privileges. This isn‘t ideal for security.

The best practice is to add your non-root user to the docker user group. Then you can run docker-compose safely without sudo:

sudo usermod -aG docker ${USER}

Re-login or restart for this to take effect.

Use Version 3 Compose Files

Docker initially had version 1 and 2 Compose file formats. But version 3 supports many useful additions like resource constraints and named volumes.

Use version 3 unless you need to specifically remain compatible with older Docker releases.

Constrain Container Resources

Unlike a desktop or server, Raspberry Pis have pretty limited RAM and CPU power.

Pay close attention to container resource demands using Compose file options like cpus, memory and pids. If you don‘t constrain container resources, your Pi can slow down or become unstable.

Here is an example of adding resource limits:

services:
  web:
    image: nginx
    cpus: "1"
    mem_limit: 512M
    pids_limit: 128

Use Bind Mounts Over Volumes

By default, containers have ephemeral storage that disappears after they shut down. Often you‘ll want persistent data outside the containers using volumes or bind mounts.

On Raspberry Pi, bind mounts are preferable since they avoid the filesystem I/O overhead of volumes. Just be aware of the risks of using bind mounts instead of volumes.

Utilize Pre-built ARM Images

When possible, leverage container images purpose-built for ARM like Raspberry Pi rather than generic x86 images. These images will run more efficiently without emulation overhead.

Docker Hub now curates many ARM-compatible images. For example, arm32v7/nginx instead of the standard nginx image.

Going Beyond – Alternatives and Next Steps

While Docker Compose itself is now setup, there are additional tools you may want to consider:

Docker Swarm

Docker Swarm provides full-fledged orchestration features like clustered management, scaling, load balancing and more for containers. It gives a production-grade platform for containerized apps.

Swarm is well-supported on Raspberry Pi using HypriotOS.

Kubernetes

As an alternative to Swarm, Kubernetes is an open source container orchestrator with an extensive ecosystem. Major cloud providers offer managed Kubernetes services.

For example, Docker Desktop now comes bundled with Kubernetes support.

And managed services like Amazon EKS Anywhere make self-hosted clusters possible for edge computing using Raspberry Pis.

So there are many options to run resilient Dockerized applications.

No matter which tooling you leverage, Docker Compose is a lightweight starting point for defining containers as code and wiring together the components of your apps!

I hope this full guide helped provide what you need to get started using Compose on your Raspberry Pi devices. Let me know in the comments if you have any other questions!