# 🔗 Integrations Guide

## Overview

This guide covers integrating homelab services with external platforms and each other.

---

## 🔐 Authentication Integrations

### Authentik SSO

Integrate services with Authentik for single sign-on:

| Service | Integration Type | Status |
|---------|-----------------|--------|
| Grafana | OAuth2/OIDC | ✅ |
| Portainer | OAuth2 | ✅ |
| Mattermost | OAuth2 | ✅ |
| Seafile | OAuth2 | ✅ |
| Proxmox | LDAP | ✅ |
| Various Apps | Forward Auth | ✅ |

#### Forward Auth Proxy
```nginx
# NPM Advanced Config for Forward Auth
location /outpost.goauthentik.io {
    proxy_pass http://authentik-server:9000/outpost.goauthentik.io;
    proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
}
```

---

## 📱 Mobile App Integrations

### Home Assistant
```yaml
# Integrate with:
# - Smart home devices
# - Presence detection
# - Automation triggers

homeassistant:
  integrations:
    - tailscale   # Remote access
    - ntfy        # Notifications
    - influxdb    # Long-term stats
```

### Immich
```yaml
# Mobile backup settings
immich:
  auto_backup: true
  backup_albums: true
  background_backup: true
```

---

## 📊 Monitoring Integrations

### Prometheus Exporters
```yaml
# Available integrations
exporters:
  node_exporter:      # Linux hosts
  snmp_exporter:      # Synology NAS
  blackbox_exporter:  # HTTP/ICMP probes
  cadvisor:           # Docker containers
  postgres_exporter:  # PostgreSQL
  redis_exporter:     # Redis
```

### Grafana Data Sources
```yaml
datasources:
  - prometheus       # Metrics
  - loki            # Logs
  - influxdb        # Time series
  - postgres        # Direct DB queries
```

---

## ☁️ Cloud Service Integrations

### Cloudflare
```yaml
integrations:
  - DNS management (API)
  - DDoS protection
  - WAF rules
  - Tunnel for secure exposure
  - Zero Trust Access
```

### Backblaze B2
```yaml
# Backup integration
rclone_remote: b2
use_cases:
  - Offsite backups
  - Photo archive
  - Document storage
```

---

## 🎬 Media Integrations

### *Arr Stack Integration
```
Prowlarr (Indexers)
    │
    ├── Sonarr (TV) ──┬── SABnzbd
    ├── Radarr (Movies) ┤
    ├── Lidarr (Music) ─┘── qBittorrent
    └── Readarr (Books)
            │
            ▼
    Plex / Jellyfin (Streaming)
            │
            ▼
    Overseerr (Requests)
```

### Plex Integrations
```yaml
integrations:
  - Tautulli (analytics)
  - Overseerr (requests)
  - PlexTraktSync (watch history)
  - Varken (InfluxDB stats)
```

---

## 💬 Communication Integrations

### Matrix Federation
```yaml
# Enable federation for cross-server chat
federation:
  enabled: true
  servers:
    - matrix.org
    - other-homeservers
```

### Mastodon ActivityPub
```yaml
# Fediverse connections
activitypub:
  enabled: true
  relay: enabled
```

---

## 🔧 API Integrations

### Portainer API
```bash
# Manage containers via API
curl -H "X-API-Key: $API_KEY" \
  http://portainer:9000/api/endpoints/1/docker/containers/json
```

### Home Assistant REST API
```bash
# Trigger automations
curl -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  http://homeassistant:8123/api/services/script/my_script
```

---

## 📚 Further Reading

- [Customization Guide](customization.md)
- [Scaling Guide](scaling.md)
- [Authentik SSO](../infrastructure/authentik-sso.md)
- [Service Architecture](../diagrams/service-architecture.md)
