# homepage-agents

## Overview
The homepage-agents stack is a critical component of NetGrimoire, providing reverse proxy services for Docker socket proxies, enabling monitoring, and ensuring smooth operation within the network.

---

## Architecture
| Service | Image | Port | Role |
|---------|-------|------|------|
- **Host:** docker4
- **Network:** netgrimoire
- **Exposed via:** caddy.dns.znas, caddy.dns.docker3, caddy.dns.docker4, caddy.dns.docker5
- **Homepage group:** homepage

---

## Build & Configuration

### Prerequisites
This stack requires Docker Swarm to be configured and running.

### 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
Set up monitoring for the Docker socket proxies.

---

## User Guide

### Accessing homepage-agents
| Service | URL | Purpose |
- **caddy-dns.znas:** <internal>
- **caddy.dns.docker3:** http://dock3:4111, https://dock3:4112
- **caddy.dns.docker4:** http://dock4:4111, https://dock4:4112
- **caddy.dns.docker5:** http://dock5:4111, https://dock5:4112

### Primary Use Cases
Accessing Docker socket proxies via Caddy.

### NetGrimoire Integrations
Monitoring and configuration of Docker socket proxies via Uptime Kuma.

---

## Operations

### Monitoring
```bash
docker stack services homepage-agents
docker service logs -f homepage-agents
```

### Backups
Critical Docker socket proxy data will be stored on /DockerVol/homepage-agents. Regular backups should ensure that this critical data is always available in case of failure.

### Restore
```bash
cd services/swarm/stack/homepage-agents
./deploy.sh
```

---

## Common Failures
1. Caddy unable to connect to Docker socket: Insufficient network connectivity, or the Docker socket proxy has been reset.
2. Uptime Kuma monitoring not updating: Check that all service logs are being forwarded correctly and that Docker socket proxies are running as expected.
3. Docker socket proxy configuration errors: Double-check that the Docker socket proxy configurations are correct.

---

## Changelog

| Date | Commit | Summary |
|------|--------|---------|
| 2026-05-06 | a628043d | <infer what changed from the diffs above> |
| 2026-05-06 | 657c3d28 | <infer what changed from the diffs above> |

<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-06T18:40:35.988Z
- Source: swarm/homepage-agents.yaml
- Review User Guide and Changelog sections