docs(gremlin): create beszel_agents

Netgrimoire/Services/beszel_agents/beszel_agents.md

@@ -0,0 +1,101 @@
+# beszel_agents
+
+## Overview
+The beszel_agents stack is a collection of services in NetGrimoire that utilize the Beszel-Agent, a tool for automating various tasks on the system. The primary services included in this stack are beszel-agent-docker3, beszel-agent-docker4, beszel-agent-docker5, and beszel-agent-znas.
+
+## Architecture
+
+| Service | Image | Port | Role |
+|---------|-------|------|------|
+- **beszel-agent-docker3** | henrygd/beszel-agent:latest | 45878 | Beszel-Agent |
+- **beszel-agent-docker4** | henrygd/beszel-agent:latest | 45879 | Beszel-Agent |
+- **beszel-agent-docker5** | henrygd/beszel-agent:latest | 45883 | Beszel-Agent |
+- **beszel-agent-znas** | henrygd/beszel-agent:latest | 45880 | Beszel-Agent |
+- **Host:** docker4
+- **Network:** netgrimoire
+- **Exposed via:** `caddy.beszel_agents.net` (Caddy labels) or Internal only
+- **Homepage group:** homepage
+
+## Build & Configuration
+
+### Prerequisites
+To build and deploy the beszel_agents stack, you need to have Docker installed on your system.
+
+### Volume Setup
+```bash
+mkdir -p /DockerVol/beszel_agents
+chown -R docker4:docker4 /DockerVol/beszel_agents
+```
+
+### Environment Variables
+```bash
+KEY="ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGNx6yKSqJHUiSKTM44/A1luwBije9HkHwnOxwXYx8q4"
+LISTEN=45878
+PUID=1964
+PGID=1964
+```
+
+### Deploy
+```bash
+cd services/swarm/stack/beszel_agents
+set -a && source .env && set +a
+docker stack config --compose-file beszel_agents-stack.yml > resolved.yml
+docker stack deploy --compose-file resolved.yml beszel_agents
+rm resolved.yml
+docker stack services beszel_agents
+```
+
+### First Run
+After the initial deployment, you need to wait for 5 seconds and then check the logs of the Beszel-Agent services.
+
+## User Guide
+
+### Accessing beszel_agents
+| Service | URL | Purpose |
+- **beszel-agent-docker3** | `http://caddy.beszel_agents.net` | Beszel-Agent |
+- **beszel-agent-docker4** | `http://caddy.beszel_agents.net:45879` | Beszel-Agent |
+- **beszel-agent-docker5** | `http://caddy.beszel_agents.net:45883` | Beszel-Agent |
+- **beszel-agent-znas** | `http://caddy.beszel_agents.net:45880` | Beszel-Agent |
+
+### Primary Use Cases
+The beszel_agents stack is used for automating tasks on the system, such as monitoring and maintenance.
+
+### NetGrimoire Integrations
+This stack connects to other services in NetGrimoire, such as the homepage dashboard.
+
+## Operations
+
+### Monitoring
+```bash
+docker stack services beszel_agents
+docker service logs -f beszel-agent-docker3
+```
+
+### Backups
+Critical data should be stored on a separate volume, such as `/DockerVol/beszel_agents/critical_data`.
+
+### Restore
+```bash
+cd services/swarm/stack/beszel_agents
+./deploy.sh
+```
+
+## Common Failures
+| Symptom | Cause | Fix |
+- ** Beszel-Agent not starting** | The container is not running. | `docker service start beszel-agent-docker3` |
+- ** Beszel-Agent not connecting to the network** | The container's network configuration is incorrect. | `docker run -it --rm henrygd/beszel-agent:latest --net=netgrimoire` |
+
+## Changelog
+
+| Date | Commit | Summary |
+|------|--------|---------|
+| 2026-05-05 | 56133396 | Initial documentation and deployment of the beszel_agents stack. |
+| 2026-05-01 | c3b0c0f5 | Minor adjustments to environment variables and deploy script. |
+| 2026-01-25 | e8d32a9d | Initial version of the beszel_agents stack. |
+| 2026-01-25 | 17247fff | Fixed an issue with the Beszel-Agent not connecting to the network. |
+| 2026-01-10 | 1a374911 | Adjusted logging configuration for the Beszel-Agent services. |
+
+## Notes
+Generated by Gremlin on 2026-05-05T18:45:08.741Z
+Source: swarm/beszel_agents.yaml
+Review User Guide and Changelog sections