Brook Admin

Self-hosted control plane for a fleet of Brook VPN/proxy servers — users, access keys, servers, traffic analytics, RBAC, and a self-service user portal — with a polished bilingual (EN/RU) UI.

Features · Requirements · Quick Start · Production Install · User Portal · Admin Portal · Monitoring · Backup · Documentation

---

Features

• Multi-user & RBAC — super_admin, admin, support, viewer roles enforced in the backend; bootstrap super admin on first boot.
• Secure by default — server-side sessions in HttpOnly/Secure/SameSite cookies, CSRF double-submit, bcrypt password hashes, SHA-256 access-token hashes (plaintext shown once), AES-256-GCM encrypted server credentials.
• Access-key management — create, list, revoke, brook:// link + QR generation matching the upstream protocol.
• Server capability model — normalized detection with explicit "unavailable with current Brook deployment" states.
• Traffic & connections analytics — live health, per-server status, traffic usage, user connection state.
• Dashboard + global search — operational overview and cross-resource search.
• Self-service user portal — end users register, manage their own keys, devices, subscription view, notifications, and referral invites.
• Notifications — user inbox + preferences with an internal Notifier stub for subscription/maintenance/security events.
• Bilingual UI — English and Russian.
• Production-ready packaging — Docker Compose, Caddy automatic HTTPS, one-click installer, update/backup/restore scripts, optional Prometheus/Grafana monitoring.
• OpenAPI — generated API reference in docs/openapi.json.

Requirements

Environment	Requirements
Docker (dev)	Docker Engine 24+ and Docker Compose v2
Production (Ubuntu)	Ubuntu 24.04 LTS, 2 GB RAM, a domain pointing to this host (the installer installs Docker automatically)
Local development (no Docker)	Go 1.22+, Node.js 20+, npm

Quick Start (Docker)

Run the whole stack with Docker Compose (PostgreSQL + backend + frontend + Caddy):

cp .env.example .env            # fill in SESSION_SECRET, ADMIN_CSRF_SECRET, BOOTSTRAP_ADMIN_PASSWORD
docker compose up -d --build

Open http://localhost:8088 and log in with the bootstrap admin you set in .env (BOOTSTRAP_ADMIN_USERNAME / BOOTSTRAP_ADMIN_PASSWORD). Health check: http://localhost:8088/healthz.

Production Install

One-click installer for Ubuntu 24.04 LTS — no interactive prompts. It installs Docker if missing, copies the project to /opt/brook-admin, generates .env.production with random secrets, starts the stack, and waits for the backend health endpoint. The generated credentials are printed once.

sudo ./scripts/install-release.sh --domain YOUR.DOMAIN --email you@example.com

Then open https://YOUR.DOMAIN and log in with the admin credentials printed by the installer.

Manual alternative:

cp .env.production.example .env      # fill every required secret
sed -i 's/admin.example.com/YOUR.DOMAIN/' .env
sudo ./scripts/install.sh --domain YOUR.DOMAIN --email you@example.com

• docker-compose.prod.yml — postgres, backend, frontend, caddy, plus optional profiles: agents (Brook data-plane agent), updates (Watchtower), monitoring (Prometheus + Grafana).
• caddy/Caddyfile.prod — reverse proxy, automatic TLS, security headers, rate limiting, /metrics access control.
• scripts/install-release.sh — one-click installer (auto-generates secrets).
• scripts/install.sh — Docker install, firewall, build and start the stack.
• scripts/update.sh — backs up, pulls, rebuilds, migrates, and can roll back.
• scripts/backup.sh / scripts/restore.sh — see Backup & restore.

Required secrets (generated automatically by install-release.sh, or see .env.production.example for the manual path): SESSION_SECRET, ADMIN_CSRF_SECRET, POSTGRES_PASSWORD, BOOTSTRAP_ADMIN_PASSWORD, CADDY_DOMAIN.

Daily updates: sudo ./scripts/update.sh.

User Portal

A separate, cookie-authenticated credential domain where end users manage their own account — isolated from the admin panel.

• /portal/login, /portal/register — sign in / create an account.
• /portal/keys — create an access key (one-time token + link/QR), revoke it.
• /portal/devices — self-declared device registry.
• /portal/subscription — read-only current plan and available plans.
• /portal/notifications — inbox, unread count, mark read / mark all, prefs.
• /portal/connections — read-only own connection state.
• /portal/profile, /portal/security — email, change password, Telegram mapping status/unlink.
• /portal/referrals — referral code + invite management.

The portal is scoped to the user everywhere: users cannot read, revoke, link, or QR another user's keys, and a portal session cannot reach admin endpoints. See docs/user-portal.md.

Admin Portal

Operator UI (role-gated):

• Dashboard — overview, unread counters, key counts.
• Servers — register/status, capability matrix, health.
• Keys / Users / Traffic / Connections — full CRUD + analytics.
• Subscriptions & plans — manage plans and user subscriptions.
• Notifications — broadcast inbox + preferences.
• Audit — JSONL audit log browser.
• Settings — global settings (super admin only).
• Email templates — CRUD + preview endpoint.

Monitoring

Optional Prometheus + Grafana monitoring (monitoring profile) scrapes the backend /metrics; import monitoring/dashboard.json into Grafana.

docker compose --profile monitoring -f docker-compose.prod.yml up -d

See docs/monitoring.md.

Backup & Restore

# One-off backup (~/.env POSTGRES_* and BACKUP_* drive the target/retention)
sudo ./scripts/backup.sh

# Restore a snapshot
sudo ./scripts/restore.sh /var/backups/brook-admin/brookadmin-YYYYMMDD-HHMMSS.sql.gz

# Automate: add to cron, e.g. 0 3 * * * /opt/brook-admin/scripts/backup.sh

• Logical pg_dump → gzip → optional AES-256 encryption (openssl) with a sha256 checksum.
• Retention pruning via BACKUP_RETENTION_DAYS (default 14).
• Restore drops and recreates the database (confirm unless --force).

See docs/backup.md and docs/backups.md.

Documentation

Doc	Purpose
docs/architecture.md	Control-plane design, data model, capability model
docs/api.md / docs/api-contract.md	API reference and contract, errors, RBAC, session/CSRF
docs/openapi.json	OpenAPI spec
docs/security.md	Threat model + concrete controls
docs/deployment.md	Local + production deployment
docs/backup.md / docs/backups.md	Backup & restore
docs/monitoring.md	Prometheus/Grafana
docs/user-portal.md	Self-service portal
docs/brook-integration.md	Verified Brook capability matrix

License

MIT © Brook Admin contributors. See SECURITY.md for how to report vulnerabilities and CONTRIBUTING.md for how to contribute.