docs(gremlin): create homepage

Netgrimoire/Services/homepage/homepage.md

@@ -0,0 +1,117 @@
+# homepage Stack
+
+description: NetGrimoire homepage service with Caddy reverse proxy and Uptime Kuma monitoring.
+
+---
+
+## Overview
+
+The `homepage` stack is a Docker Swarm-based service that provides the NetGrimoire homepage. It utilizes the `ghcr.io/gethomepage/homepage:latest` image and features an environment variable for allowed hosts, as well as a volume mount for configuration files. This stack also uses Caddy for reverse proxying and Uptime Kuma for monitoring.
+
+---
+
+## Architecture
+
+| Service | Image | Port | Role |
+|---------|-------|------|------|
+- **Host:** docker4
+- **Network:** netgrimoire
+- **Exposed via:** homepage.netgrimoire.com, glance.netgrimoire.com (Caddy domains)
+- **Homepage group:** homepage.group
+
+---
+
+## Build & Configuration
+
+### Prerequisites
+
+This stack requires the `docker` command-line utility to be installed and configured.
+
+### Volume Setup
+```bash
+mkdir -p /DockerVol/homepage/config
+chown -R docker:docker /DockerVol/homepage/config
+```
+
+### Environment Variables
+```bash
+# generate: openssl rand -hex 32
+HOMEPAGE_ALLOWED_HOSTS=homepage.netgrimoire.com,glance.netgrimoire.com
+```
+
+### Deploy
+```bash
+cd services/swarm/stack/homepage
+set -a && source .env && set +a
+docker stack config --compose-file homepage-stack.yml > resolved.yml
+docker stack deploy --compose-file resolved.yml homepage
+rm resolved.yml
+docker stack services homepage
+```
+
+### First Run
+
+Perform the following steps after deployment:
+
+* Run `docker-compose up` to start the services.
+* Configure the `HOMEPAGE_ALLOWED_HOSTS` environment variable with the desired hosts.
+
+---
+
+## User Guide
+
+### Accessing homepage
+| Service | URL | Purpose |
+|---------|-----|---------|
+- **Host:** docker4, `homepage.netgrimoire.com`
+
+### Primary Use Cases
+
+This stack serves as the primary source for NetGrimoire's homepage. It can be accessed by visiting the specified Caddy domain or hostname.
+
+### NetGrimoire Integrations
+
+This stack integrates with other services in the NetGrimoire environment through environment variables and labels, including `kuma.*` monitors and `homepage.group`.
+
+---
+
+## Operations
+
+### Monitoring
+```bash
+docker stack services homepage
+docker-compose logs -f homepage
+```
+
+### Backups
+Critical backups should be performed regularly. Reconstructable paths are `/DockerVol/homepage/config/...`. Non-critical paths can be left to the system's automatic backup mechanisms.
+
+### Restore
+```bash
+cd services/swarm/stack/homepage
+./deploy.sh
+```
+
+---
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+1. Service not responding | Incorrect configuration or missing dependencies | Review and correct environment variables, ensure all required packages are installed.
+2. No reverse proxying | Caddy configuration issues or incorrect labels | Check Caddy logs for errors, verify the `caddy-docker-proxy` label is applied correctly.
+3. Network connectivity issues | External network issues or incorrect routing table entries | Verify network connections and routing table entries.
+
+---
+
+## Changelog
+
+| Date | Commit | Summary |
+|------|--------|---------|
+| 2026-04-06 | 5db4fdd9 | Migration to swarm configuration |
+
+---
+
+## Notes
+- Generated by Gremlin on 2026-04-07T00:45:36.511Z
+- Source: swarm/stack/homepage/homepage.yaml