Sanitized mirror from private repository - 2026-03-21 08:52:36 UTC
This commit is contained in:
Gitea Mirror Bot
229
docs/infrastructure/service-dependency-map.md
Normal file
229
docs/infrastructure/service-dependency-map.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# 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)*
|
||||
Reference in New Issue
Block a user