docs: create Netgrimoire/Services/homepage/Configuration

2026-04-10 19:50:27 +00:00 · 2026-04-10 19:50:27 +00:00 · 4c97703fab
commit 4c97703fab
parent b888d6b640
1 changed files with 218 additions and 0 deletions
--- a/Netgrimoire/Services/homepage/Configuration.md
+++ b/Netgrimoire/Services/homepage/Configuration.md
@ -0,0 +1,218 @@
+---
+title: Homepage Final Config
+description: 
+published: true
+date: 2026-04-10T19:50:17.672Z
+tags: 
+editor: markdown
+dateCreated: 2026-04-10T19:50:17.672Z
+---
+
+# Homepage Configuration — Netgrimoire Command Center
+
+## Overview
+
+Homepage (`ghcr.io/gethomepage/homepage`) runs as a Docker Swarm service on `znas`, pinned to port `3056:3000` and accessible at `https://homepage.netgrimoire.com`.
+
+Config files live at `/DockerVol/homepage/config/`. Images live at `/DockerVol/homepage/images/` (mounted as `/app/public/images:ro`).
+
+---
+
+## Tab Structure
+
+| Tab | Groups |
+|-----|--------|
+| Glance | Glance (iframe) |
+| Netgrimoire | Applications, Gremlin, Monitoring, Management, Backup, Mail Services, Remote Access, Services |
+| PNCHarris | PNCHarris Apps |
+| Wasted-Bandwidth | Jolly Roger, Downloaders, VPN Protected Apps, Media Management, Media Search |
+| Nucking-Futz | Nucking Apps, Entertainment |
+
+---
+
+## Compose File
+
+```yaml
+# swarm/homepage.yaml
+services:
+  homepage:
+    image: ghcr.io/gethomepage/homepage:latest
+    environment:
+      - HOMEPAGE_ALLOWED_HOSTS=homepage.netgrimoire.com,glance.netgrimoire.com
+      - HOMEPAGE_VAR_MAILCOW_KEY=<mailcow-api-key>
+      - HOMEPAGE_VAR_DNS_TOKEN=<technitium-token>
+      - HOMEPAGE_VAR_OPNSENSE_USER=<opnsense-api-key>
+      - HOMEPAGE_VAR_OPNSENSE_PASS=<opnsense-api-secret>
+      - HOMEPAGE_VAR_IMMICH_KEY=<immich-api-key>
+    ports:
+      - 3056:3000
+    volumes:
+      - /DockerVol/homepage/config:/app/config
+      - /DockerVol/homepage/images:/app/public/images:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    networks:
+      - netgrimoire
+    deploy:
+      placement:
+        constraints:
+          - node.hostname == znas
+      labels:
+        caddy: homepage.netgrimoire.com
+        caddy.reverse_proxy: homepage:3000
+        caddy.import: crowdsec
+        caddy.import_1: authentik
+        kuma.homepage.http.name: Homepage
+        kuma.homepage.http.url: https://homepage.netgrimoire.com
+        diun.enable: "true"
+```
+
+**Important:** API keys go directly in the `environment:` block (not `env_file:`) because Docker Swarm's `env_file` is only read at deploy time from the deploying machine — not by the container at runtime.
+
+---
+
+## API Keys
+
+| Variable | Source | Where to Generate |
+|----------|--------|-------------------|
+| `HOMEPAGE_VAR_MAILCOW_KEY` | Mailcow | Admin UI → API |
+| `HOMEPAGE_VAR_DNS_TOKEN` | Technitium | Administration → API Tokens |
+| `HOMEPAGE_VAR_OPNSENSE_USER` | OPNsense API key | System → Access → Users → edit user → API Keys |
+| `HOMEPAGE_VAR_OPNSENSE_PASS` | OPNsense API secret | Same as above (one-time download) |
+| `HOMEPAGE_VAR_IMMICH_KEY` | Immich | User Settings → API Keys |
+
+**OPNsense note:** The widget uses API key/secret pairs, not admin credentials. Create a dedicated `homepage` user with Audit group membership and generate an API key on that user.
+
+---
+
+## settings.yaml — Group Layout
+
+All groups must be registered in `settings.yaml` with `style: column`. Any group discovered via Docker labels that is **not** listed here will default to full-width (stretching across all columns).
+
+```yaml
+layout:
+  Glance:
+    tab: Glance
+    header: false
+  Applications:
+    tab: Netgrimoire
+    style: column
+  Gremlin:
+    tab: Netgrimoire
+    style: column
+  # ... all groups must be listed
+```
+
+**Rule:** Whenever you add a new `homepage.group=Something` label to a Swarm service, add a matching entry to `settings.yaml`.
+
+---
+
+## widgets.yaml — Global Info Bar
+
+```yaml
+- logo:
+    icon: /images/gremlin-badge.png
+
+- greeting:
+    text_size: xl
+    text: "NetGrimoire"
+
+- datetime:
+    text_size: l
+    format:
+      dateStyle: long
+      timeStyle: short
+      hour12: true
+
+- resources:
+    label: ZNAS
+    cpu: true
+    memory: true
+    disk: /
+    uptime: true
+    refresh: 5000
+
+- resources:
+    label: Hermes
+    cpu: true
+    memory: true
+    cputemp: true
+    uptime: true
+    refresh: 5000
+
+- resources:
+    label: Docker5
+    cpu: true
+    memory: true
+    uptime: true
+    refresh: 5000
+
+- openmeteo:
+    label: Pensacola
+    latitude: 30.42
+    longitude: -87.21
+    units: imperial
+    cache: 5
+
+- search:
+    provider: duckduckgo
+    target: _blank
+```
+
+**Note:** Resource widgets currently show stats for the Homepage host only. Deploy the Homepage agent on each node for true per-node metrics.
+
+---
+
+## Branding — Gremlin Images
+
+| File | Usage |
+|------|-------|
+| `/DockerVol/homepage/images/gremlin-badge.png` | Logo widget (circular badge) |
+| `/DockerVol/homepage/images/gremlin-scene.png` | Gremlin AI service card background |
+
+After adding new images, restart the Homepage container — Next.js static server does not pick up new files without a restart.
+
+---
+
+## Service Widgets
+
+| Service | Widget Type | URL |
+|---------|-------------|-----|
+| Mailcow | `customapi` | `http://192.168.5.16/api/v1/get/domain/all` |
+| Technitium | `customapi` | `http://192.168.5.7:5380/api/dashboard/stats/get` |
+| OPNsense | `opnsense` | `https://192.168.3.4:8443` |
+| Immich | `immich` | `https://immich.netgrimoire.com` |
+| Jackett | `jackett` | `http://gluetun:9117` |
+| Radarr | `radarr` | `http://radarr:7878` |
+| Sonarr | `sonarr` | `http://sonarr:8989` |
+| SABnzbd | `sabnzbd` | `http://sabnzbd:8080` |
+
+**Mailcow widget note:** The native `mailcow` widget type is broken with Mailcow 2025+ (API endpoint `/api/v1/get/mailboxes` was removed). Use `customapi` pointing at `/api/v1/get/domain/all` instead.
+
+---
+
+## custom.css — Key Sections
+
+The CSS uses a Netgrimoire dark ops aesthetic with per-tab color theming:
+
+| Tab | Accent Color |
+|-----|-------------|
+| Netgrimoire | Teal (`#00e5cc`) |
+| Wasted-Bandwidth | Amber (`#ffaa00`) |
+| Nucking-Futz | Red (`#ff4455`) |
+| PNCHarris | Teal (narrow column layout) |
+
+**Critical fix:** `html, body, body > div { background-color: transparent !important; }` must be present or Homepage's root div paints over the body background, hiding tab background images.
+
+**Card layout:** Groups use `style: column` in settings.yaml. The CSS does not override the grid — Homepage's own Tailwind layout handles column placement.
+
+---
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Card stretches full width | Group not in settings.yaml | Add group with `style: column` |
+| Background image not showing | Missing transparent fix in CSS | Add `html, body, body > div { background-color: transparent !important }` |
+| Widget shows API error | Wrong URL or missing API key | Check env vars and use internal container URLs |
+| Logo not showing | Image not in `/app/public/images` | Copy to `/DockerVol/homepage/images/` and restart container |
+| New image not loading | Next.js static cache | Restart the Homepage container after adding images |