docs/README.md

# Nexuma Documentation

Nexuma is a multi-node VPN and proxy management platform. It provides a central web panel, a control API, and node agents that run on VPN/proxy servers.

This documentation repository is self-contained. The examples below use published container images and do not require access to the application source repositories.

## What Nexuma Provides

- Central management for users, tariffs, subscriptions, nodes, routing, and audit logs.
- Public subscription links for VPN clients.
- Per-user traffic limits, expiry, balance, and auto-renewal.
- Multi-node deployment with per-node protocol configuration.
- Supported subscription exports: `v2ray`, `clash`, and `singbox`.
- Supported protocols: VLESS, VMess, Trojan, Shadowsocks, HTTP, SOCKS, WireGuard, Hysteria, and MTProto.
- Routing rule sets, traffic blocking options, and node outbounds for proxy chains.
- External subscription sources that can be appended to user subscriptions.
- Telegram login, approval flow, and notifications when configured.

## Main Components

```text
Users and admins
       |
       v
Panel - web interface and public subscription page
       |
       v
Core  - API, state, subscription generation, node coordination
       |
       v
Nodes - VPN/proxy servers that apply configs and report usage
```

## Quick Start

### 1. Deploy Core and Panel

Create a `docker-compose.yml` from the base example:

```yaml
version: '3.9'

services:
  postgres:
    image: postgres:16-alpine
    container_name: nexuma-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: nexuma
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - nexuma

  redis:
    image: redis:7-alpine
    container_name: nexuma-redis
    restart: unless-stopped
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - nexuma

  core:
    image: nexuma/core:latest
    container_name: nexuma-core
    restart: unless-stopped
    environment:
      PORT: 3000
      GRPC_PORT: 3002
      DB_HOST: postgres
      DB_PORT: 5432
      DB_USER: postgres
      DB_PASSWORD: change-me
      DB_NAME: nexuma
      REDIS_HOST: redis
      REDIS_PORT: 6379
      JWT_SECRET: replace-with-long-random-secret
      JWT_REFRESH_SECRET: replace-with-another-long-random-secret
      JWT_EXPIRES_IN: 15m
      JWT_REFRESH_EXPIRES_IN: 7d
      CORS_ORIGINS: https://panel.example.com
    ports:
      - "3000:3000"
      - "3002:3002"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - nexuma

  panel:
    image: nexuma/panel:latest
    container_name: nexuma-panel
    restart: unless-stopped
    environment:
      NUXT_CORE_URL: http://core:3000
      NUXT_PUBLIC_API_BASE: /api
    ports:
      - "3010:3000"
    depends_on:
      - core
    networks:
      - nexuma

volumes:
  postgres_data:
  redis_data:

networks:
  nexuma:
    driver: bridge
```

Run:

```bash
docker compose up -d
```

Open `http://your-server:3010`.

### 2. Create the First Admin

Register the first user in the panel. Promote or seed an admin according to your deployment policy before exposing the system publicly.

### 3. Deploy a Node

In the panel, open `Nodes` and generate a registration code. Then deploy a node on the VPN/proxy server:

```yaml
version: '3.9'

services:
  node:
    image: nexuma/node:latest
    container_name: nexuma-node
    restart: unless-stopped
    environment:
      PORT: 3001
      CORE_URL: https://core.example.com
      CORE_GRPC_URL: core.example.com:3002
      REGISTRATION_CODE: paste-one-time-code-here
      HEARTBEAT_INTERVAL_SEC: 30
    volumes:
      - node_data:/var/lib/vpnnode
    ports:
      - "3001:3001"
    cap_add:
      - NET_ADMIN

volumes:
  node_data:
```

Run:

```bash
docker compose up -d
```

After the node registers successfully, remove `REGISTRATION_CODE` and redeploy. Keep the `node_data` volume; it contains the persistent node auth key and local service state.

## Documentation Index

- [Core](./core.md) - control API, environment, Docker, public/user/admin API, and node-private API overview.
- [Panel](./panel.md) - operator UI, self-service UI, routes, environment, Docker, and API behavior.
- [Node](./node.md) - node agent setup, registration, environment, Docker, local endpoints, and operations.
- [Core API routes](./core-routes.md) - detailed Core route table.
- [Core private node routes](./core-private-routes.md) - node-to-Core private API contract.

## Security Checklist

- Replace all example secrets before production.
- Use HTTPS for public panel and Core endpoints.
- Restrict Core API exposure with firewall or reverse-proxy rules.
- Restrict node agent ports to trusted networks.
- Remove one-time node registration codes after successful registration.
- Rotate node auth keys when a node is rebuilt or compromised.
- Keep database and Redis inaccessible from the public internet.