docs(gremlin): create homepage-agent

Netgrimoire/Services/homepage-agent/homepage-agent.md

@@ -0,0 +1,160 @@
+# homepage-agent Stack
+
+description: Agent for NetGrimoire
+
+published: true
+date: 2026-05-06T14:37:45.785Z
+tags: docker,swarm,homepage-agent,netgrimoire
+editor: markdown
+dateCreated: 2026-05-06T14:37:45.785Z
+---
+
+# homepage-agent
+
+## Overview
+
+The homepage-agent stack is a Docker Swarm service that provides an agent for NetGrimoire. It exposes several ports and services to interact with the platform.
+
+---
+
+## Architecture
+
+| Service | Image | Port | Role |
+|-|-|-|-|
+- **Homepage Agent** | ghcr.io/gethomepage/agent:latest | 4111, 4112, 4113, 4114, 4115 | Web server and agent |
+
+- **Host:** docker4
+- **Network:** netgrimoire
+- **Exposed via:** <caddy domains from labels>
+- **Homepage group:** homepage.group
+
+---
+
+## Build & Configuration
+
+### Prerequisites
+- Docker 20 or later
+- Caddy 2.0 or later installed on nodes
+
+### Volume Setup
+```bash
+mkdir -p /DockerVol/homepage-agent-docker3
+chown -R homepage:homepage /DockerVol/homepage-agent-docker3
+```
+
+```bash
+mkdir -p /DockerVol/homepage-agent-docker4
+chown -R homepage:homepage /DockerVol/homepage-agent-docker4
+```
+
+```bash
+mkdir -p /DockerVol/homepage-agent-docker5
+chown -R homepage:homepage /DockerVol/homepage-agent-docker5
+```
+
+```bash
+mkdir -p /DockerVol/homepage-agent-znas
+chown -R homepage:homepage /DockerVol/homepage-agent-znas
+```
+
+```bash
+mkdir -p /DockerVol/homepage-agent-dockerpi1
+chown -R homepage:homepage /DockerVol/homepage-agent-dockerpi1
+```
+
+### Environment Variables
+
+- PUID: 1964
+- PGID: 1964
+- HOMEPAGE_AGENT_PORT: 4111, 4112, 4113, 4114, 4115
+```bash
+generate: openssl rand -hex 32
+```
+
+### Deploy
+```bash
+cd services/swarm/stack/homepage-agent
+set -a && source .env && set +a
+docker stack config --compose-file homepage-agent-stack.yml > resolved.yml
+docker stack deploy --compose-file resolved.yml homepage-agent
+rm resolved.yml
+docker stack services homepage-agent
+```
+
+### First Run
+
+- Update Caddy configuration and restart
+```bash
+cd caddy/
+docker-compose up -d --force-recreate --remove
+```
+- Update Uptime Kuma configuration and restart
+```bash
+kumactl update kuma
+kumactl restart ufk
+```
+
+---
+
+## User Guide
+
+### Accessing homepage-agent
+| Service | URL | Purpose |
+|-|-|-|
+- **Home**: <Caddy domain from label>
+- **Monitor**: <Kuma monitor from kuma.* label>
+
+### Primary Use Cases
+- Set up NetGrimoire as the primary web server.
+- Configure Caddy to serve the agent.
+
+### NetGrimoire Integrations
+- The homepage-agent connects to Uptime Kuma for monitoring.
+- It exposes its services through Caddy.
+
+---
+
+## Operations
+
+### Monitoring
+```bash
+docker stack services homepage-agent
+kumactl status ufk
+```
+
+### Backups
+- Critical data is stored in /DockerVol/homepage-agent-docker3, /DockerVol/homepage-agent-docker4, and other respective Docker volumes.
+- Data is reconstructable from these volumes.
+
+### Restore
+```bash
+cd services/swarm/stack/homepage-agent
+./deploy.sh
+```
+
+---
+
+## Common Failures
+
+| Failure | Symptoms | Cause | Fix |
+|-|-|-|-|
+- **Service Unreachable**: Service not available over network.  | No incoming traffic to service. Check Caddy configuration and Uptime Kuma status.
+- **Incorrect Configuration**: Service not correctly set up for NetGrimoire.  | Incorrect file or label used in deployment script. Review the deploy.sh script and update accordingly.
+- **Missing Docker Volume**: Docker volume is missing, so data cannot be retrieved.  | Data volume (e.g., /DockerVol/homepage-agent-docker3) is missing from container. Check for missing data volumes.
+
+---
+
+## Changelog
+
+| Date | Commit | Summary |
+|------|--------|---------|
+| 2026-05-06 | 3b8f1795 | Initial documentation |
+
+<Write a paragraph summarizing the evolution of this service based on the diffs above. If no diffs available, note that this is the initial documentation.]
+
+---
+
+## Notes
+- Generated by Gremlin on 2026-05-06T14:37:45.785Z
+- Source: swarm/homepage-agent.yaml
+- Review User Guide and Changelog sections