230 lines
8.6 KiB
Markdown
230 lines
8.6 KiB
Markdown
# 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
|
|
```bash
|
|
cd hosts/synology/atlantis
|
|
docker-compose config
|
|
```
|
|
|
|
### Portainer
|
|
1. Open Portainer → Stacks → Select stack
|
|
2. View "Service dependencies" in the UI
|
|
|
|
### Ansible Dependency Map
|
|
```bash
|
|
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](../troubleshooting/common-issues.md)*
|