homelab-optimized/docs/services/dependencies.md

Service Dependencies

This document outlines the dependencies between services in the homelab infrastructure.

Core Infrastructure Dependencies

Authentication & Authorization

• Authentik (Calypso) - Provides SSO for multiple services
  • Dependent services: Grafana, Portainer, various web UIs
  • Required for: OIDC authentication across the infrastructure

Reverse Proxy & SSL

• Nginx Proxy Manager (Calypso) - Handles SSL termination and routing
  • Dependent services: All web-accessible services
  • Provides: SSL certificates, domain routing, access control

Monitoring Stack

• Prometheus (Homelab VM) - Metrics collection
  • Dependencies: Node exporters on all hosts
  • Dependent services: Grafana, Alertmanager
• Grafana (Homelab VM) - Visualization
  • Dependencies: Prometheus, InfluxDB
• Alertmanager (Homelab VM) - Alert routing
  • Dependencies: Prometheus
  • Dependent services: ntfy, Signal bridge

Storage & Backup

• Syncthing - File synchronization across hosts
  • No dependencies
  • Used by: Multiple hosts for config sync
• Vaultwarden (Atlantis) - Password management
  • Dependencies: Database (SQLite/PostgreSQL)
  • Critical for: Accessing other service credentials

Media Stack Dependencies

Download Chain

1. Prowlarr (Atlantis) - Indexer management
2. Sonarr/Radarr/Lidarr (Atlantis) - Content management
   • Dependencies: Prowlarr, download clients
3. SABnzbd/qBittorrent (Atlantis) - Download clients
   • Dependencies: VPN (optional), storage volumes
4. Plex/Jellyfin (Multiple hosts) - Media servers
   • Dependencies: Media files from arr stack

Theme Integration

• Theme.Park (Atlantis) - UI theming
  • Dependent services: All arr stack applications
  • Configuration: Must use HTTP scheme for local deployment

Network Dependencies

VPN & Remote Access

• Wireguard (Multiple hosts) - VPN access
  • Dependencies: Port forwarding, dynamic DNS
• Tailscale (Multiple hosts) - Mesh VPN
  • No local dependencies
  • Provides: Secure inter-host communication

DNS & Discovery

• Pi-hole (Multiple hosts) - DNS filtering
  • Dependencies: Upstream DNS servers
• AdGuard Home (Concord NUC) - Alternative DNS filtering

Development Stack

Git & CI/CD

• Gitea (Guava) - Git hosting
  • Dependencies: Database, storage
• Portainer (Multiple hosts) - Container management
  • Dependencies: Docker daemon, Git repositories

Databases

• PostgreSQL (Various hosts) - Primary database
  • Dependent services: Authentik, Gitea, various applications
• Redis (Various hosts) - Caching and sessions
  • Dependent services: Authentik, various web applications

Service Startup Order

For disaster recovery, services should be started in this order:

1. Core Infrastructure

   • Storage systems (Synology, TrueNAS)
   • Network services (Pi-hole, router)
   • VPN services (Wireguard, Tailscale)

2. Authentication & Proxy

   • Authentik
   • Nginx Proxy Manager

3. Monitoring Foundation

   • Prometheus
   • Node exporters
   • Grafana

4. Application Services

   • Media stack (Plex, arr suite)
   • Development tools (Gitea, Portainer)
   • Communication (Matrix, Mastodon)

5. Optional Services

   • Gaming servers
   • AI/ML services
   • Experimental applications

Critical Dependencies

Services that, if down, affect multiple other services:

• Authentik: Breaks SSO for many services
• Nginx Proxy Manager: Breaks external access
• Prometheus: Breaks monitoring and alerting
• Vaultwarden: Prevents access to credentials
• Synology NAS: Hosts critical storage and services

Dependency Mapping Tools

• Use docker-compose config to verify service dependencies
• Check depends_on clauses in compose files
• Monitor service health through Grafana dashboards
• Use Portainer to visualize container dependencies

---

For specific service configuration details, see the individual service documentation in docs/services/individual/