diff --git a/Netgrimoire/Services/homepage-agent/homepage-agent.md b/Netgrimoire/Services/homepage-agent/homepage-agent.md index 23b9d1d..999d010 100644 --- a/Netgrimoire/Services/homepage-agent/homepage-agent.md +++ b/Netgrimoire/Services/homepage-agent/homepage-agent.md @@ -1,74 +1,90 @@ -# homepage-agent Stack - -description: Agent for NetGrimoire - +--- +title: homepage-agent Stack +description: Migration to swarm configuration published: true -date: 2026-05-06T14:37:45.785Z +date: 2026-05-06T14:37:49.849Z tags: docker,swarm,homepage-agent,netgrimoire editor: markdown -dateCreated: 2026-05-06T14:37:45.785Z +dateCreated: 2026-05-06T14:37:49.849Z --- # 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. - ---- +The homepage-agent stack is a Docker Swarm configuration for the homepage service in NetGrimoire. It consists of four services: `homepage-agent-docker3`, `homepage-agent-docker4`, `homepage-agent-docker5`, and `homepage-agent-znas`. These services are replicas of the same image, with slightly different port numbers and labels. ## 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:** +- **Exposed via:** caddy.docker3:4111, internal - **Homepage group:** homepage.group ---- - ## Build & Configuration ### Prerequisites -- Docker 20 or later -- Caddy 2.0 or later installed on nodes +To build this stack, you need to have Docker Swarm installed and running. ### Volume Setup ```bash mkdir -p /DockerVol/homepage-agent-docker3 -chown -R homepage:homepage /DockerVol/homepage-agent-docker3 +chown -R docker:docker /DockerVol/homepage-agent-docker3 ``` ```bash mkdir -p /DockerVol/homepage-agent-docker4 -chown -R homepage:homepage /DockerVol/homepage-agent-docker4 +chown -R docker:docker /DockerVol/homepage-agent-docker4 ``` ```bash mkdir -p /DockerVol/homepage-agent-docker5 -chown -R homepage:homepage /DockerVol/homepage-agent-docker5 +chown -R docker:docker /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 +chown -R docker:docker /DockerVol/homepage-agent-znas ``` ### Environment Variables - -- PUID: 1964 -- PGID: 1964 -- HOMEPAGE_AGENT_PORT: 4111, 4112, 4113, 4114, 4115 ```bash -generate: openssl rand -hex 32 +# generate: openssl rand -hex 32 +PUID=1964 +PGID=1964 +HOMEPAGE_AGENT_PORT=4111 +CADDY_SKIP=true +HOME_PAGE_SKIP=true +MONITOR_SKIP=true +DIUN_ENABLE=true + +# generate: openssl rand -hex 32 +PUID=1964 +PGID=1964 +HOMEPAGE_AGENT_PORT=4112 +CADDY_SKIP=true +HOME_PAGE_SKIP=true +MONITORSKIP=true +DIUN_ENABLE=true + +# generate: openssl rand -hex 32 +PUID=1964 +PGID=1964 +HOMEPAGE_AGENT_PORT=4113 +CADDY_SKIP=true +HOME_PAGE_SKIP=true +MONITOR_SKIP=true +DIUN_ENABLE=true + +# generate: openssl rand -hex 32 +PUID=1964 +PGID=1964 +HOMEPAGE_AGENT_PORT=4114 +CADDY_SKIP=true +HOME_PAGE_SKIP=true +MONITORSKIP=true +DIUN_ENABLE=true ``` ### Deploy @@ -82,79 +98,73 @@ docker stack services homepage-agent ``` ### First Run +Perform the following steps after deploying the stack for the first time: -- 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 -``` +# Initialize Kuma for monitoring +kuma init ---- +# Start Uptime Kuma for monitoring +kuma start -d + +# Check service logs for errors +docker service logs --follow homepage-agent-docker3 +``` ## User Guide ### Accessing homepage-agent | Service | URL | Purpose | -|-|-|-| -- **Home**: -- **Monitor**: +|---------|-----|---------| +- **Home Page:** caddy.docker3:4111 +- **Admin Panel:** None ### Primary Use Cases -- Set up NetGrimoire as the primary web server. -- Configure Caddy to serve the agent. +To use the homepage-agent service, you can access it through the admin panel. Please note that the admin panel is not currently available. ### NetGrimoire Integrations -- The homepage-agent connects to Uptime Kuma for monitoring. -- It exposes its services through Caddy. - ---- +The homepage-agent service connects to other services in NetGrimoire through environment variables and labels. Specifically, it connects to `diun` for integration with the DiUn server. ## Operations ### Monitoring +Use Kuma to monitor the status of the homepage-agent service. + ```bash docker stack services homepage-agent -kumactl status ufk +kuma status ``` ### 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. +Critical data is stored in `/DockerVol/homepage-agent-docker3` and `/DockerVol/homepage-agent-docker4`. Ensure that these directories are backed up regularly. ### Restore +To restore the service, run the following command: + ```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. - ---- +| Failure Mode | Symptoms | Cause | Fix | +|-------------|----------|-------|------| +- **Port in Use**: Port is already in use by another process. + - Symptoms: Service cannot be started. + - Cause: Another service is using the same port. + - Fix: Stop the other service and try again. +- **Kuma Connection Error**: Kuma connection fails. + - Symptoms: Service logs contain error messages about Kuma connection failures. + - Cause: Kuma is not running or there is an issue with the configuration. + - Fix: Check the Kuma logs and adjust the configuration as needed. ## Changelog | Date | Commit | Summary | |------|--------|---------| -| 2026-05-06 | 3b8f1795 | Initial documentation | +| 2026-05-06 | 9e8a2087 | Initial documentation creation. | +| 2026-05-06 | 3b8f1795 | Added initial services and configuration. | -