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 ---
title: homepage-agent Stack
description: Agent for NetGrimoire description: Migration to swarm configuration
published: true published: true
date: 2026-05-06T14:37:45.785Z date: 2026-05-06T14:37:49.849Z
tags: docker,swarm,homepage-agent,netgrimoire tags: docker,swarm,homepage-agent,netgrimoire
editor: markdown editor: markdown
dateCreated: 2026-05-06T14:37:45.785Z dateCreated: 2026-05-06T14:37:49.849Z
--- ---
# homepage-agent # homepage-agent
## Overview ## Overview
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.
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 ## Architecture
| Service | Image | Port | Role | | Service | Image | Port | Role |
|-|-|-|-| |---------|-------|------|------|
- **Homepage Agent** | ghcr.io/gethomepage/agent:latest | 4111, 4112, 4113, 4114, 4115 | Web server and agent |
- **Host:** docker4 - **Host:** docker4
- **Network:** netgrimoire - **Network:** netgrimoire
- **Exposed via:** <caddy domains from labels> - **Exposed via:** caddy.docker3:4111, internal
- **Homepage group:** homepage.group - **Homepage group:** homepage.group
---
## Build & Configuration ## Build & Configuration
### Prerequisites ### Prerequisites
- Docker 20 or later To build this stack, you need to have Docker Swarm installed and running.
- Caddy 2.0 or later installed on nodes
### Volume Setup ### Volume Setup
```bash ```bash
mkdir -p /DockerVol/homepage-agent-docker3 mkdir -p /DockerVol/homepage-agent-docker3
chown -R homepage:homepage /DockerVol/homepage-agent-docker3 chown -R docker:docker /DockerVol/homepage-agent-docker3
``` ```
```bash ```bash
mkdir -p /DockerVol/homepage-agent-docker4 mkdir -p /DockerVol/homepage-agent-docker4
chown -R homepage:homepage /DockerVol/homepage-agent-docker4 chown -R docker:docker /DockerVol/homepage-agent-docker4
``` ```
```bash ```bash
mkdir -p /DockerVol/homepage-agent-docker5 mkdir -p /DockerVol/homepage-agent-docker5
chown -R homepage:homepage /DockerVol/homepage-agent-docker5 chown -R docker:docker /DockerVol/homepage-agent-docker5
``` ```
```bash ```bash
mkdir -p /DockerVol/homepage-agent-znas mkdir -p /DockerVol/homepage-agent-znas
chown -R homepage:homepage /DockerVol/homepage-agent-znas chown -R docker:docker /DockerVol/homepage-agent-znas
```
```bash
mkdir -p /DockerVol/homepage-agent-dockerpi1
chown -R homepage:homepage /DockerVol/homepage-agent-dockerpi1
``` ```
### Environment Variables ### Environment Variables
- PUID: 1964
- PGID: 1964
- HOMEPAGE_AGENT_PORT: 4111, 4112, 4113, 4114, 4115
```bash ```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 ### Deploy
@ -82,79 +98,73 @@ docker stack services homepage-agent
``` ```
### First Run ### First Run
Perform the following steps after deploying the stack for the first time:
- Update Caddy configuration and restart
```bash ```bash
cd caddy/ # Initialize Kuma for monitoring
docker-compose up -d --force-recreate --remove kuma init
```
- Update Uptime Kuma configuration and restart
```bash
kumactl update kuma
kumactl restart ufk
```
--- # Start Uptime Kuma for monitoring
kuma start -d
# Check service logs for errors
docker service logs --follow homepage-agent-docker3
```
## User Guide ## User Guide
### Accessing homepage-agent ### Accessing homepage-agent
| Service | URL | Purpose | | Service | URL | Purpose |
|-|-|-| |---------|-----|---------|
- **Home**: <Caddy domain from label> - **Home Page:** caddy.docker3:4111
- **Monitor**: <Kuma monitor from kuma.* label> - **Admin Panel:** None
### Primary Use Cases ### Primary Use Cases
- Set up NetGrimoire as the primary web server. To use the homepage-agent service, you can access it through the admin panel. Please note that the admin panel is not currently available.
- Configure Caddy to serve the agent.
### NetGrimoire Integrations ### NetGrimoire Integrations
- The homepage-agent connects to Uptime Kuma for monitoring. 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.
- It exposes its services through Caddy.
---
## Operations ## Operations
### Monitoring ### Monitoring
Use Kuma to monitor the status of the homepage-agent service.
```bash ```bash
docker stack services homepage-agent docker stack services homepage-agent
kumactl status ufk kuma status
``` ```
### Backups ### Backups
- Critical data is stored in /DockerVol/homepage-agent-docker3, /DockerVol/homepage-agent-docker4, and other respective Docker volumes. Critical data is stored in `/DockerVol/homepage-agent-docker3` and `/DockerVol/homepage-agent-docker4`. Ensure that these directories are backed up regularly.
- Data is reconstructable from these volumes.
### Restore ### Restore
To restore the service, run the following command:
```bash ```bash
cd services/swarm/stack/homepage-agent
./deploy.sh ./deploy.sh
``` ```
---
## Common Failures ## Common Failures
| Failure Mode | Symptoms | Cause | Fix |
| Failure | Symptoms | Cause | Fix | |-------------|----------|-------|------|
|-|-|-|-| - **Port in Use**: Port is already in use by another process.
- **Service Unreachable**: Service not available over network. | No incoming traffic to service. Check Caddy configuration and Uptime Kuma status. - Symptoms: Service cannot be started.
- **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. - Cause: Another service is using the same port.
- **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. - 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 ## Changelog
| Date | Commit | Summary | | 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:49.849Z
---
## Notes
- Generated by Gremlin on 2026-05-06T14:37:45.785Z
- Source: swarm/homepage-agent.yaml - Source: swarm/homepage-agent.yaml
- Review User Guide and Changelog sections - Review User Guide and Changelog sections