# Beszel Agent

Docker deployment for the Beszel monitoring agent. Run all commands from the
repository root.

## Persistent Data

Beszel Agent state is stored in the Docker-managed named volume
`beszel_agent_data`.

Existing deployments that use `appdata/beszel-agent` must copy that data into
the named volume before recreating the container.

## Installation

1. Create `.env` if it does not exist:

   ```bash
   cp -n .env.sample .env
   ```

2. Add the agent credentials supplied by Beszel Hub to `.env`:

   ```dotenv
   TZ=Africa/Johannesburg
   BESZEL_AGENT_KEY=<public-key-from-hub>
   BESZEL_AGENT_TOKEN=<token-from-hub>
   BESZEL_AGENT_HUB_URL=https://beszel.example.com
   BESZEL_AGENT_LISTEN=45876
   BESZEL_SOCKET_PROXY_PORT=2375
   DOCKERLOGGING_MAXFILE=3
   DOCKERLOGGING_MAXSIZE=10m
   ```

3. Render the template:

   ```bash
   ./substitute_env.sh docker-compose-files/beszel-agent/template.yaml docker-compose.beszel-agent.yml .env
   ```

4. Start the socket proxy first, then validate and start the agent:

   ```bash
   docker compose -f docker-compose.beszel-proxy.yml up -d
   docker compose -f docker-compose.beszel-agent.yml config --quiet
   docker compose -f docker-compose.beszel-agent.yml up -d
   ```

5. Verify the container:

   ```bash
   docker compose -f docker-compose.beszel-agent.yml ps
   docker compose -f docker-compose.beszel-agent.yml logs --tail=100 beszel-agent
   ```

## Apply Configuration Changes

```bash
./substitute_env.sh docker-compose-files/beszel-agent/template.yaml docker-compose.beszel-agent.yml .env
docker compose -f docker-compose.beszel-agent.yml up -d
```

## Initial Setup

Add the system in Beszel Hub and use the generated key, token, and hub URL in
`.env`.

## Network Requirements

- Beszel Hub must reach the agent on `BESZEL_AGENT_LISTEN`.
- The agent reaches the socket proxy at `127.0.0.1:BESZEL_SOCKET_PROXY_PORT`.

## Troubleshooting

Confirm `beszel-proxy` is running and listening on localhost if Docker container
metrics are missing.

## Useful Commands

```bash
docker compose -f docker-compose.beszel-agent.yml restart beszel-agent
```

## Backup

Back up the `beszel_agent_data` named volume.