AGH Central

Central manager for several AdGuard Home instances: unified query logs and statistics, DNS cache flush, configuration sync with drift detection, alerting.

Version 1.0.0 · Go (Gin) backend · React/Vite dashboard · TimescaleDB · Docker Compose

Features

• Query logs & stats for all instances (hypertable, native compression, real-time continuous aggregates).
• Agents with catch-up: no query lost after an outage, restart or AdGuard Home log rotation.
• Sync (bakito/adguardhome-sync): automatic pre-sync config backup, readable status, drift detection, visible/pinnable image.
• Alerts: agent offline, ingestion stalled, sync stopped/error/drift, failed DB jobs → dashboard + webhook / e-mail.
• Security: HMAC-authenticated agents, AdGuard credentials encrypted at rest, secret rotation, roles (admin/viewer), login rate limit, SSO OpenID Connect with admin group.
• Multilingual: English (default) and French.

Architecture

AdGuard Home + agent (dns-01) ─┐
AdGuard Home + agent (dns-02) ─┼─ WebSocket (HMAC) ─► manager (API + dashboard) ─► TimescaleDB
                               └ /state cursor                   └─► adguardhome-sync containers (Docker socket)

No Redis, no mTLS collector. Encrypt agent traffic with an HTTPS reverse proxy (MANAGER_URL=https://…).

Quick start

See docs/INSTALL.md (installation, all environment variables, secret rotation).

cd manager && cp .env.example .env   # fill secrets: openssl rand -hex 32
docker compose up -d

Repository layout

Path	Content
manager/	Go API, WebSocket hub, sync manager, alert engine, migrations/, dashboard/ (React)
manager/internal/	Stdlib-only packages: secret, alerts, synclog, drift
agent/	Log forwarder, cursor/catch-up, config & cache handlers
scripts/db-diagnose.sql	DB size / compression / jobs / lag diagnostics
docs/INSTALL.md	Installation & configuration reference
CHANGELOG.md	Release notes

Development

cd manager && go vet ./... && go test ./...
cd agent   && go vet ./... && go test ./...
cd manager/dashboard && npm ci && npm run build

Adding a language: add a resource block in manager/dashboard/src/i18n/i18n.js and manager/locales/.

Documentation rule

README, docs/INSTALL.md, .env.example files and CHANGELOG are updated with every release, including any new environment variable.

Limitations

See Known limitations in docs/INSTALL.md.