History

Brian Pooe 1815beadf4 refactor: restructure docs, sync stacks with Caddyfile, harden compose templates - Add compose stacks for apps already proxied by Caddy: bento-pdf, it-tools, paperless-ngx, and beszel-hub (with Makefile targets) - Remove the unused Vault stack and the drawio Caddyfile block - Fix Caddyfile gramps upstream to port 80 to match the compose file - Bring immich and gramps-web up to the shared template pattern (no-new-privileges, log rotation, memory limits, healthchecks) - Single-quote vaultwarden SSO_AUDIENCE_TRUSTED so regex values like ^\d{18}$ render as valid YAML - Move root docs into kebab-case topic folders, rebuild the docs index to cover every doc, and fix all broken links		2026-07-03 17:45:16 +02:00
..
.env.sample	refactor: restructure docs, sync stacks with Caddyfile, harden compose templates	2026-07-03 17:45:16 +02:00
README.md	refactor: restructure docs, sync stacks with Caddyfile, harden compose templates	2026-07-03 17:45:16 +02:00
template.yaml	refactor: restructure docs, sync stacks with Caddyfile, harden compose templates	2026-07-03 17:45:16 +02:00

README.md

Beszel Hub

Central web dashboard for Beszel server monitoring. Agents (see beszel-agent) connect to this hub and report host and Docker container metrics.

Persistent Data

All hub state (PocketBase database, system records, alert config) is stored in the Docker-managed named volume beszel_hub_data.

Installation

Create .env if it does not exist:
```
cp -n .env.sample .env
```

Adjust the values in .env if needed:

TZ=Africa/Johannesburg
BESZEL_HUB_PORT=8090
BESZEL_HUB_MEM_LIMIT=256m

DOCKERLOGGING_MAXFILE=3
DOCKERLOGGING_MAXSIZE=10m

Deploy with make:

make deploy-beszel-hub

Manual equivalent:

./substitute_env.sh docker-compose-files/beszel-hub/template.yaml docker-compose.beszel-hub.yml .env
docker compose -f docker-compose.beszel-hub.yml config --quiet
docker compose -f docker-compose.beszel-hub.yml up -d

Open http://<host-ip>:8090 and create the admin account.

Connecting Agents

In the hub, click Add System and enter the agent host's IP and port (default 45876).
Copy the public key / token shown in the dialog into the agent's .env (BESZEL_AGENT_KEY, BESZEL_AGENT_TOKEN, and BESZEL_AGENT_HUB_URL=http://<hub-ip>:8090), then deploy the agent:
```
make deploy-beszel
```

Reverse Proxy

The Caddyfile proxies beszel.<domain> to this host on port 8090. After changing the port, update docker-compose-files/caddy/Caddyfile_template and run make reload-caddy.

Backup

Back up the beszel_hub_data named volume:

docker run --rm \
  -v beszel_hub_data:/data:ro \
  -v /opt/backups/beszel-hub:/backup \
  busybox tar czf /backup/beszel-hub-$(date +%Y%m%d).tar.gz -C /data .

Useful Commands

# Tail logs
docker compose -f docker-compose.beszel-hub.yml logs -f beszel-hub

# Recreate after an image update
docker compose -f docker-compose.beszel-hub.yml pull
docker compose -f docker-compose.beszel-hub.yml up -d