🏠 HomeLab Stack

One-click self-hosted services deployment platform for home servers and VPS.

HomeLab Stack is a production-grade, one-command deployment platform for 40+ self-hosted services. It handles reverse proxying, SSO, monitoring, alerting, backups, and CN network compatibility — all wired together out of the box.

---

🚀 Quick Start

# 1. Clone the repo
git clone https://github.com/YOUR_USERNAME/homelab-stack.git
cd homelab-stack

# 2. Check dependencies & setup environment
./install.sh

# 3. Launch base infrastructure
docker compose -f docker-compose.base.yml up -d

# 4. Launch any stack
./scripts/stack-manager.sh start media
./scripts/stack-manager.sh start monitoring
./scripts/stack-manager.sh start sso

China users: Run ./scripts/setup-cn-mirrors.sh first to configure Docker registry mirrors and apt sources.

---

📦 Service Catalog

Stack	Services	Bounty
Base Infrastructure	Traefik, Portainer, Watchtower	✅ Core
Media	Jellyfin, Sonarr, Radarr, Prowlarr, qBittorrent, Jellyseerr	#2
Storage	Nextcloud, MinIO, FileBrowser, Syncthing	#3
Monitoring	Grafana, Prometheus, Loki, Alertmanager, Uptime Kuma	#4
Network	AdGuard Home, WireGuard Easy, Cloudflare DDNS, Nginx Proxy Manager	#5
Productivity	Gitea, Vaultwarden, Outline, Stirling-PDF, IT-Tools	#6
AI	Ollama, Open WebUI, LocalAI, n8n	#7
Home Automation	Home Assistant, Node-RED, Mosquitto, Zigbee2MQTT, ESPHome	#8
SSO / Auth	Authentik, PostgreSQL, Redis	#9
Dashboard	Homepage, Heimdall	#10
Notifications	Gotify, Ntfy, Apprise	#11

---

🏗️ Architecture

Internet
   │
   ▼
[Traefik v3]  ← Reverse proxy, auto HTTPS, Forward Auth
   │
   ├── [Authentik]     ← SSO / OIDC provider (all services)
   │
   ├── [Monitoring]    ← Prometheus + Grafana + Loki + Alertmanager
   │
   ├── [Media Stack]   ← Jellyfin + *arr suite
   ├── [Storage Stack] ← Nextcloud + MinIO
   ├── [AI Stack]      ← Ollama + Open WebUI
   └── [...]

All stacks share:

• A common proxy Docker network (Traefik accessible)
• A shared databases stack (PostgreSQL + Redis + MariaDB)
• Authentik SSO via Forward Auth middleware
• Centralized logging via Promtail → Loki

---

📁 Project Structure

homelab-stack/
├── install.sh                    # Entry point — env check + guided setup
├── docker-compose.base.yml       # Core infrastructure
├── .env.example                  # All configurable variables
├── BOUNTY.md                     # Bounty task overview
│
├── stacks/                       # One directory per service group
│   ├── media/
│   ├── storage/
│   ├── monitoring/
│   ├── network/
│   ├── productivity/
│   ├── ai/
│   ├── home-automation/
│   ├── sso/
│   ├── dashboard/
│   ├── databases/
│   └── notifications/
│
├── scripts/
│   ├── check-deps.sh             # Dependency + network check
│   ├── setup-env.sh              # Interactive .env generator
│   ├── setup-cn-mirrors.sh       # CN mirror configuration
│   ├── stack-manager.sh          # Start/stop/update stacks
│   ├── backup.sh                 # Volume backup
│   └── prefetch-images.sh        # Pre-pull all images
│
├── config/
│   ├── traefik/
│   ├── prometheus/
│   ├── alertmanager/
│   ├── loki/
│   ├── grafana/
│   └── authentik/
│
└── docs/
    ├── getting-started.md
    ├── services.md
    ├── configuration.md
    ├── cn-network.md
    ├── sso-integration.md
    ├── backup-restore.md
    └── troubleshooting.md

---

💰 Contributing & Bounties

This project has active bounties on open issues. See BOUNTY.md for the full list.

Each bounty task is self-contained with:

• Exact deliverables
• Acceptance criteria
• Test instructions

See CONTRIBUTING.md for contribution guidelines.

---

📋 Requirements

• Linux (Ubuntu 22.04+ recommended) or macOS
• Docker Engine 24+
• Docker Compose v2.20+
• 4GB RAM minimum (8GB+ recommended)
• A domain name (optional, but recommended for HTTPS)

---

📄 License

MIT