homelab-optimized/docs/infrastructure/service-dependency-map.md

Service Dependency Map

Last Updated: 2026-02-26

This document provides a comprehensive visual and reference guide for understanding service dependencies in the homelab infrastructure.

---

Architecture Layers

┌─────────────────────────────────────────────────────────────────────┐
│                        EXTERNAL ACCESS                              │
│    Cloudflare → DDNS → Home Router → Nginx Proxy Manager           │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    CORE INFRASTRUCTURE LAYER                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌───────────┐  │
│  │  Authentik  │  │     NPM     │  │ Prometheus  │  │  Vault    │  │
│  │  (SSO)      │  │ (Proxy)     │  │ (Monitoring)│  │ (Secrets) │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  └───────────┘  │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      APPLICATION LAYER                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │  Media   │ │   Dev    │ │   Comms  │ │  Photos  │ │Productivy│  │
│  │  Stack   │ │  Stack   │ │  Stack   │ │  Stack   │ │  Stack   │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
└─────────────────────────────────────────────────────────────────────┘

---

Critical Service Dependencies

Tier 1: Foundation Services

These services must be running for other services to function:

Service	Host	Port	Dependencies	Depended By
Nginx Proxy Manager	Calypso	80, 443	Docker	All web services
Authentik	Calypso	9000	PostgreSQL, Redis	All SSO-enabled services
Vaultwarden	Atlantis	8080	SQLite	Credential storage
Prometheus	Homelab VM	9090	Node exporters	Grafana, Alertmanager

Tier 2: Operational Services

These depend on Tier 1 and support multiple other services:

Service	Host	Dependencies	Depended By
Grafana	Homelab VM	Prometheus	Dashboards
Alertmanager	Homelab VM	Prometheus	ntfy, Signal
Pi-hole	Multiple	Network	DNS resolution
AdGuard Home	Concord NUC	Network	DNS filtering
Syncthing	Multiple	Storage	Config sync
PostgreSQL	Various	Storage	Authentik, Gitea
Redis	Various	Memory	Authentik, caching

Tier 3: Application Services

End-user services that depend on Tiers 1-2:

Category	Services	Dependencies
Media	Plex, Jellyfin, arr-stack	Media storage, network
Communication	Matrix, Mastodon, Mattermost	Authentik, PostgreSQL
Photos	Immich	PostgreSQL, S3/Local storage
Development	Gitea, Portainer	PostgreSQL, Docker
Productivity	Paperless, Wallabag, Reactive Resume	Storage, Auth (optional)

---

Service Dependency Graph

Authentication Flow

User → NPM (SSL) → Authentik (OIDC) → Service
                     ↑
                     └── Redis (sessions)
                     └── PostgreSQL (users)

Monitoring Flow

Node Exporters → Prometheus → Alertmanager → ntfy
                     │
                     └── Grafana (dashboards)

Media Stack Flow

Prowlarr (indexers)
    ↓
Sonarr/Radarr/Lidarr (requests)
    ↓
qBittorrent/SABnzbd (downloads)
    ↓
Plex/Jellyfin (streaming)

External Access Flow

Internet → Cloudflare → Home Router → NPM → Service
                                        ↓
                                   Authentik (if enabled)

---

Host Service Mapping

Atlantis (Synology DS1821+)

• Primary Role: Media server, Vaultwarden, Immich
• Services: Vaultwarden, Immich, Ollama, Plex
• Critical Dependencies: Storage volumes, network

Calypso (Synology DS723+)

• Primary Role: Infrastructure, Proxy, Auth
• Services: NPM, Authentik, Paperless, Reactive Resume
• Critical Dependencies: Storage volumes

Concord NUC

• Primary Role: DNS, AdGuard, Light services
• Services: AdGuard Home, various lightweight apps
• Critical Dependencies: Network

Homelab VM

• Primary Role: Monitoring, CI/CD
• Services: Prometheus, Grafana, Alertmanager, Gitea Runner
• Critical Dependencies: Prometheus data volume

RPi5

• Primary Role: Edge/Immich
• Services: Immich (edge)
• Critical Dependencies: Network, storage mount

---

Startup Order

When bringing up the infrastructure after a complete outage:

Phase 1: Hardware & Network (0-5 min)

1. Synology NAS (Atlantis, Calypso)
2. Network equipment (router, switches)
3. Home Assistant (Zigbee/Z-Wave)

Phase 2: Core Services (5-15 min)

1. Vaultwarden - Access to credentials
2. PostgreSQL - Database foundation
3. Redis - Session/caching
4. Authentik - SSO identity
5. Nginx Proxy Manager - External access

Phase 3: Monitoring (15-20 min)

1. Prometheus - Metrics collection
2. Node Exporters - System metrics
3. Grafana - Dashboards
4. Alertmanager - Notifications

Phase 4: Applications (20-45 min)

1. Syncthing - Config sync
2. Media Stack - Plex, arr applications
3. Communication - Matrix, Mastodon
4. Development - Gitea, Portainer
5. Productivity - Paperless, etc.

Phase 5: Optional (45+ min)

1. Gaming servers
2. AI/ML services (Ollama)
3. Experimental applications

---

Failure Impact Analysis

Service Down	Impact	Affected Services
NPM	External access broken	All web services
Authentik	SSO broken	Grafana, Portainer, SSO-enabled apps
Prometheus	Monitoring silent	Grafana, Alertmanager
Vaultwarden	Can't access credentials	All (if credentials needed)
Atlantis (NAS)	Storage issues	Media, Immich, Vaultwarden
Pi-hole	DNS issues	Local network

---

Checking Dependencies

Docker Compose

cd hosts/synology/atlantis
docker-compose config

Portainer

1. Open Portainer → Stacks → Select stack
2. View "Service dependencies" in the UI

Ansible Dependency Map

ansible-playbook ansible/automation/playbooks/container_dependency_map.yml

---

Common Dependency Issues

Service Won't Start

1. Check logs: docker-compose logs <service>
2. Verify dependency is running: docker ps | grep <dependency>
3. Check restart policy

Intermittent Failures

1. Check resource availability (CPU, memory, disk)
2. Verify network connectivity between hosts
3. Check for circular dependencies

After Reboot

1. Verify Docker starts automatically
2. Check container restart policies
3. Monitor logs for startup order issues

---

For detailed troubleshooting, see Troubleshooting Guide