Docker Compose: The Easier Way to Run Docker on Raspberry Pi

Docker is an excellent tool for installing portable cross-platform apps on Raspberry Pi. However, using Docker often involves figuring out long and confusing commands. In this post, I’ll show you an easier way to run app containers with simple text files.

Docker Compose is installed on Raspberry Pi using an official script from Docker. To deploy a container, download a sample Compose file, edit its settings, and launch the app with Docker Compose.

I’ll show you a dead simple way to install Docker Compose. To give an example of how to use it, I’ll walk you through using Docker Compose to run Photoprism, a self-hosted photo management server. Lastly, as a bonus, I’ll share a list of great apps you can run as containers.

If you’re new to Raspberry Pi or Linux, I’ve got something that can help you right away!
Download my free Linux commands cheat sheet – it’s a quick reference guide with all the essential commands you’ll need to get things done on your Raspberry Pi. Click here to get it for free!

Why Use Docker Compose?

When I first heard about Docker, I thought it would be the next killer app. It could open up unlimited possibilities to run any program on any system—or at least, that was the dream.

When I began using Docker, the shine started to fade. Different containers required unusual configurations—often with variables that weren’t intuitive and that I couldn’t get working. Worse, different operating systems configured Docker differently, so it wasn’t universal.

Because of all that friction, I rarely used Docker—and only as a last resort. Until I discovered the magic of Docker Compose files.

What’s the Difference Between Docker and Docker Compose?

Docker is the program that runs app containers.
Docker Compose files are text files that make configuring and deploying apps easier.

If you use Docker the regular way, you’d have to figure out this command to run the Plex app:
docker run -d --name=plex --net=host-e PUID=1000 -e PGID=1000 -e TZ=Etc/UTC -e VERSION=docker -e PLEX_CLAIM=#optional -v /path/to/plex/library:/config -v /path/to/tvseries:/tv -v /path/to/movies:/movies --restart unless-stopped lscr.io/linuxserver/plex:latest

But if you use Docker Compose instead, you get this easy-to-read text file:

---
services:
  plex:
    image: lscr.io/linuxserver/plex:latest
    container_name: plex
    network_mode: host
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - VERSION=docker
      - PLEX_CLAIM= #optional
    volumes:
      - /path/to/plex/library:/config
      - /path/to/tvseries:/tv
      - /path/to/movies:/movies
    restart: unless-stopped

I find it more convenient to save the file above on your system and edit it with Nano.

My strongly held opinion is that Docker Compose is simply the better way to use Docker.
Compose files make it so:

• App containers can be set up faster and more intuitively.
• Containers can be moved between systems by copying/pasting text.
• Running containers can be updated conveniently with almost no downtime.

In short, Docker Compose finally delivers on the promise of making Docker feel like a universal way to run app containers.

When Can You Use Docker Compose?

You can use Docker Compose to deploy any Docker container.

I use Docker Compose files to set up 100% of my containers. It’s the only way I use Docker now.

More specifically, I turn to Docker when I want to run servers that aren’t natively supported on Raspberry Pi OS or when I want to install an app that normally requires messy workarounds.

If you’re sold, let’s finally get down to installing Docker Compose on Raspberry Pi.

Docker Compose Installation on Raspberry Pi

Now you understand why I’m a big fan of Docker Compose and why it’s become so popular. In this section, I’ll review the requirements to run and install it on Raspberry Pi.

Requirements

Here’s the hardware and software you’ll need to run Docker Compose:

• Raspberry Pi: Almost every Raspberry Pi model should be able to run Docker.
  I recommend it on newer boards like the Raspberry Pi 5, Pi 4, and Pi 3B+.
  My examples use a 64-bit system, but Docker works on 32-bit models, too.
• Operating system: Raspberry Pi OS (Bookworm or Bullseye recommended).
  These instructions will also probably work on Debian, Ubuntu, and a few other Linux distros.
• Internet access: to download Docker images of the apps you want to run.

How to Install Docker Compose on Raspberry Pi

Let’s start by installing Docker. Then, you’ll install Docker Compose and test if it’s working.

It’s just a 1-line install. The rest will help you understand how things should work.

1. Install Docker

Open a terminal, and run the official Docker installation script.
curl -sSL https://get.docker.com | sh

The script will install everything (repo, keys, etc.) for you. That’s all—you’re done.

When the script is finished, Docker should be installed with autostart already enabled.
systemctl status docker

This next step is optional but highly recommended. Adding your user to the Docker group allows you to run Docker commands without sudo. It also adds some security in that the container cannot run with root privileges.

• Add your user to the “docker” group.
  sudo usermod -aG docker $USER
• Log out and log back in for the changes to take effect.
  logout

Note: If you want to see these steps in action, I have a video lesson available just for community members. Join here to watch it directly! Becoming a member gives you access to 30+ other lessons for Raspberry Pi and comes with many other benefits.

2. Install Docker Compose

Next, we have to install Docker Compose so that Docker can use Compose files. In the past, there were three different ways to do this. But now, guess what?

Docker Compose is already installed because new versions include it by default.

Check if it’s installed.
docker compose version

Now you’re ready to launch a test container using your very own Compose file:

• First, make a folder to hold all of your containers.
  mkdir containers
• You’ll want a separate folder for each app you plan to run. For our test, make a subfolder.
  cd containers
mkdir helloworld
cd helloworld
• Create a Docker Compose file, which typically uses the .yml or .yaml extension.
  nano compose.yaml
• Now, paste these lines into your new compose.yaml file. The indentation matters!

services:
  hello-world:
    image: hello-world

• Finally, launch the container.
  docker compose up

Using up tells Docker to look for compose.yaml in the current directory and do the following:

• Download the image specified in the Compose file from the official registry.
• Apply configuration settings from the Compose file.
• Start the app as a container.

Success! Docker Compose is working. That was easy.

Are you a bit lost in the Linux command line? Check this article first for the most important commands to remember and a free downloadable cheat sheet so you can have the commands at your fingertips.

Example: Photoprism with Docker Compose

Now you’ve installed Docker Compose and understand how it works. But what about a more realistic use case? In this section, I’ll show how to run a server with a Docker Compose file.

You’ll create a container for Photoprism, an AI photo management app. Photoprism can’t be installed natively on Raspberry Pi, but you can get it up and running with Docker Compose.

Here’s an overview of the steps:

• Download a sample Docker Compose file.
• Modify the Compose file to match your system configuration.
• Launch the container with your Compose file.

1. Download the Sample Docker Compose File

You’ll start by getting a sample Compose file from Photoprism’s official website:

• Inside your containers folder, create a subfolder for the app.
  mkdir photoprism
cd photoprism
• Download the sample Docker Compose file.
  wget https://dl.photoprism.app/docker/arm64/compose.yaml

Here’s a preview of the Compose file we downloaded:

It looks complicated, but most of the time, you’ll leave 99% of the settings alone and only change a few variables. The beauty is that the sample did all of the hard work for you already.

I rarely create Docker Compose files from scratch. I just download (or copy/paste) a Compose file provided by the official vendor or one made by somebody else.

Then, I modify it for my use, which is what you’ll do next.

2. Edit the Compose File

You often have to change a few settings in the Compose File to get containers to work properly on your particular system—or in our case, on a Raspberry Pi.

Here are the most common things I find myself changing:

• Password: for security purposes.
• Port: to assign a port for connections if it’s a service or server.
• Volumes: to specify where to store app files.

What you’ll have to change depends on the container you’re working with. You’ll find instructions on the page where you got the Compose file.

Let’s make these changes in the Compose file for our Photoprism example.

Modify Password

First, change the default password because that’s a security risk.

• Open Photoprism’s Docker Compose file.
  nano compose.yaml
• Find PHOTOPRISM_ADMIN_PASSWORD. It’s set to “insecure” so change it by replacing what’s inside the quotation marks. For example:

Modify Port

If there’s a port that needs to be exposed for the app to function, it will be found in the Docker Compose file under the “ports” section.

The syntax for ports is written like this:
(your system’s port):(app’s internal port)

• On the left side of the colon (:), change the port to the one you want to use.
• On the right side of the colon (:), don’t change anything.

This line means the app container wants to map port 2342 on your system to the app’s internal port 2342.

Using port 2342 should be fine on Raspberry Pi OS, so I won’t change it. (However, you may need to change port numbers for apps that default to something common, like port 80 or 443, which can create conflicts with your other apps.)

So there’s nothing to do here, and you’re done. Nice.

Modify Volumes

Last comes the part that might be the most confusing for newcomers: mapping directories.

The app has a set folder structure internally so containers are portable across different operating systems. But the actual folders might be different on whatever OS you’re running the container on. So the container needs to map your system’s folders to the app’s folders.

The simple explanation: you have to tell the container where it can store data.
In Docker Compose files, you’ll find these directories listed under the “volumes” section.

The syntax for volumes is written like this:
(your system’s folder):(app’s internal folder)

• On the left side of the colon (:), modify this to point to a folder on your system.
• On the right side of the colon (:), don’t change anything.

For our Photoprism example, the documentation says to modify this line:
~/Pictures:/photoprism/originals

Currently, it’s pointing to the Pictures folder in my home directory. You can change it to whichever folder your system will store the photos. For instance, you can even change it to a mounted USB folder if you plan to store all your photos on an external drive.

In this case, the default works just fine for Raspberry Pi OS. But I’ve seen many sample Compose files where the default folders don’t exist on my system.

Important: The volumes specified must already exist, but if they don’t, you must change the path or create the directories yourself. Docker Compose will NOT do it for you.

If it isn’t set properly, the container won’t start or function as expected.

That’s everything you have to edit in the Compose file: save your changes and exit Nano.

Photoprism had great defaults for Raspberry Pi OS, so all we changed was the password. That’s what makes Docker Compose so attractive—configuration is as simple as editing a text file.

3. Launch the Container with Docker Compose

Now it’s show time! Let’s launch Photoprism with Docker Compose.

• Run this command from the directory where you put the Compose file.
  docker compose up
• You’ll see Docker Compose pulling (AKA, downloading) files and doing its magic. When it’s done, you’ll see the Photoprism server go into listening mode.
  

Tip: For containers meant to be 24/7 servers, it’s more convenient to run them in the background. To detach, add the -d flag:
docker compose up -d

• Go to another PC, and point your browser to the Raspberry Pi on port 2342.
  192.168.1.69:2342
  (Replace 192.168.1.69 with your Pi’s local IP.)

It worked! To log in, the username is ‘admin’ and the password is the one you set earlier.

There’s more you can do with Photoprism, but this was just an example of how easy it was to run a non-native app on Raspberry Pi with just a couple of line changes in Docker Compose.

I didn’t have to figure out which dependencies to install. Best of all, I didn’t have to configure the MariaDB database that Photoprism needs. The container handled it all.

Docker Compose is a total game-changer in the right situations.

More Possibilities With Docker Compose

If you’re looking for other containers to run, below is a list of popular ones I recommend. I’ve provided links to where you can get sample Docker Compose files.

I’ve also provided links to our tutorials, just in case you prefer installing the app natively on Raspberry Pi or want to learn how it works. Happy containerizing!

Media

• Plex – a media server for TV and movies (Compose file).
• Jellyfin – a fully offline media server that’s free and open-source (Compose file).
• Sonarr – automatically manages your TV shows (Compose file).
• Radarr – automatically manages your movie collection (Compose file).
• Bazarr – automatically downloads subtitles for TV and movies (Compose file).
• FreshRSS – a self-hosted feed aggregator to follow multiple sites in one place (Compose file).
• BookStack – create your own Wiki (Compose file).

Productivity

• Code Server – code with VS Code through a web browser (Compose file).
• Photoprism – an AI photo manager (Compose file).
• Lychee – a photo management tool (Compose file).
• Obsidian – a note-taking app with lots of powerful plugins (Compose file).
• Mealie – a self-hosted recipe manager (Compose file).

File Sharing

• NextCloud – host your own cloud (Compose file).
• qBittorrent – a full-featured torrent client (Compose file).
• Transmission – a lightweight torrent client (Compose file).
• Syncthing – sync files across multiple devices (Compose file).

Homelab Management

• Heimdall – a pretty dashboard to organize all your server apps (Compose file).
• Home Assistant – the ultimate in smart home automation (Compose file).
• Vaultwarden – a Bitwarden password manager server (Compose file).

Network Tools

• Grafana – monitor anything like network traffic (Compose file).
• SpeedTest – test your internet speed (Compose file).
• duckdns – map a domain to your dynamic IP address (Compose file).
• Pi-Hole – a network-wide ad-blocker (Compose file).
• Nginx – run your web server (Compose file).
• UniFi Controller – manage your UniFi network devices (Compose file).

Related: 11 Docker Projects Every Raspberry Pi Owner Should Try

Well, I’m out of breath. If that wasn’t enough for you, there are more options you can browse through in the official registry. Remember that if you’re using a newer Raspberry Pi with a 64-bit processor, you’ll want Docker images that support ARM64.

That’s all folks! Now you know how to deploy Docker containers easily with Docker Compose files.

If you want to manage containers through a graphical interface, I recommend checking out our guide to Portainer. To level up, combine your knowledge of Docker Compose files with Portainer. And soon, everybody on your street will know you as the container guru.

FAQ

How do I see which Docker containers are running?

To view all of your containers, use this command:
docker ps -a

The STATUS column tells you whether the container is started or stopped.

How do I start, stop, or delete containers with Docker Compose?

These commands must be run from the directory that contains your app’s YAML file.

• To download and install a new container, use the up command.
  docker compose up
• To delete an existing container, use the down command.
  docker compose down

Once you’ve got a container configured the way you want, you don’t need to install or delete it every time you want to start or stop the app. Instead, use these:

• To pause a running container, use the stop command.
  docker compose stop
• To resume a paused container, use the start command.
  docker compose start

How do I update Docker & Docker Compose?

Once installed, Docker and Docker Compose can be updated with your normal system update.
sudo apt update
sudo apt upgrade

You can also remove these programs with APT in the same way you remove others.

How do I update an app container using Docker Compose?

Your system’s package manager, APT, will not update apps running as containers for you.
To update a container, run the following commands:

• Download the latest version of the image.
  docker compose pull
• Reinstall the container again.
  docker compose up

Whenever you’re ready, here are other ways I can help you:

Test Your Raspberry Pi Level (Free): Not sure why everything takes so long on your Raspberry Pi? Take this free 3-minute assessment and see what’s causing the problems.

The RaspberryTips Community: Need help or want to discuss your Raspberry Pi projects with others who actually get it? Join the RaspberryTips Community and get access to private forums, exclusive lessons, and direct help (try it for just $1).

Master your Raspberry Pi in 30 days: If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.

Master Python on Raspberry Pi: Create, understand, and improve any Python script for your Raspberry Pi. Learn the essentials step-by-step without losing time understanding useless concepts.

You can also find all my recommendations for tools and hardware on this page.