Fleet management control plane for Telemt MTProto proxy nodes

Quick Install  •  Features  •  Architecture  •  Development  •  Docker

---

✨ Features

	Feature	Description
📊	Fleet Dashboard	Real-time monitoring with metrics, health indicators, and alerts
👥	Managed Clients	Centralized client management with secret rotation and quotas
🤖	Agent System	Lightweight per-node agents with mTLS enrollment and gRPC streaming
🗄️	Dual Storage	SQLite for dev/lightweight, PostgreSQL for production
🔄	Self-Update	Panel and agents update themselves from GitHub Releases
📦	Embedded UI	Single binary ships the React dashboard — no separate web server
🔐	TOTP 2FA	Optional two-factor authentication for operator accounts
🛡️	RBAC	Viewer, Operator, and Admin roles with middleware enforcement

---

🚀 Quick Install

Control Plane

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/lost-coder/panvex/main/deploy/install.sh)"

Interactive wizard: ports, storage, TLS, firewall, admin account — all configured step by step.

Agent

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/lost-coder/panvex/main/deploy/install-agent.sh)"

Requires a panel URL and enrollment token (create one in Settings → Enrollment Tokens).

📋 Non-interactive mode (CI / automation)

# Control Plane
PANVEX_ADMIN_PASS='<password>' \
PANVEX_HTTP_PORT=8080 \
PANVEX_GRPC_PORT=8443 \
  sudo -E bash install.sh

# Agent
PANVEX_PANEL_URL='https://panel.example.com' \
PANVEX_ENROLLMENT_TOKEN='<token>' \
  sudo -E bash install-agent.sh

Run bash install.sh --help for all environment variables.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                    🌐 Browser                        │
│           React · TanStack Router/Query              │
├─────────────────────────────────────────────────────┤
│              📡 Control Plane (:8080)                │
│        HTTP API · WebSocket · Embedded UI            │
├─────────────────────────────────────────────────────┤
│              🔒 gRPC Gateway (:8443)                 │
│         mTLS · Bidirectional Stream · Jobs           │
├─────────────────────────────────────────────────────┤
│              🤖 Agent (per Telemt node)              │
│       Heartbeats · Snapshots · Job Execution         │
└─────────────────────────────────────────────────────┘

📁 Repository Layout

Directory	Description
cmd/control-plane	Control plane server (HTTP + gRPC + embedded UI)
cmd/agent	Agent binary with bootstrap and enrollment
internal/controlplane	Auth, jobs, presence, storage, server logic
internal/agent	Telemt client, runtime, self-updater
internal/gatewayrpc	Generated gRPC stubs (protobuf)
internal/security	Enrollment, crypto, mTLS CA
web	React dashboard (Vite + TailwindCSS 4 + TanStack)
db/migrations	PostgreSQL and SQLite schema migrations
proto	Protobuf gateway contract
deploy	Install scripts, Docker Compose, nginx config

🔧 Tech Stack

Layer	Technology
Backend	Go 1.26, chi/v5, pgx/v5, modernc.org/sqlite, gRPC
Frontend	React 19, Vite 8, TailwindCSS 4, TanStack Router + Query
UI Kit	Inlined under web/src/ui/ — Radix UI primitives + CVA
Database	PostgreSQL (primary) · SQLite (lightweight)
Deploy	Multi-stage Docker · systemd · nginx

---

💻 Development

Prerequisites

• Go 1.26+  ·  Node.js 22+  ·  sqlc  ·  protoc + Go plugins

Backend

go build ./...                    # Build all
go test ./...                     # Run tests
go test -race ./...               # Race detector
golangci-lint run ./...           # Lint
sqlc generate                     # Regenerate DB code

Frontend

cd web
npm install                       # Install deps
npm run dev                       # Dev server (proxies API to :8080)
npm run build                     # Production build
npm run lint                      # ESLint

🏃 Local Development Flow

1. Bootstrap admin:

go run ./cmd/control-plane bootstrap-admin \
  -username admin \
  -password '<strong-password>'

2. Start control plane:

go run ./cmd/control-plane -http-addr :8080 -grpc-addr :8443

3. Start frontend dev server:

cd web && npm run dev

Dashboard at http://localhost:5173, API proxied to :8080

📦 Single binary build

cd web && npm run build:embed
cd .. && go build -tags embeddedui -o panvex-control-plane ./cmd/control-plane

---

🐳 Docker

Each compose file ships a bootstrap service under --profile bootstrap that creates the first admin one-shot. It refuses to plant an account on a non-empty store, so it's safe to re-run.

SQLite (lightweight)

# 1. First-run admin (run before bringing up the backend so the SQLite
#    file isn't contended).
PANVEX_BOOTSTRAP_PASSWORD='<strong-password>' \
  docker compose -f deploy/docker-compose.sqlite.yml \
    --profile bootstrap run --rm bootstrap

# 2. Start the stack.
docker compose -f deploy/docker-compose.sqlite.yml up --build -d

PostgreSQL (dev — default password, plaintext DB traffic)

# 1. Start Postgres + backend (creates schema on first boot).
docker compose -f deploy/docker-compose.postgres.yml up --build -d

# 2. First-run admin.
PANVEX_BOOTSTRAP_PASSWORD='<strong-password>' \
POSTGRES_PASSWORD='<db-password>' \
  docker compose -f deploy/docker-compose.postgres.yml \
    --profile bootstrap run --rm bootstrap

PostgreSQL (production — TLS, no default credentials)

# 1. Bring up the stack. Required env vars are enforced via ${VAR:?...}.
POSTGRES_PASSWORD='<strong-db-password>' \
PANVEX_ENCRYPTION_KEY='<strong-encryption-key>' \
  docker compose -f deploy/docker-compose.prod.yml up --build -d

# 2. First-run admin. Reuse the same PANVEX_ENCRYPTION_KEY so freshly
#    minted secrets are readable to the running backend.
POSTGRES_PASSWORD='<strong-db-password>' \
PANVEX_ENCRYPTION_KEY='<strong-encryption-key>' \
PANVEX_BOOTSTRAP_PASSWORD='<strong-admin-password>' \
  docker compose -f deploy/docker-compose.prod.yml \
    --profile bootstrap run --rm bootstrap

The prod profile refuses to start without POSTGRES_PASSWORD and PANVEX_ENCRYPTION_KEY, forces sslmode=require, sets resource limits, JSON-log rotation (15 MiB × 10), PANVEX_ENV=production, and binds publishers to loopback (terminate TLS at a reverse proxy — see deploy/nginx/default.conf).

Override the admin username via PANVEX_BOOTSTRAP_USERNAME (default: admin).

Dashboard: http://localhost:8080  ·  gRPC: localhost:8443

---

🤖 Agent Deployment

1. Create an enrollment token: Settings → Enrollment Tokens
2. On each Telemt server:

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/lost-coder/panvex/main/deploy/install-agent.sh)"

Manual bootstrap (without installer)

./panvex-agent bootstrap \
  -panel-url https://panel.example.com \
  -enrollment-token '<token>' \
  -state-file /var/lib/panvex-agent/agent-state.json

---

👥 Managed Clients

Create and manage Telemt clients centrally from the dashboard:

• 🔑 Generate secrets and user_ad_tag
• 📏 Set limits: connections, unique IPs, quota, expiration
• 🌐 Assign by fleet group or individual nodes
• 🔄 Rotate secrets without recreating the client
• 📈 Live deployment status, connection links, and usage per node

---

🔐 Security

Two-Factor Authentication — TOTP 2FA is optional. Enable in Profile page.

Emergency TOTP reset via CLI:

./panvex-control-plane reset-user-totp \
  -storage-driver sqlite \
  -storage-dsn /var/lib/panvex/panvex.db \
  -username admin

---

🔄 Updates

The control plane checks GitHub Releases for new versions automatically.

Method	Command
Dashboard	Settings → Updates → Update Panel / Update Agent
CLI	./panvex-control-plane self-update
Auto-update	Enable in Settings → Updates (disabled by default)

Agents can be updated individually or in bulk. The panel sends an update job via gRPC — the agent downloads and installs the new binary automatically.

---

_{Built with ❤️ for Telemt fleet operators}