Skip to content

Project Overview & Product Development Requirements

Mission

Self-hosted infrastructure management via GitOps — managing 61 containerized services across two physical servers with automated deployment, monitoring, and quality gates.

Scope

Area Details
Services 61 containerized services across 8 categories
Servers 2 (Unraid NAS, Development VM)
Deployment Komodo GitOps — all changes via git push
Networking Tailscale WireGuard VPN, direct port access, AdGuard HA DNS
Monitoring OpenTelemetry → Mimir/Loki/Tempo → Grafana
Quality Gates 7 pre-commit hooks (taplo, ruff, mypy, dclint, hadolint, yamllint, ruff-format)
CI/CD Gitea Actions for custom Dockerfile builds

Stakeholders

Role Responsibility
Solo developer / homelab operator All infrastructure decisions, development, and operations

Success Criteria

  1. Reproducible deployments — Every service deployable from a single git push
  2. Automated quality gates — Pre-commit hooks catch issues before they reach production
  3. Monitoring coverage — All critical services emit metrics, logs, and traces
  4. GitOps compliance — Zero manual SSH or UI-based deployments
  5. Disaster recovery — Gitea-down recovery documented and tested

Tech Stack

Infrastructure Layer

Component Technology Purpose
Container orchestration Docker Compose Service definition and lifecycle
Deployment platform Komodo GitOps deployment with periphery agents
VPN Tailscale WireGuard-encrypted networking
Source control Gitea Self-hosted git repository
CI/CD Gitea Actions Dockerfile builds

Monitoring Layer

Component Technology Purpose
Collector OpenTelemetry Collector Metrics, logs, traces ingestion
Metrics backend Mimir Long-term metric storage
Log backend Loki Log aggregation
Trace backend Tempo Distributed tracing
Visualization Grafana Dashboards and exploration

Media & Transcoding

Component Technology Purpose
Video Jellyfin Media server with HW transcoding
Music Navidrome Music server (Subsonic API)
HW Transcoding VAAPI/iHD Intel GPU acceleration via /dev/dri

Development Tools

Component Technology Purpose
Language Python 3.12 Automation scripts
Package manager uv Dependency management
Linting ruff, mypy (strict) Code quality
Formatting ruff-format, taplo Consistent style
YAML linting yamllint, yamlfix Compose file quality
Compose linting dclint Docker Compose conventions
Issue tracking bd (beads) Task management

Categories & Service Count

Category Count Examples
Applications 20 Gitea, Immich, Jellyfin, Navidrome, Homepage, ntfy, Crawl4AI, Vaultwarden
Database 12 Pigsty, PostgreSQL, Redis, ClickHouse, Qdrant, Memgraph, OpenSearch, Supabase
Development 4 Komodo, BigQuery Emulator, AgentMemory, Rosetta
LLM 6 LiteLLM, 9Router, Nanobot, Odysseus, QMD, Usage-Plan-MCP
Monitoring 6 Grafana, Uptime Kuma, OTel Collector, Mimir-Loki-Tempo, GLM Usage Exporter, Promtail Dev
Networking 9 AdGuard Home, AdGuard Replica, AdGuard Sync, Caddy, Cloudflared, Gluetun, Mosquitto, Pmacct, Vector
Storage 3 OpenList, Romm, Redpanda
Orchestration 2 Airflow, n8n
Total 62

Applications Inventory

Service Port(s) Purpose
aria2 — Download manager
crawl4ai 11235 Web crawling for AI
delphitools — Delphi development tools
emby — Media server
ezbookkeeping 8077 Finance tracker
gitea 2222, 3005 Self-hosted git + CI/CD
homeassistant — Home automation
homepage 8088 Service dashboard
immich 2283 Photo/video management
jellyfin 8096, 7359/udp Media server + HW transcoding
koodo 8182 Reader
linkding — Bookmark manager
navidrome 4533 Music server (Subsonic API)
ntfy 9282 Push notification service
protonmail 1025, 1143 Email bridge
searxng — Metasearch engine
tdarr — Media transcoding
vaultwarden — Password manager
zalo-tg — Zalo-Telegram bridge

Key Principles

  1. Everything as code — Compose files, deployment configs, and infrastructure are all versioned
  2. Caddy reverse proxy — *.home domains via Caddy (macvlan 192.168.100.10) for clean internal access
  3. Immutable deployments — destroy_before_deploy = true ensures clean state
  4. Secrets externalized — All secrets in Komodo Variables, never committed to git
  5. Monitoring-first — OTel collector centralizes observability from day one
  6. HW transcoding — Intel VAAPI via /dev/dri for media processing