homelab/README.md

Homelab Infrastructure

A collection of self-hosted services running on Docker containers, orchestrated through Portainer and exposed via Traefik reverse proxy.

Architecture

This homelab uses a stack-based approach where each service is containerized and deployed as a complete stack with its dependencies. All services integrate with a centralized Traefik instance for SSL termination and domain routing.

Stack Structure

docker/stacks/<service>/
 - docker-compose.yaml   # Service definition
 - stack.env             # Environment template (tracked)
 - stack.env.real        # Actual values with secrets (gitignored)

Services

Service	Description	Purpose
Immich	Self-hosted photo and video management	Personal media library with ML features
Paperless-ngx	Document management system with OCR	Digital document archive and search
Media Stack	Sonarr, Radarr, Prowlarr, qBittorrent	Automated media acquisition and management
Arch Mirror	Local Arch Linux package repository mirror	Local package cache for faster updates

Deployment

Services are deployed through Portainer WebUI:

1. Access Portainer dashboard
2. Navigate to Stacks section
3. Create new stack or update existing
4. Copy content from docker-compose.yaml
5. Configure environment variables from stack.env.real
6. Deploy stack

Environment Setup

For each stack:

cd docker/stacks/<service>/
cp stack.env stack.env.real
# Edit stack.env.real with actual values

Common Operations

Stack Management

• Stack status and logs monitored through Portainer WebUI dashboard
• Updates performed by pulling new images and recreating containers

Backup Operations

Each stack includes automated backup services:

• Database backups: Hourly PostgreSQL dumps using postgres-backup-local
• File backups: Scheduled Restic backups to AWS S3 backend

Network Architecture

• traefik (external): Reverse proxy network for SSL termination and routing
• service-specific: Internal networks for each stack (immich, paperless, sonarr, radarr)
• Services primarily accessed through Traefik with minimal direct port exposure

Security

• All services behind Traefik reverse proxy with Let's Encrypt SSL certificates
• Environment variables with secrets stored in *.env.real files (gitignored)
• API endpoints protected with HTTP basic authentication where applicable
• Internal service communication isolated over Docker networks

Requirements

• Docker and Docker Compose
• Portainer CE for stack management
• Traefik reverse proxy (external dependency)
• Valid domain names for SSL certificate generation

Notes

• This repository contains infrastructure definitions only
• Actual deployment and management handled through Portainer WebUI