Homelab Docker Configurations

A collection of Docker containers for self-hosted services on Raspberry Pi systems

This repository contains Docker Compose configurations for running various self-hosted services on Raspberry Pi devices. Each service is organized in its own directory with persistent data volumes and consistent configuration patterns.

Overview

This setup provides a complete homelab environment with:

Media Server: Jellyfin for streaming
Network Management: Pi-hole for DNS-based ad blocking
Reverse Proxy: Nginx Proxy Manager for HTTPS and domain routing
Automation: n8n for workflow automation
Monitoring: LGTM stack (Loki, Grafana, Tempo, Mimir) for observability
Container Management: CasaOS for easy Docker management
Dashboards: Grafana standalone for custom visualizations
Backend: PocketBase for lightweight backend/database
Project Management: OpenProject for team collaboration
Backend-as-a-Service: Appwrite for full-stack development
Downloads: qBittorrent for torrent management
Music Server: Mopidy for YouTube Music streaming with remote control

All services are configured to run on Raspberry Pi with appropriate resource considerations and hardware acceleration where applicable.

Port Allocation

IMPORTANT: Use unique ports to avoid conflicts. This table shows all allocated ports.

Port	Service	Description
80	Nginx Proxy Manager	Public HTTP
81	Nginx Proxy Manager	Admin UI
443	Nginx Proxy Manager	Public HTTPS
3000	LGTM Stack	Grafana (built-in)
3050	Grafana	Standalone Grafana
3100	LGTM Stack	Loki
4317	LGTM Stack	OTLP gRPC
4318	LGTM Stack	OTLP HTTP
5678	n8n	Workflow automation
8055	PocketBase	Backend/Admin UI
8060	OpenProject	Project management
8070	Appwrite	Console/API
8071	Appwrite	Realtime
8075	qBittorrent	Web UI
8096	Jellyfin	Media server
8443	Pi-hole	Admin UI
9090	CasaOS	Container management
9092	LGTM Stack	Prometheus
6881	qBittorrent	BitTorrent (TCP/UDP)
6680	Mopidy	Web interface (Iris)
6600	Mopidy	MPD protocol
8085	ZeroClaw	Gateway / Webhook API

When adding new services, choose ports not listed above to avoid conflicts.

Container Services

CasaOS

Purpose: Web-based Docker container management interface

Location: /casa and /casaos

Docker Image: dockurr/casa

Access: http://<raspberry-pi-ip>:9090

Configuration:

ports:
  - 9090:8080
volumes:
  - ./casa:/DATA
  - /var/run/docker.sock:/var/run/docker.sock # Docker socket access

Description: CasaOS provides a user-friendly web interface for managing Docker containers. It has access to the Docker socket, allowing it to start, stop, and monitor other containers on your system.

Jellyfin

Purpose: Media server for streaming movies, TV shows, and music

Location: /jellyfin

Docker Image: jellyfin/jellyfin:latest

Access: http://<raspberry-pi-ip>:8096

Configuration:

network_mode: host
user: 1000:1000 # Replace with your user ID
volumes:
  - ./config:/config
  - ./cache:/cache
  - ~/media:/media:ro
  - /home/stoxmod/media/movies:/Movies:ro
  - /mnt/passport:/Passport:ro
devices:
  - /dev/dri:/dev/dri # Hardware acceleration for Pi 5

Features:

Hardware-accelerated video transcoding (Raspberry Pi 5 VideoCore VII)
Network mode: host for optimal performance
Read-only media mounts for data protection
Customizable media library paths

Setup Notes:

Update user with your user ID (run id -u and id -g)
Update JELLYFIN_PublishedServerUrl with your Pi's IP address
Customize media volume paths to match your setup

Pi-hole

Purpose: Network-wide ad blocking and DNS server

Location: /pihole

Docker Image: pihole/pihole:latest

Access: http://<raspberry-pi-ip>:8443/admin

Configuration:

network_mode: host
environment:
  TZ: "Asia/Colombo"
  WEBPASSWORD: "<your-password>"
  FTLCONF_LOCAL_IPV4: "192.168.1.174"
  PIHOLE_DNS_: "1.1.1.1;1.0.0.1" # Cloudflare DNS
  WEB_PORT: 8443
volumes:
  - ./etc-pihole:/etc/pihole
  - ./etc-dnsmasq.d:/etc/dnsmasq.d

Features:

Network-wide ad blocking
Custom DNS server
Web interface on port 8443
Persistent configuration and block lists

Setup Notes:

Change WEBPASSWORD to your desired admin password
Update FTLCONF_LOCAL_IPV4 with your Pi's static IP address
Configure your router to use Pi-hole as the DNS server

Nginx Proxy Manager (NPM)

Purpose: Reverse proxy with SSL certificate management

Location: /npm

Docker Image: jc21/nginx-proxy-manager:latest

Access:

Admin UI: http://<raspberry-pi-ip>:81
HTTP: Port 80
HTTPS: Port 443

Configuration:

ports:
  - "80:80" # Public HTTP
  - "443:443" # Public HTTPS
  - "81:81" # Admin interface
volumes:
  - ./data:/data
  - ./letsencrypt:/etc/letsencrypt

Features:

Easy SSL certificate management with Let's Encrypt
Reverse proxy for all your services
Web-based configuration interface
Access lists for security

Default Credentials:

Email: admin@example.com
Password: changeme
Change these immediately after first login!

n8n

Purpose: Workflow automation platform

Location: /n8n

Docker Image: docker.n8n.io/n8nio/n8n

Access: http://<raspberry-pi-ip>:5678

Configuration:

ports:
  - "5678:5678"
environment:
  - GENERIC_TIMEZONE=Asia/Colombo
  - TZ=Asia/Colombo
volumes:
  - n8n_data:/home/node/.n8n

Features:

Visual workflow builder
Hundreds of integrations
Persistent workflow storage
Timezone configuration

Optional Settings: Uncomment in the docker-compose.yml to enable:

Basic authentication
Custom webhook URL for domain access

LGTM Stack

Purpose: Complete observability stack (Loki, Grafana, Tempo, Mimir, Prometheus)

Location: /lgtm

Docker Images:

grafana/otel-lgtm (main stack)
prom/node-exporter (system metrics)

Access:

Grafana: http://<raspberry-pi-ip>:3000
Prometheus: http://<raspberry-pi-ip>:9092

Configuration:

ports:
  - "3000:3000" # Grafana UI
  - "4317:4317" # OTLP gRPC
  - "4318:4318" # OTLP HTTP
  - "9092:9090" # Prometheus
  - "3100:3100" # Loki
volumes:
  - otel-lgtm-data:/data
  - ./lgtm-config.yaml:/otel-lgtm/prometheus.yaml:ro
  - /sys:/host/sys:ro
  - /proc:/host/proc:ro

Features:

Grafana: Visualization and dashboards
Prometheus: Metrics collection
Loki: Log aggregation
Tempo: Distributed tracing
Node Exporter: System metrics (CPU, memory, disk, temperature)
Anonymous viewer access enabled

Monitored Metrics:

System resources (CPU, memory, disk)
Hardware temperatures and thermal zones
Container performance
Custom application metrics

Grafana

Purpose: Standalone visualization and dashboards platform

Location: /grafana

Docker Image: grafana/grafana:latest

Access: http://<raspberry-pi-ip>:3050

Configuration:

ports:
  - "3050:3000" # Unique port to avoid conflict with LGTM
environment:
  - GF_SECURITY_ADMIN_USER=admin
  - GF_SECURITY_ADMIN_PASSWORD=admin
volumes:
  - grafana_data:/var/lib/grafana

Default Credentials:

Username: admin
Password: admin (change on first login)

Features:

Custom dashboards separate from LGTM stack
Plugin ecosystem for extended functionality
Connect to external data sources

PocketBase

Purpose: Lightweight backend with built-in database and admin UI

Location: /pocketbase

Docker Image: ghcr.io/muchobien/pocketbase:latest

Access:

Admin UI: http://<raspberry-pi-ip>:8055/_/
API: http://<raspberry-pi-ip>:8055/api/

Configuration:

ports:
  - "8055:8090" # Unique port
volumes:
  - ./pb_data:/pb_data

Features:

SQLite database with REST API
Real-time subscriptions
Built-in authentication
File storage
Admin dashboard

Setup Notes:

Visit the admin UI on first run to create admin account
Data persists in ./pb_data directory

OpenProject

Purpose: Open-source project management and collaboration platform

Location: /openproject

Docker Image: openproject/openproject:16

Access: http://<raspberry-pi-ip>:8060

Configuration:

ports:
  - "8060:80" # Unique port
environment:
  - SECRET_KEY_BASE=${SECRET_KEY_BASE}
  - OPENPROJECT_HOST__NAME=localhost:8060
volumes:
  - ./pgdata:/var/openproject/pgdata
  - ./assets:/var/openproject/assets

Default Credentials:

Username: admin
Password: admin (change on first login)

Setup Notes:

Copy .env.example to .env
Generate secret: head /dev/urandom | tr -dc A-Za-z0-9 | head -c 32
Set SECRET_KEY_BASE in .env

Features:

Gantt charts and timelines
Agile boards (Scrum/Kanban)
Time tracking
Team collaboration
Document management

Appwrite

Purpose: Open-source Backend-as-a-Service (BaaS) platform for web and mobile apps

Location: /appwrite

Docker Images:

appwrite/appwrite:1.6 (main + workers)
mariadb:10.11 (database)
redis:7.2-alpine (cache)

Access:

Console: http://<raspberry-pi-ip>:8070
Realtime: http://<raspberry-pi-ip>:8071

Configuration:

ports:
  - "8070:80" # Console/API
  - "8071:80" # Realtime
environment:
  - _APP_OPENSSL_KEY_V1=${_APP_OPENSSL_KEY_V1}
  - _APP_DB_PASS=${_APP_DB_PASS}
  - _APP_REDIS_PASS=${_APP_REDIS_PASS}

Setup Notes:

Copy .env.example to .env

Generate secrets:

# OpenSSL key
openssl rand -hex 32
# Passwords
openssl rand -base64 24

Fill in all values in .env
Start: docker compose up -d

Features:

Authentication (OAuth, Email, Phone)
Database with real-time subscriptions
File storage
Serverless functions
Messaging (Push, SMS, Email)
Full REST and GraphQL API

Resource Requirements:

Minimum 2GB RAM for basic operation
Consider adding resource limits on Raspberry Pi

qBittorrent

Purpose: Feature-rich BitTorrent client with web interface

Location: /qbittorrent

Docker Image: lscr.io/linuxserver/qbittorrent:latest

Access: http://<raspberry-pi-ip>:8075

Configuration:

ports:
  - "8075:8080" # Web UI
  - "6881:6881" # BitTorrent TCP
  - "6881:6881/udp" # BitTorrent UDP
environment:
  - TZ=Asia/Colombo
  - PUID=1000
  - PGID=1000
volumes:
  - ./config:/config
  - ./downloads:/downloads

Default Credentials:

Username: admin
Password: Check container logs on first run (docker logs qbittorrent)

Setup Notes:

Update PUID and PGID with your user ID (id -u and id -g)
Adjust ./downloads path to your preferred download location
Forward port 6881 on your router for optimal speeds

Features:

Web-based remote access
RSS feed support
Search plugins
Sequential downloading
Bandwidth scheduling

Mopidy

Purpose: Music server with YouTube Music integration and remote control

Location: /mopidy

Docker Image: Custom build based on ghcr.io/mopidy/mopidy:latest

Access:

Web Interface: http://<raspberry-pi-ip>:6680
Iris UI (recommended): http://<raspberry-pi-ip>:6680/iris
Mobile UI: http://<raspberry-pi-ip>:6680/mobile

Configuration:

build: .
ports:
  - "6680:6680" # Web interface
  - "6600:6600" # MPD protocol
volumes:
  - ./mopidy.conf:/config/mopidy.conf
  - ./ytmusic_auth.json:/config/ytmusic_auth.json
  - ./local:/var/lib/mopidy/local
  - ./media:/var/lib/mopidy/media
devices:
  - /dev/snd:/dev/snd # Audio device access

Setup Notes:

Generate YouTube Music auth file (on your PC with a browser):

pip install mopidy-ytmusic
mopidy-ytmusic setup
# Follow prompts to authenticate with Google account

Transfer auth file to Pi:

scp ytmusic_auth.json pi@<raspberry-pi-ip>:~/homelab-configs/mopidy/

Build and start:
```
cd mopidy
docker compose up -d --build
```

Audio Configuration:

If audio doesn't work initially:

# Check ALSA devices on Pi
aplay -l

# Test audio output
speaker-test -t wav -c 2

# Adjust volume
alsamixer

You may need to adjust the audio device in mopidy.conf:

[audio]
output = alsasink device=hw:X,Y  # Replace X,Y with your device numbers

Features:

Web-based control from any device on your network
YouTube Music library search and playback
Queue management and playlists
Multiple clients can control simultaneously
Persistent state - resumes where you left off
MPD protocol support for alternative clients

ZeroClaw

Purpose: Lightweight AI assistant agent with webhook gateway

Location: /zeroclaw

Docker Image: Custom build (pre-compiled binary)

Access: http://<raspberry-pi-ip>:8085

Configuration:

build: .
ports:
  - "8085:8080" # Gateway / Webhook API
volumes:
  - ./data:/root/.zeroclaw/workspace # Agent workspace & memory
  - ./config.toml:/root/.zeroclaw/config.toml # Config file
environment:
  - RUST_LOG=info

Features:

Extremely lightweight (<5MB RAM)
SQLite vector database for memory
Supervised autonomy mode
Pairing-based security
OpenRouter / Claude Haiku integration

Setup Notes:

Download the ARM64 binary from ZeroClaw releases
Edit config.toml with your API key
Build and start: docker compose up -d --build
Check logs for pairing code: docker compose logs -f zeroclaw
See zeroclaw/SETUP.md for full deployment instructions

Getting Started

Prerequisites

Raspberry Pi (tested on Pi 5)
Docker and Docker Compose installed
Static IP address configured for your Pi
Sufficient storage for media and data

Initial Setup

Clone this repository:

git clone <repository-url>
cd homelab-configs

Configure environment-specific settings:
- Update IP addresses in configurations
- Set passwords and credentials
- Adjust volume paths for your system

Start all services:

# Start all services
for dir in */; do
  (cd "$dir" && docker compose up -d)
done

Or start individual services:

cd jellyfin
docker compose up -d

Managing Containers

Start a Service

cd <service-directory>
docker compose up -d

Stop a Service

cd <service-directory>
docker compose down

View Logs

cd <service-directory>
docker compose logs -f

Restart a Service

cd <service-directory>
docker compose restart

Update a Service

cd <service-directory>
docker compose pull
docker compose up -d

Check Service Status

docker ps

Adding New Containers

Follow this standardized structure when adding new services:

1. Create Service Directory

mkdir new-service
cd new-service

2. Create docker-compose.yml

Use this template:

version: "3.8"

services:
  service-name:
    image: <docker-image>:latest
    container_name: service-name
    restart: unless-stopped

    # Ports (if needed)
    ports:
      - "host-port:container-port"

    # Environment variables
    environment:
      - TZ=Asia/Colombo
      # Add service-specific variables

    # Volumes for persistent data
    volumes:
      - ./data:/data
      # Add service-specific volumes

    # Network (optional)
    # networks:
    #   - service-network

# Define volumes (if using named volumes)
volumes:
  service-data:
    driver: local
# Define networks (if needed)
# networks:
#   service-network:
#     driver: bridge

3. Directory Structure

Organize your service following this pattern:

new-service/
├── docker-compose.yml
├── data/              # Application data
├── config/            # Configuration files
└── logs/              # Log files (if needed)

4. Configuration Best Practices

Restart Policy: Use unless-stopped for most services
Timezone: Set TZ environment variable
Volumes: Use relative paths (./) for easy portability
Ports: Document all exposed ports in comments
Security: Never commit passwords; use environment files
User Permissions: Set appropriate user IDs for file access

5. Test and Verify

# Validate configuration
docker compose config

# Start in foreground to check for errors
docker compose up

# If successful, run in background
docker compose up -d

# Check logs
docker compose logs -f

6. Document Your Service

Add a section to this README documenting:

Service purpose
Access URLs and ports
Important configuration options
Any special setup requirements

Raspberry Pi Considerations

Hardware Requirements

Minimum: Raspberry Pi 4 with 4GB RAM
Recommended: Raspberry Pi 5 with 8GB RAM
Storage: SSD recommended for better performance (vs SD card)
Cooling: Heatsink or fan recommended under load

Performance Optimization

Use Hardware Acceleration:
- Jellyfin uses /dev/dri for video transcoding
- Check available devices: ls -la /dev/dri
Network Mode:
- Some services use host network mode for better performance
- Trade-off: Port conflicts are possible

Resource Limits: Add to docker-compose.yml if needed:

deploy:
  resources:
    limits:
      cpus: "2"
      memory: 1G

Storage Optimization:
- Mount external drives for media storage
- Use SSD for Docker volumes
- Regular cleanup: docker system prune

ARM Architecture

All images in this setup support ARM architecture (arm64). When adding new services, verify ARM support:

docker manifest inspect <image-name>:latest | grep architecture

Power Management

Services are configured with restart: unless-stopped to survive reboots. To disable auto-start:

restart: "no"

Troubleshooting

Service Won't Start

Check logs:
```
docker compose logs
```
Verify port availability:
```
sudo netstat -tlnp | grep <port>
```
Check file permissions:
```
ls -la
sudo chown -R 1000:1000 ./data
```

Performance Issues

Monitor resources:
```
docker stats
```
Check Pi temperature:
```
vcgencmd measure_temp
```
Monitor disk I/O:
```
iostat -x 1
```

Network Issues

Check container networking:

docker network ls
docker network inspect <network-name>

Verify DNS resolution:
```
docker exec <container> ping google.com
```

Permission Errors

Find your user/group ID:
```
id -u  # User ID
id -g  # Group ID
```

Update ownership:

sudo chown -R $(id -u):$(id -g) ./directory

Container Logs

View detailed logs with timestamps:

docker compose logs -f --timestamps --tail=100

Backup and Maintenance

Backup Configuration

# Backup all configurations and data
tar -czf homelab-backup-$(date +%Y%m%d).tar.gz \
  --exclude='*/cache/*' \
  --exclude='*/logs/*' \
  homelab-configs/

Update All Services

# Update all services
for dir in */; do
  echo "Updating $dir..."
  (cd "$dir" && docker compose pull && docker compose up -d)
done

Cleanup

# Remove unused images and volumes
docker system prune -a --volumes

Security Notes

Change default passwords immediately
Use Nginx Proxy Manager to add HTTPS
Consider setting up Tailscale or WireGuard for remote access
Enable UFW firewall for additional security
Keep Docker and images updated regularly

Contributing

When adding new services:

Follow the directory structure
Document in this README
Test thoroughly on Raspberry Pi
Include resource requirements

License

Personal homelab configuration - use at your own discretion.

Support

For issues with specific services, consult their official documentation:

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
appwrite		appwrite
casa		casa
flowise		flowise
jellyfin		jellyfin
languagetool		languagetool
lgtm		lgtm
mopidy		mopidy
n8n		n8n
npm		npm
openproject		openproject
pihole		pihole
pocketbase		pocketbase
qbittorrent		qbittorrent
zeroclaw		zeroclaw
.gitignore		.gitignore
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Homelab Docker Configurations

Table of Contents

Overview

Port Allocation

Container Services

CasaOS

Jellyfin

Pi-hole

Nginx Proxy Manager (NPM)

n8n

LGTM Stack

Grafana

PocketBase

OpenProject

Appwrite

qBittorrent

Mopidy

ZeroClaw

Getting Started

Prerequisites

Initial Setup

Managing Containers

Start a Service

Stop a Service

View Logs

Restart a Service

Update a Service

Check Service Status

Adding New Containers

1. Create Service Directory

2. Create docker-compose.yml

3. Directory Structure

4. Configuration Best Practices

5. Test and Verify

6. Document Your Service

Raspberry Pi Considerations

Hardware Requirements

Performance Optimization

ARM Architecture

Power Management

Troubleshooting

Service Won't Start

Performance Issues

Network Issues

Permission Errors

Container Logs

Backup and Maintenance

Backup Configuration

Update All Services

Cleanup

Security Notes

Contributing

License

Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages