homelab-optimized/docs/services/HOMARR_SETUP.md

# 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 |