Reality VPN Server

Backend-only repository for the Reality VPN control plane.

This package contains:

• api/ - Go control API for auth, subscriptions, server catalog, connect-session issuance, and Telegram integration
• deploy/ - PostgreSQL + API Docker Compose stack
• scripts/ - local Windows/Laragon helper scripts for DB init, API start, smoke checks, and Telegram webhook/poller flows

Included features

• Go API backed by PostgreSQL
• JWT-based access tokens
• short-lived connect session issuance for Xray client runtime
• server catalog filtered by subscription plan
• admin API endpoints for users, servers, and app settings
• Telegram auth session flow
• Telegram Stars payment order handling
• audit logging for auth, admin mutations, and connect sessions
• basic in-memory rate limiting for login and Telegram webhook endpoints

Project tree

server-release/
  api/
  deploy/
  scripts/
  .env.example
  .gitignore
  README.md

Environment variables

Core API:

• API_PORT=8080
• API_BASE_URL=http://localhost:8080
• JWT_SECRET=<required, non-default>
• DEV_AUTH_ENABLED=false

PostgreSQL:

• POSTGRES_DB=reality_vpn
• POSTGRES_USER=reality_vpn
• POSTGRES_PASSWORD=change-me
• POSTGRES_HOST=localhost
• POSTGRES_PORT=5432
• POSTGRES_SSLMODE=disable
• POSTGRES_SUPERUSER=postgres
• POSTGRES_SUPER_DB=postgres

Telegram:

• TELEGRAM_BOT_TOKEN=
• TELEGRAM_BOT_USERNAME=
• TELEGRAM_WEBHOOK_SECRET=
• TELEGRAM_SUPPORT_HANDLE=@support

If Telegram integration is enabled, TELEGRAM_WEBHOOK_SECRET is required.

Local development login

The temporary email + code login flow is disabled by default.

To enable it for local development only:

1. set DEV_AUTH_ENABLED=true
2. set a non-default JWT_SECRET

Then you can log in with code 0000 against the local API.

Seeded development accounts:

• admin: starter@admin.local
• user: user@demo.local

Running with Docker Compose

From deploy/:

docker compose up

This starts:

1. PostgreSQL
2. Go API on http://localhost:8080

Running with Laragon on Windows

This machine already has usable toolchains inside C:\laragon:

• Go: C:\laragon\bin\go\go1.24.1\bin\go.exe
• Node: C:\laragon\bin\nodejs\node-v22\node.exe
• NPM: C:\laragon\bin\nodejs\node-v22\npm.cmd

Helper scripts:

1. powershell -ExecutionPolicy Bypass -File .\scripts\start-db.ps1
2. powershell -ExecutionPolicy Bypass -File .\scripts\init-db.ps1
3. powershell -ExecutionPolicy Bypass -File .\scripts\start-api.ps1
4. powershell -ExecutionPolicy Bypass -File .\scripts\smoke-api.ps1
5. powershell -ExecutionPolicy Bypass -File .\scripts\check.ps1
6. powershell -ExecutionPolicy Bypass -File .\scripts\set-telegram-webhook.ps1
7. powershell -ExecutionPolicy Bypass -File .\scripts\start-telegram-poller.ps1

Telegram auth and payments

Current flow:

1. Client calls POST /api/v1/auth/telegram/start
2. API creates a short Telegram auth session and returns a deep link to the bot
3. User presses Start in Telegram, bot confirms the session
4. Client polls GET /api/v1/auth/telegram/sessions/:id until it receives the access token
5. User buys a plan with /buy basic, /buy premium, or /buy maximum
6. Bot receives successful_payment, activates or extends the subscription

Webhook setup:

1. expose your API publicly over HTTPS
2. fill TELEGRAM_BOT_TOKEN, TELEGRAM_BOT_USERNAME, and TELEGRAM_WEBHOOK_SECRET
3. run powershell -ExecutionPolicy Bypass -File .\scripts\set-telegram-webhook.ps1 -ApiBaseUrl https://your-domain.example

For local development you can skip public webhook delivery and use polling instead:

1. start the API on 127.0.0.1:8080
2. run powershell -ExecutionPolicy Bypass -File .\scripts\start-telegram-poller.ps1
3. talk to the bot in Telegram, and the poller will forward updates into the local API

Verification

Run:

powershell -ExecutionPolicy Bypass -File .\scripts\check.ps1

This will:

1. initialize PostgreSQL
2. run go test ./...
3. run the API smoke check