traveler/Netgrimoire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(gremlin): update homepage-agent

Browse source
This commit is contained in:
traveler 2026-05-06 09:41:16 -05:00
parent 23e46f14ee
commit 39272ca2e0
1 changed files with 82 additions and 72 deletions
Download patch file Download diff file Expand all files Collapse all files

154
Netgrimoire/Services/homepage-agent/homepage-agent.md
View file

@ -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:** <caddy domains from labels>
- **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**: <Caddy domain from label>
- **Monitor**: <Kuma monitor from kuma.* label>
|---------|-----|---------|
- **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. |
<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
# Notes
- Generated by Gremlin on 2026-05-06T14:37:49.849Z
- Source: swarm/homepage-agent.yaml
- Review User Guide and Changelog sections