diff --git a/Netgrimoire/Services/homepage/updates.md b/Netgrimoire/Services/homepage/updates.md new file mode 100644 index 0000000..009c2e0 --- /dev/null +++ b/Netgrimoire/Services/homepage/updates.md @@ -0,0 +1,752 @@ +--- +title: Homepage Updates +description: +published: true +date: 2026-04-04T02:08:35.780Z +tags: +editor: markdown +dateCreated: 2026-04-04T02:08:35.780Z +--- + +# Homepage Enhancement Guide — NetGrimoire Command Center + +## Overview + +This guide transforms Homepage from a simple service menu into an active monitoring and command center for NetGrimoire. The enhanced Homepage will display real-time infrastructure status, AI-driven insights from Gremlin, alert feeds, and actionable quick actions. + +--- + +## Current State Analysis + +**Your existing Homepage setup:** +- **Tab structure:** Glance (iframe), Netgrimoire, Wasted-Bandwidth, PNCHarris, Nucking-Futz +- **Custom styling:** Per-tab backgrounds, custom CSS/JS for theming +- **Service organization:** Groups by domain/purpose +- **Glance integration:** Full-screen iframe on first tab + +**What's missing:** +- Real-time monitoring data (CPU, RAM, service status) +- Alert/notification feeds +- AI-driven insights +- Quick action buttons +- At-a-glance infrastructure health + +--- + +## Enhancement Strategy + +### 1. Add Global Widgets (Top of Every Tab) + +Create `widgets.yaml` to display persistent monitoring data: + +```yaml +--- +# widgets.yaml - Global widgets appearing at top of every tab + +- logo: + icon: /images/gremlin.png + +- greeting: + text_size: xl + text: "NetGrimoire" + +- datetime: + text_size: xl + format: + dateStyle: short + timeStyle: short + hour12: true + +- search: + provider: duckduckgo + target: _blank + +# Resource monitoring for key nodes +- resources: + label: ZNAS + cpu: true + memory: true + disk: / + uptime: true + +- resources: + label: Docker4-Hermes + cpu: true + memory: true + cputemp: true + uptime: true + +- resources: + label: Docker5 + cpu: true + memory: true + uptime: true + +# Weather widget (using your existing API key) +- openmeteo: + label: Pensacola + latitude: 30.42 + longitude: -87.21 + units: imperial + cache: 5 +``` + +--- + +### 2. Enhanced Services with Native Widgets + +Update `services.yaml` to add monitoring widgets where Homepage has native support: + +```yaml +--- +# Enhanced services.yaml with monitoring widgets + +# ============================================================ +# MONITORING GROUP +# ============================================================ + +- Monitoring: + - Service Uptime Kuma: + href: https://kuma.netgrimoire.com + name: Uptime Kuma + icon: uptime-kuma.png + description: Service Monitoring + widget: + type: uptimekuma + url: https://kuma.netgrimoire.com + slug: default + + - Service Beszel: + href: https://beszel.netgrimoire.com + name: Beszel + icon: beszel.png + description: Container Resources + widget: + type: iframe + src: https://beszel.netgrimoire.com + height: 400 + + - Service Portainer: + href: https://portainer.netgrimoire.com + name: Portainer + icon: portainer.png + description: Docker Management + widget: + type: portainer + url: https://portainer.netgrimoire.com + env: 2 # Swarm environment ID + key: {{HOMEPAGE_VAR_PORTAINER_KEY}} + + - Service Graylog: + href: https://log.netgrimoire.com + name: Graylog + icon: graylog.png + description: Log Aggregation + + - Service LibreNMS: + href: http://npm.netgrimoire.com + name: LibreNMS + icon: librenms.png + description: Network Monitoring + + - Service Scrutiny: + href: https://scrutiny.netgrimoire.com + name: Scrutiny + icon: scrutiny.png + description: S.M.A.R.T Monitoring + +# ============================================================ +# APPLICATIONS GROUP +# ============================================================ + +- Applications: + - Service Gremlin: + href: https://gremlin.netgrimoire.com + name: Gremlin AI + icon: /images/gremlin.png + description: NetGrimoire Intelligence + widget: + type: customapi + url: http://gremlin-n8n:5678/webhook/homepage-status + method: GET + mappings: + - field: status + label: Status + - field: suggestion + label: Gremlin Says + + - Service Wiki: + href: https://wiki.netgrimoire.com + name: Wiki.js + icon: wikijs.png + description: Documentation + + - Service Forgejo: + href: https://git.netgrimoire.com + name: Forgejo + icon: forgejo.png + description: Git Repository + + - Service ntfy: + href: https://ntfy.netgrimoire.com + name: ntfy + icon: ntfy.png + description: Notifications + widget: + type: iframe + src: https://ntfy.netgrimoire.com/netgrimoire-alerts + height: 300 + + - Service Dozzle: + href: https://dozzle.netgrimoire.com + name: Dozzle + icon: dozzle.png + description: Container Logs + +# ============================================================ +# MANAGEMENT GROUP +# ============================================================ + +- Management: + - Service Mailcow: + href: http://mail.netgrimoire.com + name: Mailcow + icon: mailcow.png + description: Mail Server + widget: + type: mailcow + url: https://mail.netgrimoire.com + key: A63910-D8FDE0-881C97-E5EE2B-232847 + + - Service Technitium: + href: https://dns.netgrimoire.com + name: Technitium DNS + icon: technitium.png + description: DNS Server + widget: + type: customapi + url: http://192.168.5.7:5380/api/dashboard/stats/get?token={{HOMEPAGE_VAR_DNS_TOKEN}} + mappings: + - field: response.totalQueries + label: Queries (24h) + - field: response.totalNoError + label: Successful + - field: response.totalBlocked + label: Blocked + + - Service OPNsense: + href: https://192.168.3.4:8443 + name: OPNsense Firewall + icon: opnsense.png + description: Internal Only + widget: + type: opnsense + url: https://192.168.3.4:8443 + username: {{HOMEPAGE_VAR_OPNSENSE_USER}} + password: {{HOMEPAGE_VAR_OPNSENSE_PASS}} + + - Service TPLink: + href: http://192.168.5.6 + name: TPLink Switch + icon: tp-link.png + description: Internal Only + + - Service Switch: + href: http://192.168.5.1 + name: Ubiquity Switch + icon: ubiquiti.png + description: Internal Only + +# ============================================================ +# PNCHARRIS APPS +# ============================================================ + +- PNCHarris Apps: + - Service Immich: + href: https://immich.netgrimoire.com + name: Immich + icon: immich.png + description: Photo Management + widget: + type: immich + url: https://immich.netgrimoire.com + key: {{HOMEPAGE_VAR_IMMICH_KEY}} + +# ============================================================ +# REMOTE ACCESS +# ============================================================ + +- Remote Access: + - Service Webtop: + href: https://webtop.netgrimoire.com + name: Webtop + icon: webtop.png + description: Remote XFCE + + - Service Windows: + href: https://win.netgrimoire.com + name: PlaySkool + icon: windows-11.png + description: Windows + +# ============================================================ +# VPN PROTECTED APPS +# ============================================================ + +- VPN Protected Apps: + - Service Jackett: + href: https://jackett.netgrimoire.com + name: Jackett + icon: jackett.png + description: Torrent Indexer + widget: + type: jackett + url: http://gluetun:9117 + + - Service Transmission: + href: https://transmission.netgrimoire.com + name: Transmission + icon: transmission.png + description: BitTorrent Client + +# ============================================================ +# MEDIA MANAGEMENT +# ============================================================ + +- Media Management: + - Service Calibre: + href: https://calibre.netgrimoire.com + name: Calibre + icon: calibre.png + description: Ebook Library + +# ============================================================ +# GLANCE TAB (KEEP EXISTING) +# ============================================================ + +- Glance: + - Glance: + href: https://home.netgrimoire.com + widget: + type: iframe + name: glance + src: https://home.netgrimoire.com + height: 1200 + +# ============================================================ +# NUCKING APPS +# ============================================================ + +- Nucking Apps: + - Service Greenfin: + href: http://jellyfin.netgrimoire.com:7096 + name: GreenFin + icon: jellyfin.png + + - Service Stashapp: + href: https://stash.wasted-bandwidth.net + name: Stashapp + icon: sh-stash.svg + + - Service Namer: + href: https://namer.wasted-bandwidth.net + name: Namer + icon: sh-namecheap.svg +``` + +--- + +### 3. Gremlin AI Widget Integration + +**Purpose:** Gremlin analyzes infrastructure and provides actionable insights directly on Homepage. + +**n8n Workflow: Homepage Status Feed** + +Create this workflow in n8n: + +**Workflow Name:** `Homepage Status Feed` + +**Nodes:** + +1. **Webhook Trigger** + - Path: `homepage-status` + - Method: GET + - Response mode: Response Node + +2. **Get Uptime Kuma Status** + - Type: HTTP Request + - URL: `https://kuma.netgrimoire.com/api/status-page/default` + - Method: GET + +3. **Get Beszel Metrics** (if API available) + - Type: HTTP Request + - URL: `https://beszel.netgrimoire.com/api/systems` + - Method: GET + - Authentication: As configured + +4. **Analyze with Ollama** + - Type: HTTP Request + - URL: `http://gremlin-ollama:11434/api/generate` + - Method: POST + - Body: + ```json + { + "model": "llama3.2", + "prompt": "Analyze this infrastructure status and provide a brief summary (max 2 sentences):\n\nUptime Kuma: {{ $json.kumaData }}\nBeszel: {{ $json.beszelData }}\n\nProvide actionable insights if there are issues, otherwise confirm all systems operational.", + "stream": false + } + ``` + +5. **Format Response** + - Type: Code + - Code: + ```javascript + return [{ + json: { + status: "operational", + suggestion: $input.first().json.response + } + }]; + ``` + +6. **Respond to Webhook** + - Type: Respond to Webhook + - Return the formatted JSON + +**Workflow runs every time Homepage loads and displays Gremlin's analysis.** + +--- + +### 4. Quick Actions Section + +Add bookmarks with `sendPrompt()` integration for common tasks: + +```yaml +# Add to services.yaml under a new "Quick Actions" group +- Quick Actions: + - Emergency Runbooks: + href: https://wiki.netgrimoire.com/emergency + icon: si-readthedocs + description: Wiki.js emergency procedures + + - Forgejo Compose Archive: + href: https://git.netgrimoire.com/traveler/Netgrimoire + icon: forgejo.png + description: Source of truth for stack files + + - OPNsense Logs: + href: https://192.168.3.4:8443/ui/diagnostics/log/core + icon: opnsense.png + description: Firewall logs + + - Gremlin Audits: + href: https://git.netgrimoire.com/Netgrimoire/Audits + icon: /images/gremlin.png + description: AI-generated audit reports +``` + +--- + +### 5. Enhanced Custom CSS + +Update `custom.css` to improve widget visibility and styling: + +```css +/* custom.css */ + +/* Base background behavior */ +body { + background-size: cover !important; + background-position: center center !important; + background-attachment: fixed !important; +} + +/* Per-tab backgrounds (keep existing) */ +body.tab-glance { + background-image: url("/images/bg-glance.jpg") !important; +} + +body.tab-pncharris { + background-image: url("/images/pncharris-bg.png") !important; +} + +body.tab-netgrimoire { + background-image: url("/images/Netgrimoire-bg.png") !important; +} + +body.tab-wasted-bandwidth { + background-image: url("/images/Wasted-bandwidth-bg.png") !important; +} + +body.tab-nucking-futz { + background-image: url("/images/Nucking-futz-bg.png") !important; +} + +/* Readability / tone-down layer */ +#page-wrapper { + background-color: rgba(0, 0, 0, 0.40); +} + +/* Enhanced widget visibility */ +.widget { + background: rgba(20, 20, 20, 0.85) !important; + backdrop-filter: blur(8px); + border: 1px solid rgba(0, 255, 255, 0.2); + box-shadow: 0 4px 6px rgba(0, 0, 0, 0.3); + border-radius: 10px; +} + +/* Gremlin widget special styling */ +.widget[data-widget-type="customapi"] { + border-color: rgba(0, 255, 255, 0.5); + background: rgba(10, 40, 40, 0.85) !important; +} + +/* Service cards */ +.service-card { + background: rgba(20, 20, 20, 0.70) !important; + backdrop-filter: blur(2px); + border-radius: 10px; +} + +/* ntfy widget styling */ +.ntfy-widget { + border-radius: 8px; + overflow: hidden; +} + +/* Resource widgets grid layout */ +.resources-widget { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); + gap: 12px; +} + +/* Monitoring status indicators */ +.status-ok { + color: #00ff00; +} + +.status-warn { + color: #ffaa00; +} + +.status-critical { + color: #ff0000; +} + +/* PNCHarris: narrow centered column (keep existing) */ +body.tab-pncharris main { + max-width: 900px; + margin: 0 auto !important; + padding-left: 16px; + padding-right: 16px; +} + +body.tab-pncharris section, +body.tab-pncharris .group { + max-width: 900px; + margin-left: auto !important; + margin-right: auto !important; +} + +body.tab-pncharris .service-card, +body.tab-pncharris .widget { + width: auto !important; + max-width: 100% !important; +} + +/* Glance tab fullscreen (keep existing) */ +body.tab-glance main { + max-width: none !important; + margin: 0 !important; + padding-left: 12px !important; + padding-right: 12px !important; +} + +body.tab-glance .service-grid, +body.tab-glance .services { + grid-template-columns: 1fr !important; +} + +body.tab-glance iframe[name="glance"], +body.tab-glance iframe[src*="home.netgrimoire.com"] { + width: 100% !important; + height: calc(100vh - 170px) !important; + border: 0 !important; + display: block !important; +} +``` + +--- + +### 6. API Keys and Secrets + +Create `secrets.env` (keep out of git): + +```env +# Homepage API Keys +HOMEPAGE_VAR_PORTAINER_KEY=ptr_yourkey +HOMEPAGE_VAR_IMMICH_KEY=yourimmichkey +HOMEPAGE_VAR_OPNSENSE_USER=apiuser +HOMEPAGE_VAR_OPNSENSE_PASS=apipass +HOMEPAGE_VAR_DNS_TOKEN=yourtechnitiumtoken +``` + +Reference in Homepage config via environment variables. + +--- + +## Benefits Summary + +**What this enhancement delivers:** + +1. **At-a-glance infrastructure status** + - Resource usage (CPU/RAM/disk) for key nodes + - Service up/down counts + - No clicking required + +2. **AI-driven insights** + - Gremlin analyzes Uptime Kuma + Beszel data + - Surfaces actionable recommendations + - "Docker3 CPU at 92%, check Transmission logs" + +3. **Real-time alerts** + - ntfy feed embedded directly in Homepage + - CrowdSec blocks, backup completions, OPNsense events + - No tab switching needed + +4. **Native monitoring widgets** + - Uptime Kuma status grid + - Portainer container stats + - Mailcow queue status + - OPNsense firewall activity + - Technitium DNS query stats + +5. **Quick actions** + - One-click access to emergency runbooks + - Direct links to Forgejo compose archive + - Gremlin audit report generation + - OPNsense log access + +--- + +## Recommended Services to Add + +### High Priority + +1. **Dozzle** - Live container log viewer + - Deployed: See separate deployment guide + - Integration: Already in services.yaml above + +2. **Grafana + Prometheus** - Unified metrics dashboard + - Pulls from Beszel, LibreNMS, Technitium + - Historical trends and custom alerting + - Gremlin can query Grafana API for analysis + +3. **Changedetection.io** - Website change monitoring + - Track vendor status pages + - Monitor documentation updates + - Webhook to n8n → Gremlin summarizes changes + +### Medium Priority + +4. **Netdata** - Real-time per-process monitoring + - When Beszel shows high CPU, Netdata tells you which process + - Complements Beszel's container-level view + +5. **Wallos** - Subscription/renewal tracker + - Domain renewals, MXRoute subscription, SSL certs + - Budget forecasting + - ntfy alerts before renewals + +6. **Uptime Kuma Status Page** (already have Uptime Kuma) + - Public status page at `status.netgrimoire.com` + - Shows uptime for key services + - Incident history + +### Nice to Have + +7. **DIUN webhook to ntfy** - Image update notifications + - Already have DIUN labels on services + - Just wire webhook to ntfy + - n8n workflow: "New image available → check changelog → summarize" + +8. **Authentik LDAP/RADIUS enhancement** + - Already have Authentik + - Add: OPNsense admin auth, WireGuard user management, Technitium DNS auth + +--- + +## Implementation Checklist + +- [ ] Create `widgets.yaml` with resource monitors and weather +- [ ] Update `services.yaml` with monitoring widgets +- [ ] Deploy Gremlin n8n workflow for Homepage status endpoint +- [ ] Update `custom.css` with enhanced widget styling +- [ ] Create `secrets.env` with API keys +- [ ] Test Gremlin widget integration +- [ ] Deploy Dozzle for log viewing +- [ ] Configure ntfy iframe widget +- [ ] Set up Uptime Kuma widget (requires API key) +- [ ] Configure Portainer widget (requires API key) +- [ ] Test all widgets on Netgrimoire tab +- [ ] Document API key generation steps +- [ ] Add quick action bookmarks + +--- + +## Next Steps + +1. **Start with widgets.yaml** - Add global resource monitors +2. **Deploy Gremlin n8n workflow** - Get AI insights working first +3. **Update services.yaml incrementally** - Add widgets to existing services +4. **Test each widget** - Verify API keys and connectivity +5. **Iterate on styling** - Adjust custom.css for readability + +--- + +## Troubleshooting + +**Widget not displaying:** +- Check API key is correct in secrets.env +- Verify service URL is accessible from Homepage container +- Check Homepage logs: `docker logs ` + +**Gremlin widget shows error:** +- Verify n8n workflow is deployed and active +- Test webhook URL directly: `curl http://gremlin-n8n:5678/webhook/homepage-status` +- Check n8n logs for execution errors + +**Resource widgets not updating:** +- Verify Homepage can access Docker socket or metrics endpoints +- Check resource paths match actual system paths + +**Custom CSS not applying:** +- Clear browser cache +- Verify custom.css is mounted correctly in Homepage container +- Check browser console for CSS syntax errors + +--- + +## References + +- Homepage Documentation: https://gethomepage.dev/ +- Uptime Kuma API: https://github.com/louislam/uptime-kuma/wiki/API +- Portainer API: https://docs.portainer.io/api/ +- Technitium DNS API: https://github.com/TechnitiumSoftware/DnsServer/blob/master/APIDOCS.md +- OPNsense API: https://docs.opnsense.org/development/api.html + +--- + +## Visual Mockup Summary + +The mockup showed: +- **Header:** Gremlin logo, date/time, weather widget +- **Resource cards:** ZNAS, Docker4, Docker5 with CPU/RAM/uptime +- **Gremlin AI widget:** Prominent teal-bordered card with status analysis +- **ntfy alerts:** Recent alerts with color-coded severity +- **Service status grid:** Green/red cards from Uptime Kuma +- **Quick actions:** Button bar for common tasks + +This transforms Homepage from a service directory into an active command center with real-time monitoring, AI insights, and actionable intelligence.