Raspberry Pi Docker: From Installation to Advanced Usage and Troubleshooting

Sep 29, 2024

Docker is a platform that allows you to package and run applications in isolated environments called containers. These containers include everything the application needs to run—code, runtime, libraries, and dependencies—ensuring consistency across different computing environments.

Using Docker on a Raspberry Pi offers several benefits, especially given the device's resource limitations:

Resource Efficiency: 
Lightweight Containers: Docker containers share the host system’s kernel, making them much lighter than virtual machines. This allows you to run multiple applications on a Raspberry Pi without overloading its limited CPU and memory resources.

Simplified Deployment: 
Pre-built Images: With Docker, we can pull pre-built images from repositories like Docker Hub, which reduces the complexity of setting up software on the Raspberry Pi. This is particularly useful when we want to quickly deploy applications without manually configuring them.

Integration:
Docker’s compatibility with various software stacks allows seamless integration with other tools, making the Raspberry Pi a versatile hub for DIY projects, home automation, or small-scale server tasks.

Prerequisites

● Raspberry Pi: Docker works best on the more recent models like the Raspberry Pi 5 due to better processing power and more memory.
● Raspberry Pi OS: For better performance, especially with larger applications, it's recommended to use the 64-bit versión.
● MicroSD card: 32GB or more is preferable, especially if we plan to run multiple Docker containers.
● Network connection: Ethernet preferred, but Wi-Fi works tooSetup and Installation 

Setting Up Docker on Raspberry Pi

Installing Docker on a Raspberry Pi is a straightforward process. Here's a step-by-step guide to get Docker up and running on your Raspberry Pi:

1.Update Your Raspberry Pi. Open a terminal and run:
sudo apt-get update
sudo apt-get upgrade

2.Install Docker. Docker provides an installation script that automates the installation process.
Download and run the Docker installation script:
curl -sSL https://get.docker.com | sh

This script will download and install the latest version of Docker for your Raspberry Pi.

3.Add your user to the Docker group** to run Docker commands without needing `sudo`:
sudo usermod -aG docker $USER
After running this command, we need to log out and log back in, or reboot your Raspberry Pi, for the changes to take effect.

4.Verify Docker Installation
To check if Docker is installed correctly, we can run the following command:
docker -v

This should return the version of Docker that has been installed.

Docker Basics and Commands on Raspberry Pi

Key Docker Concepts

Image: A read-only template used to create containers. Images can include everything needed to run an application. For example, an image could contain an OS, a web server, and the application itself.

Container: A runnable instance of an image. Containers are isolated environments, and multiple containers can run on the same machine, sharing the host OS kernel.

Dockerfile: A script that describes the steps to follow when creating a Docker image. It automates the creation of Docker images by specifying what goes inside the image.

Registry: A repository where Docker images are stored and shared. Docker Hub is the most common registry where we can find thousands of pre-built images.

Essential Docker Commands

Check Docker System Information
docker info
This command provides detailed information about the Docker installation, including the number of containers, images, and system resources.
-Search for an Image on Docker Hub:
docker search <image-name>
 For example:
docker search nginx

-Pull an Image from Docker Hub:
docker pull <image-name>
To pull the latest Nginx image:
 docker pull nginx

-List Downloaded Images:
 docker images
This command lists all the Docker images available locally on your Raspberry Pi.

-Run a Container:
docker run <image-name>
 Running a container from the Nginx image:
docker run nginx
To run a container in the background (detached mode) and map port 80 of the container to port 8080 on the host:
docker run -d -p 8080:80 nginx
 
-List Running Containers:
 docker ps

-List All Containers (Running and Stopped):
docker ps -a

-Stop a Running Container:
docker stop <container-id>
We can get the <container-id> from the docker ps command.

-Start a Stopped Container:
 docker start <container-id>

-Remove a Stopped Container:
 docker rm <container-id>

-Remove an Image:
docker rmi <image-id>
We can get the <image-id> from the docker images command.

-Create a Volume:
docker volume create <volume-name>

-List Volumes:
docker volume ls

-Inspect a Volume:
docker volume inspect <volume-name>

-Remove a Volume:
docker volume rm <volume-name>

Advanced Docker Usage on Raspberry Pi

Docker Compose:

Docker Compose is a command-line tool that allows you to define and run complex applications that are containerized with Docker.
   1.Download Docker Compose. Open terminal and run:
wget https://github.com/docker/compose/releases/download/v2.29.7/docker-compose-linux-aarch64
 
   2.Move the downloaded file to /usr/bin:
sudo mv docker-compose-linux-aarch64 /usr/bin/Docker-compose
 
   3.Set a execute permissions:
sudo chown root: /usr/bin/docker-compose
sudo chmod +x /usr/bin/docker-compose
 
   4.Verify Docker Compose installation:
docker-compose --version
Create multi-container applications with docker-compose.yml.

Nextcloud example

services:
  nc:
    image: nextcloud:apache
     environment:
      - POSTGRES_HOST=db
      - POSTGRES_PASSWORD=nextcloud
      - POSTGRES_DB=nextcloud
      - POSTGRES_USER=nextcloud
     ports:
      - 80:80
    restart: always
    volumes:
      - nc_data:/var/www/html
db:
    image: postgres:alpine
     environment:
      - POSTGRES_PASSWORD=nextcloud
      - POSTGRES_DB=nextcloud
      - POSTGRES_USER=nextcloud
      restart: always
      volumes:
      - db_data:/var/lib/postgresql/data
      expose:
      - 5432
volumes:
  db_data:
  nc_data:

Portainer for Docker Management

Portainer is a lightweight, open-source management tool for Docker that provides a user-friendly graphical interface to manage Docker environments, including containers, images, networks, and volumes. It simplifies the complexity of managing Docker by allowing users to interact with their Docker setup through a web-based interface, rather than relying solely on command-line instructions.

Install Step by Step

1.Pull the latest Portainer image by running:
docker pull portainer/portainer-ce:latest
This command pulls the latest version of the Portainer Community Edition (CE).

2.Create a Docker Volume for Portainer
Portainer requires a persistent storage. We can create this volume using the following command:
docker volume create portainer_data

3.Deploy the Portainer Container
Now, you'll run the Portainer container, binding it to Docker and exposing it on a port so that we can access it via a web browser.

4.Run the Portainer container with the following command:
docker run -d -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest

Here's what this command does:
      -d: background mode.
      -p 9443:9443: Maps port 9443 on your Raspberry Pi to port 9443 in the container (for HTTPS access).
      --name portainer: Names the container "portainer".
      --restart=always: Ensures that Portainer restarts automatically if the Raspberry Pi reboots.
      -v /var/run/docker.sock:/var/run/docker.sock: Mounts the Docker socket so that Portainer can communicate with the Docker engine.
      -v portainer_data:/data: Attaches the volume created earlier for persistent storage.

5.Access the Portainer Web Interface
After the container is up and running, we can access the Portainer UI:
1.Open a web browser and go to https://<your-raspberry-pi-ip>:9443.
      Replace <your-raspberry-pi-ip> with the actual IP address of your Raspberry Pi 5.
      We might see a security warning because the connection is self-signed; we can safely proceed to the site.

Real-world use cases on Raspberry Pi

Home Assistant: A popular open-source platform for controlling smart home devices. You can use Docker to run Home Assistant on a Raspberry Pi, making it easier to manage updates and dependencies.

https://hub.docker.com/r/homeassistant/home-assistant

docker run -d --name=home-assistant -v /path/to/your/config:/config -p 8123:8123 homeassistant/home-assistant:stable

InfluxDB and Grafana: For IoT applications that require data collection and visualization, Docker can be used to run InfluxDB (a time-series database) and Grafana (a data visualization tool). This allows users to collect data from sensors and visualize it on dashboards, all on a low-powered Raspberry Pi.

https://hub.docker.com/_/influxdb

docker run -d -p 8086:8086 --name influxdb influxdb:2

 https://hub.docker.com/r/grafana/grafana

docker run -d -p 3000:3000 --name grafana grafana/grafana

Surveillance (MotionEye): Docker allows you to deploy MotionEye, a surveillance system that turns your Raspberry Pi into a security camera hub.

https://hub.docker.com/r/ccrisan/motioneye

docker run -d --name=motioneye -p 8765:8765 -v /path/to/media:/media ccrisan/motion

Duplicati: Use Docker to run Duplicati, an open-source backup solution, to schedule backups of files from various devices on your home network to external drives connected to your Raspberry Pi.

https://hub.docker.com/r/duplicati/duplicati

docker run -d --name=duplicati -v /backup/location:/backups -p 8200:8200 duplicati/duplicati

Plex: Use Docker to host a media server that streams videos, music, and photos to multiple devices.

https://hub.docker.com/r/plexinc/pms-docker/

docker run -d --name=plex -v /path/to/media:/media -p 32400:32400 plexinc/pms-docker

Troubleshooting and Maintenance

● Check the Docker service status
sudo systemctl status Docker

Look for any error messages. If we need, try restarting it:
sudo systemctl restart Docker

● High CPU or Memory Usage
Running multiple or resource-intensive containers can overwhelm the limited CPU and memory of the Raspberry Pi.

 Monitor resource usage with docker stats, htop, or top to monitor system and container resource usage.
 docker stats

Identify and stop resource-hogging containers:
docker stop <container-id>

Consider using lightweight versions of images or limiting container resources using Docker’s resource management flags:
docker run -m 256m --cpus="0.5" <image-name>

This limits the container to 256MB of memory and 50% of one CPU core.

● Running Out of Disk Space
Remove Unused Containers, Images, and Volumes:
docker system prune -a
docker volume prune

Monitor Disk Usage:
List images, containers, and volumes, and check how much space they’re using:
docker system df

Move Docker Data to External Storage:
If the Raspberry Pi’s SD card fills up quickly, consider moving Docker’s data directory (/var/lib/docker) to an external USB drive:
1.Stop the Docker service:
sudo systemctl stop docker
2.Move Docker’s data directory:
sudo mv /var/lib/docker /mnt/external_drive/docker
3.Create a symbolic link:
sudo ln -s /mnt/external_drive/docker /var/lib/docker
sudo systemctl start docker

● Data Corruption in Volumes:
Improper shutdowns or power loss on the Raspberry Pi can cause data corruption, especially in volumes stored on SD cards.
Use fsck to check and repair the file system on the SD card or external drive:
sudo umount /dev/mmcblk0p1
sudo fsck /dev/mmcblk0p1
sudo mount /dev/mmcblk0p1

Backup and Restore Volumes:
Regularly back up volumes using a container like busybox to prevent data loss in case of corruption:
docker run --rm -v my_volume:/data -v $(pwd):/backup busybox tar czf /backup/backup.tar.gz /data

Use External Storage for Persistent Data:
Storing Docker volumes on external drives (preferably SSDs) instead of SD cards can improve performance and reduce the risk of corruption.

Conclusion
This article provides a comprehensive guide to setting up and using Docker on a Raspberry Pi. It covers key Docker concepts, from basic installation steps to advanced usage like Docker Compose and Portainer for managing containers. Practical examples, such as running Home Assistant or Plex on Raspberry Pi, highlight real-world applications. Additionally, it includes troubleshooting tips for common issues like high CPU usage and disk space limitations, making it an excellent resource for both beginners and advanced users looking to optimize Docker on their Raspberry Pi systems.