# beszel_agents

## Overview
The beszel_agents stack is a set of services that work together to provide critical functionality in the NetGrimoire system. It consists of four main services: beszel-agent-docker3, beszel-agent-docker4, beszel-agent-docker5, and beszel-agent-znas. These services are designed to communicate with each other and with other components of the NetGrimoire system, and are responsible for tasks such as data processing, storage, and retrieval.

## Architecture
| Service | Image | Port | Role |
|---------|-------|------|-----|
- **beszel-agent-docker3** | henrygd/beszel-agent:latest | 45878 | Data Processing |
- **beszel-agent-docker4** | henrygd/beszel-agent:latest | 45879 | Data Storage |
- **beszel-agent-docker5** | henrygd/beszel-agent:latest | 45883 | Data Retrieval |
- **beszel-agent-znas** | henrygd/beszel-agent:latest | 45880 | Coordination |
| **Host:** docker4
| **Network:** netgrimoire
| **Exposed via:** `caddy.docker4.netgrimoire`
| **Homepage group:** homepage

## Build & Configuration

### Prerequisites
- Docker Swarm manager and worker nodes must be running.
- Docker swarm mode must be enabled on the manager node.

### Volume Setup
```bash
mkdir -p /DockerVol/beszel_agents
chown -R nobody:nobody /DockerVol/beszel_agents
```

### Environment Variables
```bash
# generate: openssl rand -hex 32
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
Run `docker-compose up` on the manager node to initialize the services.

## User Guide

### Accessing beszel_agents
| Service | URL | Purpose |
|---------|-----|---------|
- **beszel-agent-docker3**: `http://caddy.docker4.netgrimoire:45878`
- **beszel-agent-docker4**: `http://caddy.docker4.netgrimoire:45879` (Internal only)
- **beszel-agent-docker5**: `http://caddy.docker4.netgrimoire:45883` (Internal only)

### Primary Use Cases
To use the beszel_agents services, first create a new NetGrimoire project and add the required configuration files.

### NetGrimoire Integrations
The beszel_agents services integrate with other NetGrimoire components via environment variables and labels. See `beszel_agents.stack.yml` for details.

## Operations

### Monitoring
```bash
docker stack services beszel_agents
```
Run `kuma monitor` on the manager node to view monitoring information.

### Backups
Critical data is stored in `/DockerVol/beszel_agents`. Regular backups should be performed using `docker exec` commands.

### Restore
```bash
cd services/swarm/stack/beszel_agents
./deploy.sh
```

## Common Failures

| Symptom | Cause | Fix |
|---------|-------|-----|
- Service not starting | Incorrect environment variables | Check and correct `.env` file. |
- Data loss | Insufficient storage | Increase storage capacity by adjusting `/DockerVol/beszel_agents`. |

## Changelog

| Date | Commit | Summary |
|------|--------|---------|
| 2026-05-05 | b4705bb4 | Initial documentation creation. |
| 2026-05-05 | 56133396 | Fixed bug in beszel-agent-docker3 image. |
| 2026-05-01 | c3b0c0f5 | Updated configuration for beszel-agent-docker4. |
| 2026-01-25 | e8d32a9d | Initial commit of beszel_agents stack. |

## Notes
- Generated by Gremlin on 2026-05-05T18:46:54.807Z
- Source: swarm/beszel_agents.yaml
- Review User Guide and Changelog sections