New Grimoire

Watch-Grimoire/Dashboards/Homepage.md

@@ -0,0 +1,90 @@
+---
+title: Homepage Dashboard
+description: Homepage configuration — tabs, groups, widgets, API keys
+published: true
+date: 2026-04-12T00:00:00.000Z
+tags: watch, homepage, dashboard
+editor: markdown
+dateCreated: 2026-04-12T00:00:00.000Z
+---
+
+# Homepage Dashboard
+
+Homepage runs at `homepage.netgrimoire.com`, port 3056:3000. Config lives at `/DockerVol/homepage/config/`. Images at `/DockerVol/homepage/images/` (mounted as `/app/public/images:ro`).
+
+---
+
+## Tab Structure
+
+| Tab | Grimoire | Groups |
+|-----|----------|--------|
+| Glance | — | Glance iframe (full-screen) |
+| Netgrimoire | Netgrimoire | Applications, Gremlin, Monitoring, Management, Backup, Mail Services, Remote Access, Services |
+| Wasted-Bandwidth | Shadow Grimoire | Jolly Roger, Downloaders, VPN Protected Apps, Media Management, Media Search |
+| Nucking-Futz | Green Grimoire | Nucking Apps, Entertainment |
+| PNCHarris | PNC Harris | PNCHarris Apps |
+
+---
+
+## Branding
+
+All badge images live at `/DockerVol/homepage/images/` and are served at `/images/<filename>`.
+
+| File | Used For |
+|------|----------|
+| `netgrimoire-badge.png` | Netgrimoire logo widget |
+| `gremlin-badge.png` | Gremlin service card |
+| `keystone-badge.png` | Keystone Grimoire |
+| `vault-badge.png` | Vault Grimoire |
+| `ward-badge.png` | Ward Grimoire |
+| `watch-badge.png` | Watch Grimoire |
+| `shadow-badge.png` | Shadow Grimoire |
+| `green-badge.png` | Green Grimoire |
+| `pocket-badge.png` | Pocket Grimoire |
+| `pncharris-badge.png` | PNC Harris |
+| `pncfish-badge.png` | PNC Fish |
+
+After adding images, restart Homepage — Next.js does not pick up new files without restart.
+
+---
+
+## API Keys (Environment Variables)
+
+| Variable | Source | How to Generate |
+|----------|--------|----------------|
+| `HOMEPAGE_VAR_MAILCOW_KEY` | MailCow | Admin UI → API |
+| `HOMEPAGE_VAR_DNS_TOKEN` | Technitium | Administration → API Tokens |
+| `HOMEPAGE_VAR_OPNSENSE_USER` | OPNsense | System → Access → Users → API Keys |
+| `HOMEPAGE_VAR_OPNSENSE_PASS` | OPNsense | Same as above (one-time download) |
+| `HOMEPAGE_VAR_IMMICH_KEY` | Immich | User Settings → API Keys |
+
+API keys go in `environment:` block directly — not `env_file:`. Swarm `env_file` is only read at deploy time, not by the running container.
+
+---
+
+## settings.yaml Rule
+
+Every `homepage.group=Something` Docker label **must** have a matching entry in `settings.yaml` with `style: column`. Groups not listed default to full-width and break the layout.
+
+---
+
+## Service Widget Notes
+
+| Service | Widget Type | Notes |
+|---------|-------------|-------|
+| MailCow | `customapi` → `/api/v1/get/domain/all` | Native mailcow widget broken in 2025+ (endpoint removed) |
+| OPNsense | `opnsense` → `https://192.168.3.4:8443` | Requires dedicated homepage API user with Audit group |
+| Technitium | `customapi` → `:5380/api/dashboard/stats/get` | Returns queries, blocked, successful counts |
+| Immich | `immich` | Key via `HOMEPAGE_VAR_IMMICH_KEY` |
+
+---
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Card stretches full width | Group not in settings.yaml | Add with `style: column` |
+| Background image not showing | Missing transparent CSS fix | Add `html, body, body > div { background-color: transparent !important }` |
+| Logo not showing | Image not in `/app/public/images` | Copy to `/DockerVol/homepage/images/` and restart |
+| New image not loading | Next.js static cache | Restart Homepage container |
+| Widget API error | Wrong URL or missing key | Check env vars, use internal container URLs |