From 4c97703fab1e9dcc5bcd99e81413cf72a81d674a Mon Sep 17 00:00:00 2001 From: Administrator Date: Fri, 10 Apr 2026 19:50:27 +0000 Subject: [PATCH 1/2] docs: create Netgrimoire/Services/homepage/Configuration --- .../Services/homepage/Configuration.md | 218 ++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 Netgrimoire/Services/homepage/Configuration.md diff --git a/Netgrimoire/Services/homepage/Configuration.md b/Netgrimoire/Services/homepage/Configuration.md new file mode 100644 index 0000000..83f6f5c --- /dev/null +++ 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= + - HOMEPAGE_VAR_DNS_TOKEN= + - HOMEPAGE_VAR_OPNSENSE_USER= + - HOMEPAGE_VAR_OPNSENSE_PASS= + - HOMEPAGE_VAR_IMMICH_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 | From 860725a9bb193fad2ce217676d6962ca24076556 Mon Sep 17 00:00:00 2001 From: Administrator Date: Fri, 10 Apr 2026 19:53:31 +0000 Subject: [PATCH 2/2] docs: create Netgrimoire/Infrastructure/Docker_Template --- Netgrimoire/Infrastructure/Docker_Template.md | 205 ++++++++++++++++++ 1 file changed, 205 insertions(+) create mode 100644 Netgrimoire/Infrastructure/Docker_Template.md diff --git a/Netgrimoire/Infrastructure/Docker_Template.md b/Netgrimoire/Infrastructure/Docker_Template.md new file mode 100644 index 0000000..6ed094e --- /dev/null +++ b/Netgrimoire/Infrastructure/Docker_Template.md @@ -0,0 +1,205 @@ +--- +title: Docker Template +description: Swarm and Compose Template +published: true +date: 2026-04-10T19:53:21.433Z +tags: +editor: markdown +dateCreated: 2026-04-10T19:53:21.433Z +--- + +# Docker Swarm Template Standard — Netgrimoire + +## Template + +```yaml +# Run with docker stack deploy -c .yaml +services: + : + image: :latest + environment: + TZ: America/Chicago + volumes: + - /DockerVol/:/config # use WITH placement constraint + # - /data/nfs/znas/Docker/:/data # use for bulk/data or no constraint + networks: + - netgrimoire + deploy: + restart_policy: + condition: any + delay: 5s + max_attempts: 3 + window: 120s + placement: + constraints: + - node.platform.arch != aarch64 + - node.platform.arch != arm + labels: + # --- Caddy --- + caddy: .netgrimoire.com + caddy.reverse_proxy: : + caddy.import: crowdsec + caddy.import_1: authentik + + # --- Uptime Kuma --- + kuma..http.name: + kuma..http.url: https://.netgrimoire.com + + # --- Homepage --- + homepage.group: + homepage.name: + homepage.icon: .png + homepage.href: https://.netgrimoire.com + homepage.description: + + # --- DIUN --- + diun.enable: "true" + +networks: + netgrimoire: + external: true +``` + +--- + +## Rules + +### Forbidden Fields +Never use these at the service level: +- `version:` — deprecated in Compose v2+ +- `container_name:` — incompatible with Swarm replicas +- `restart:` — use `deploy.restart_policy` instead +- `depends_on:` — not supported in Swarm mode + +### Volume Path Rules + +| Path | When to Use | +|------|------------| +| `/DockerVol/` | Config/state files. **Only valid when a placement constraint pins the service to a specific host.** | +| `/data/nfs/znas/Docker/` | Data/bulk volumes, or any service without a specific hostname constraint | + +### Caddy Labels + +```yaml +caddy: service.netgrimoire.com +caddy.reverse_proxy: servicename:PORT +caddy.import: crowdsec +caddy.import_1: authentik +``` + +- `caddy.import_1` is required for the second import — duplicate YAML keys cause deploy errors +- `caddy.reverse_proxy` uses `servicename:PORT` (internal Docker DNS), never `{{upstreams PORT}}` +- No `https://` prefix on the `caddy:` address line +- Services managed by Caddyfile (static config) must **not** also have Caddy Docker labels — mixing causes caddy-docker-proxy to merge them into a malformed upstream pool + +### Networking + +- Default VIP mode for services that publish ports +- `endpoint_mode: dnsrr` for internal-only services (no published ports) — avoids Swarm VIP stale DNS +- **Never use `dnsrr` on services with published ports** — incompatible with ingress mesh routing + +### Placement Constraints + +**Architecture exclusions** (always include unless ARM-specific): +```yaml +constraints: + - node.platform.arch != aarch64 # Pi 4 reports aarch64 + - node.platform.arch != arm # Pi 3 reports arm +``` + +**Note:** Docker Swarm uses the kernel's arch string. Pi 4 reports `aarch64` not `arm64`. The constraint `!= arm64` does **not** exclude Pi 4s. + +Verified node architectures in Netgrimoire: +``` +DockerPi1: linux/aarch64 +docker3: linux/x86_64 +docker4: linux/x86_64 +docker5: linux/x86_64 +znas: linux/x86_64 +``` + +### Label Sections + +Labels are organized with comment dividers in this order: + +```yaml +labels: + # --- Caddy --- + # --- Uptime Kuma --- + # --- Homepage --- + # --- DIUN --- +``` + +Use map syntax (not list syntax) for labels. List syntax (`- key=value`) and map syntax (`key: value`) both work, but map syntax is the standard. + +--- + +## Services Without a UI + +Some services have no web interface and need no Caddy, Homepage, or Kuma labels: + +**Example: DIUN** +```yaml +deploy: + labels: + # --- DIUN --- + diun.enable: "true" +``` + +Services in this category: DIUN, background workers, one-shot jobs. + +--- + +## Kuma Label Format + +```yaml +kuma...: +``` + +- `unique-id` — must be unique across all services in the entire Swarm +- `monitor-type` — `http`, `tcp`, `ping`, `dns` +- Common fields: `name`, `url`, `interval`, `maxretries` + +Example: +```yaml +kuma.forgejo.http.name: Forgejo +kuma.forgejo.http.url: https://git.netgrimoire.com +``` + +--- + +## Homepage Label Format + +```yaml +homepage.group: Group Name +homepage.name: Display Name +homepage.icon: icon.png +homepage.href: https://service.netgrimoire.com +homepage.description: Short description +``` + +For services with widgets: +```yaml +homepage.widget.type: radarr +homepage.widget.url: http://radarr:7878 +homepage.widget.key: apikey +``` + +**Important:** Every `homepage.group` value must have a matching entry in `settings.yaml` with `style: column`, or the group will render full-width. + +--- + +## Secrets Approach + +Docker Swarm native secrets are preferred. For services that support `_FILE` env vars: + +```yaml +environment: + MY_PASSWORD_FILE: /run/secrets/my_password +secrets: + - my_password +``` + +Plain credentials in environment vars are acceptable as an interim approach for services that don't support `_FILE`. + +**Never use `env_file:` in Swarm stacks** — it's read by the Docker client at deploy time from the deploying machine, not injected into the container at runtime. Use `environment:` directly.