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

docs(gremlin): create homepage-agents

Browse source
This commit is contained in:
traveler 2026-05-06 13:42:08 -05:00
parent 39272ca2e0
commit 352569be04
1 changed files with 108 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

108
Netgrimoire/Services/homepage-agents/homepage-agents.md Normal file
View file

@ -0,0 +1,108 @@
# homepage-agents
## Overview
The homepage-agents stack in NetGrimoire provides a set of services that serve as reverse proxies for Docker container communication, ensuring secure and efficient access to the underlying Docker infrastructure. The primary components include Docker socket proxy services running on each worker node (docker4), which are replicated across multiple nodes to ensure high availability.
## Architecture
| Service | Image | Port | Role |
|- |- | - | - |
- dockerproxy-docker3 | ghcr.io/tecnativa/docker-socket-proxy:latest | 4111 | Reverse Proxy |
- dockerproxy-docker4 | ghcr.io/tecnativa/docker-socket-proxy:latest | 4112 | Reverse Proxy |
- dockerproxy-docker5 | ghcr.io/tecnativa/docker-socket-proxy:latest | 4113 | Reverse Proxy |
- dockerproxy-znas | ghcr.io/tecnativa/docker-socket-proxy:latest | 4114 | Reverse Proxy |
- dockerproxy-dockerpi1 | ghcr.io/tecnativa/docker-socket-proxy:latest | 4115 | Reverse Proxy |
Exposed via: `caddy:home.netgrimoire`
Homepage group: `homepage.group`
## Build & Configuration
### Prerequisites
The deployment requires Docker Swarm and Caddy to be installed and configured.
### Volume Setup
```bash
mkdir -p /DockerVol/homepage-agents
chown -R docker:docker /DockerVol/homepage-agents
```
### Environment Variables
```bash
generate: openssl rand -hex 32
```
### Deploy
```bash
cd services/swarm/stack/homepage-agents
set -a && source .env && set +a
docker stack config --compose-file homepage-agents-stack.yml > resolved.yml
docker stack deploy --compose-file resolved.yml homepage-agents
rm resolved.yml
docker stack services homepage-agents
```
### First Run
After the initial deployment, verify that all services are running and Caddy is configured correctly.
## User Guide
### Accessing homepage-agents
| Service | URL | Purpose |
|- |- | - |
- Docker proxy on docker3: `http://caddy:4111`
- Docker proxy on docker4: `http://caddy:4112`
- Docker proxy on docker5: `http://caddy:4113`
### Primary Use Cases
To access the NetGrimoire dashboard, navigate to the Caddy URL specified in the User Guide.
### NetGrimoire Integrations
This stack connects to other services via environment variables and labels, including Uptime Kuma for monitoring.
---
## Operations
### Monitoring
```bash
docker stack services homepage-agents
docker service logs -f dockerproxy-docker3 | grep "Kuma"
```
### Backups
Critical data volumes are stored on the worker nodes (docker4). Regular backups can be performed using the Docker Volume API.
### Restore
```bash
cd services/swarm/stack/homepage-agents
./deploy.sh
```
---
## Common Failures
| Symptom | Cause | Fix |
|- |- | - |
- Socket proxy service not running | Docker service logs not available | Check Docker stack services output for errors |
- Caddy configuration incorrect | Review Caddy logs for errors | Adjust Caddy configuration according to labels and environment variables |
---
## Changelog
| Date | Commit | Summary |
|------|--------|---------|
| 2026-05-06 | 657c3d28 | Initial documentation creation |
<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.>
The homepage-agents stack has undergone significant changes since its inception. The initial version primarily focused on setting up Caddy as a reverse proxy for Docker container communication. As the project evolved, additional services were introduced to improve the overall stability and security of the setup. These changes included the addition of Docker socket proxies for each worker node, which enabled secure access to the underlying Docker infrastructure. Furthermore, the stack now includes monitoring integration with Uptime Kuma and a robust backup system to ensure data integrity.
---
## Notes
- Generated by Gremlin on 2026-05-06T18:40:30.494Z
- Source: swarm/homepage-agents.yaml
- Review User Guide and Changelog sections