Virtualization and ContainersDocker StacksIntermediate2 hoursLab build

Build a Raspberry Pi Container Host with Docker Compose

A Raspberry Pi Docker Compose host with health checks, safer update habits, and a small-service layout that is easy to maintain.

Last reviewed4/30/2026

service update workflowscontainer health checkshomelab CI and rollback

Raspberry PiDockerDocker ComposeNginx

Expected Outcome

A working Raspberry Pi container host that can run multiple Docker containers with automated health checks and a safe update process.

Assumptions

Raspberry Pi (any model with Raspbian OS installed)
Basic knowledge of Linux command line
Internet connection
SSH access to the Raspberry Pi

Bill of Materials

Raspberry Pi
MicroSD card (16GB or larger)
Power supply for Raspberry Pi
Network cable or Wi-Fi connection
Computer for SSH access

Build Steps

Update System Packages
Ensure your Raspberry Pi is running the latest packages.
Safe to run: read-only
```
sudo apt update
sudo apt upgrade -y
```

Install Docker

Install Docker on your Raspberry Pi.

Safe to run: read-only

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

Install Docker Compose
Install Docker Compose to manage multi-container applications.
Changes system state: review before running
```
sudo apt install -y libffi-dev libssl-dev
sudo apt install -y python3 python3-pip
sudo pip3 install docker-compose
```
Create a Docker Compose File
Set up a Docker Compose file to define your containers.
Safe to run: read-only
```
mkdir ~/my_docker_app
cd ~/my_docker_app
nano docker-compose.yml
```

Define Services in Docker Compose

Edit the docker-compose.yml file to define your services with health checks.

Safe to run: read-only

version: '3'
services:
web:
image: nginx
ports:
- '80:80'
healthcheck:
test: ['CMD', 'curl', '-f', 'http://localhost']
interval: 30s
timeout: 10s
retries: 3

Deploy the Containers
Use Docker Compose to deploy the defined services.
Changes system state: review before running
```
docker-compose up -d
```
Set Up Safe Update Workflows
Implement a workflow for safe updates of your containers.
Changes system state: review before running
```
docker-compose pull
docker-compose up -d
docker system prune -f
```

Validation

Check if the containers are running using 'docker ps'.
Verify health check status using 'docker inspect <container_id>'.

Troubleshooting

If a step fails, capture the exact command, exit code, and log line before retrying or changing the design.
Use `docker compose ps` and `docker compose logs <service>` to separate image, environment, port, and volume problems.

Cleanup or Rollback

Keep a copy of working configuration, compose files, scripts, and service credentials before removing containers, packages, or data directories.
Stop test containers with `docker compose down` only after confirming which volumes contain persistent data.
Rollback by redeploying the previous compose file or image tag and restoring the saved environment file.

Next Improvements

Explore additional Docker images to deploy.
Implement persistent storage for your containers.
Set up a monitoring solution for your containers.