Sanitized mirror from private repository - 2026-03-20 08:50:12 UTC

2026-03-20 08:50:12 +00:00
commit bccfcaf6e2
1229 changed files with 305715 additions and 0 deletions
--- a/docs/services/HOMARR_SETUP.md
+++ b/docs/services/HOMARR_SETUP.md
@@ -0,0 +1,254 @@
+# Homarr Dashboard Setup Guide
+
+## Overview
+
+This document covers the complete setup of Homarr as a homelab dashboard, including:
+- Deployment on Atlantis (Synology NAS)
+- API-based app and integration configuration
+- NPM reverse proxy with Authentik SSO
+- Dashboard layout and widget configuration
+
+## Architecture
+
+```
+Internet → Cloudflare → NPM (Calypso:443) → Homarr (Atlantis:7575)
+                              ↓
+                        Authentik SSO (Calypso:9000)
+```
+
+## Access URLs
+
+| Service | Internal URL | External URL |
+|---------|--------------|--------------|
+| Homarr | http://atlantis.vish.local:7575 | https://dash.vish.gg |
+| NPM Admin | http://calypso.vish.local:81 | https://npm.vish.gg |
+| Authentik | http://calypso.vish.local:9000 | https://sso.vish.gg |
+
+## DNS Mapping (Split Horizon via Tailscale)
+
+| IP Address | Local DNS |
+|------------|-----------|
+| 192.168.0.80/200 | atlantis.vish.local |
+| 192.168.0.250 | calypso.vish.local |
+| 192.168.0.210 | homelab.vish.local |
+| (NUC) | concordnuc.vish.local |
+
+## Deployment
+
+### Homarr Container (Atlantis)
+
+Homarr runs on Atlantis (192.168.0.200) via Docker, managed via **GitOps** through Portainer:
+
+- **Stack ID**: 523 (homarr-stack)
+- **GitOps Path**: `hosts/synology/atlantis/homarr.yaml`
+- **Auto-Update**: Every 5 minutes
+
+```yaml
+Container: homarr
+Image: ghcr.io/homarr-labs/homarr:latest
+Ports: 7575:7575
+Volumes:
+  - /volume2/metadata/docker/homarr/appdata:/appdata
+  - /var/run/docker.sock:/var/run/docker.sock:ro
+```
+
+### NPM Proxy Configuration
+
+Proxy Host ID: 40
+
+```json
+{
+  "domain_names": ["dash.vish.gg"],
+  "forward_host": "192.168.0.200",
+  "forward_port": 7575,
+  "forward_scheme": "http",
+  "ssl_forced": true,
+  "allow_websocket_upgrade": true,
+  "http2_support": true,
+  "certificate_id": 1
+}
+```
+
+### Authentik Forward Auth
+
+NPM advanced config includes Authentik forward auth using:
+- Provider: "vish.gg Domain Forward Auth" (ID: 5)
+- Mode: forward_domain
+- Cookie Domain: vish.gg (covers all *.vish.gg subdomains)
+
+## Apps (60 Total)
+
+### Atlantis (atlantis.vish.local)
+
+| App | Port | URL |
+|-----|------|-----|
+| Plex | 32400 | http://atlantis.vish.local:32400 |
+| Jellyseerr | 5055 | http://atlantis.vish.local:5055 |
+| Tautulli | 8181 | http://atlantis.vish.local:8181 |
+| Sonarr | 8989 | http://atlantis.vish.local:8989 |
+| Radarr | 7878 | http://atlantis.vish.local:7878 |
+| Lidarr | 8686 | http://atlantis.vish.local:8686 |
+| Prowlarr | 9696 | http://atlantis.vish.local:9696 |
+| Bazarr | 6767 | http://atlantis.vish.local:6767 |
+| SABnzbd | 8080 | http://atlantis.vish.local:8080 |
+| Jackett | 9117 | http://atlantis.vish.local:9117 |
+| Portainer | 10000 | http://vishinator.synology.me:10000 |
+| Vaultwarden | 4080 | http://atlantis.vish.local:4080 |
+| Immich | 8212 | http://atlantis.vish.local:8212 |
+| Joplin | 22300 | http://atlantis.vish.local:22300 |
+| Paperless-NGX | 8777 | http://atlantis.vish.local:8777 |
+| Calibre Web | 8083 | http://atlantis.vish.local:8083 |
+| IT Tools | 5545 | http://atlantis.vish.local:5545 |
+| DokuWiki | 8399 | http://atlantis.vish.local:8399 |
+| Dozzle | 9999 | http://atlantis.vish.local:9999 |
+| Baikal | 12852 | http://atlantis.vish.local:12852 |
+| Wizarr | 5690 | http://atlantis.vish.local:5690 |
+| Proxmox | 8006 | https://proxmox.vish.local:8006 |
+
+### Homelab VM (homelab.vish.local)
+
+| App | Port | URL |
+|-----|------|-----|
+| Grafana | 3300 | http://homelab.vish.local:3300 |
+| Prometheus | 9090 | http://homelab.vish.local:9090 |
+| Redlib | 9000 | http://homelab.vish.local:9000 |
+| Karakeep | 3000 | http://homelab.vish.local:3000 |
+| Binternet | 21544 | http://homelab.vish.local:21544 |
+| Draw.io | 5022 | http://homelab.vish.local:5022 |
+
+### Matrix VM (External URLs)
+
+| App | External URL |
+|-----|--------------|
+| Element | https://matrix.thevish.io |
+| Mattermost | https://mm.crista.love |
+
+### Concord NUC (concordnuc.vish.local)
+
+| App | Port | URL |
+|-----|------|-----|
+| Home Assistant | 8123 | http://concordnuc.vish.local:8123 |
+| AdGuard Home | 3000 | http://concordnuc.vish.local:3000 |
+| Your Spotify | 4000 | http://concordnuc.vish.local:4000 |
+| Invidious | 3001 | http://concordnuc.vish.local:3001 |
+
+### Calypso (calypso.vish.local)
+
+| App | Port | URL |
+|-----|------|-----|
+| Gitea | 3052 | https://git.vish.gg |
+| AdGuard Home | 3000 | http://calypso.vish.local:3000 |
+| Actual Budget | 8304 | http://calypso.vish.local:8304 |
+| Seafile | 8611 | http://calypso.vish.local:8611 |
+
+## Integrations (8 with Live Data)
+
+| Integration | Kind | Features |
+|-------------|------|----------|
+| Sonarr | sonarr | Queue, Calendar |
+| Radarr | radarr | Queue, Calendar |
+| Lidarr | lidarr | Queue, Calendar |
+| Prowlarr | prowlarr | Indexer Status |
+| SABnzbd | sabNzbd | Download Speed, Queue |
+| Plex | plex | Now Playing |
+| Jellyseerr | jellyseerr | Pending Requests |
+| Home Assistant | homeAssistant | Entities, Sensors |
+
+## Widgets
+
+The dashboard includes these live widgets:
+
+| Widget | Integration | Shows |
+|--------|-------------|-------|
+| 📅 Release Calendar | Sonarr, Radarr, Lidarr | Upcoming TV/Movie/Music releases |
+| 📥 Downloads | SABnzbd | Current download speed & queue |
+| 🎬 Now Playing | Plex | Currently streaming media |
+| 📺 Media Requests | Jellyseerr | Pending media requests |
+| 🏠 Smart Home | Home Assistant | Entity states |
+| 🕐 Clock | - | Current time & date |
+
+## Dashboard Layout Guide
+
+### Recommended Structure
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    📅 CALENDAR WIDGET                        │
+│            (Shows upcoming releases from Sonarr/Radarr)      │
+├───────────────────┬─────────────────────┬───────────────────┤
+│   📺 MEDIA        │   📥 DOWNLOADS      │   🏠 SMART HOME   │
+│ • Plex            │ • Sonarr            │ • Home Assistant  │
+│ • Jellyseerr      │ • Radarr            │ • AdGuard         │
+│ • Tautulli        │ • SABnzbd           │                   │
+├───────────────────┼─────────────────────┼───────────────────┤
+│  🖥️ INFRA         │  📊 MONITORING      │  🔧 TOOLS         │
+│ • Portainer       │ • Grafana           │ • IT Tools        │
+│ • Gitea           │ • Prometheus        │ • Draw.io         │
+├───────────────────┴─────────────────────┴───────────────────┤
+│  📥 DOWNLOAD SPEED    │    🎬 NOW PLAYING WIDGET            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Setup Steps
+
+1. **Create Board**: Manage → Boards → New Board → "Homelab"
+2. **Enter Edit Mode**: Click pencil icon
+3. **Add Sections**: + Add → Section (Media, Downloads, etc.)
+4. **Add Apps**: + Add → App → Select from list
+5. **Add Widgets**: + Add → Widget → Configure integrations
+6. **Save**: Click checkmark to exit edit mode
+
+### Key Widgets
+
+- **Calendar**: Shows Sonarr/Radarr upcoming releases
+- **Downloads**: SABnzbd speed and queue
+- **Media Server**: Plex now playing
+- **Health Monitoring**: Service status
+
+## Backup & Maintenance
+
+### Database Location
+```
+/volume2/metadata/docker/homarr/appdata/db/db.sqlite
+```
+
+### Backup Command
+```bash
+cp db.sqlite db.sqlite.backup.$(date +%Y%m%d)
+```
+
+### Update Homarr
+```bash
+docker pull ghcr.io/homarr-labs/homarr:latest
+docker restart homarr
+```
+
+## API Reference
+
+### Create App
+```bash
+curl -X POST "http://localhost:7575/api/trpc/app.create" \
+  -H "ApiKey: <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"name":"App","description":"Desc","iconUrl":"...","href":"...","pingUrl":"..."}}'
+```
+
+### Create Integration
+```bash
+curl -X POST "http://localhost:7575/api/trpc/integration.create" \
+  -H "ApiKey: <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"json":{"name":"Name","kind":"sonarr","url":"...","secrets":[{"kind":"apiKey","value":"..."}],"attemptSearchEngineCreation":false}}'
+```
+
+### Valid Integration Kinds
+`sabNzbd`, `nzbGet`, `sonarr`, `radarr`, `lidarr`, `prowlarr`, `plex`, `jellyseerr`, `homeAssistant`, `adGuardHome`, `proxmox`, `piHole`
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "No home board found" | Create board, set as home |
+| Integration no data | Verify API keys |
+| Auth redirect loop | Clear vish.gg cookies |
+| Websocket errors | Ensure NPM has websockets enabled |