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