Deploy the user portal

The user portal (freenet-user-portal) is the consumer-facing layer for a FreeNet deployment. Users register with an e-mail, get a VPN account provisioned automatically on your panel, and self-serve config downloads, QR codes, usage, and expiry from a web console.

The portal is fully independent of the panel: it talks to the panel only through the admin API (an HMAC API key) and public subscription URLs, keeps all of its own state in its own Postgres, and never touches panel code. A panel upgrade never breaks it.

consumer ──▶ user-portal :8082 ──▶ control plane API ──▶ gateway nodes
                 │
                 └──▶ freenet-sub-convert :8081 ──▶ /api/v1/sub/{token}?format=…

End users hit the portal’s /api/v1/sub/{token} endpoint, which proxies to the converter (or the panel’s raw vless:// endpoint when no converter is configured).

Two layers of identity, never mixed:

• Portal users — people: e-mail, password, orders.
• Panel accounts — VPN service instances: quota, expiry, peers.

The link is a binding table (user_id ↔ account_id plus the account’s subscription token, sealed with AES-256-GCM at rest). The portal is a proxy: it translates user intent into panel API calls, and a portal user never touches the panel directly.

With freenet-sub-convert deployed alongside, the same subscription URL serves every popular client: vless for VLESS-capable clients, plus clash / mihomo, singbox, surge, shadowrocket, and quantumultx. Users pick a platform and client in the portal’s Subscription page (/console/subscription), which offers one-click import links and per-client QR codes, or they paste the URL into their client and let User-Agent detection pick the format.