# Nexuma

Nexuma is a multi-node VPN and proxy management platform. It lets you deploy VPN servers, manage users and subscriptions, and control everything from a single web interface.

## Features

- **Multi-node** — connect unlimited VPN servers, manage them from one place
- **Subscriptions** — per-user links with traffic limits, expiry, and auto-renewal
- **Multiple protocols** — VLESS, VMess, Trojan, Shadowsocks, Hysteria2, MTProto
- **Balance system** — user balance with deposits, withdrawals, and auto-charge on renewal
- **Traffic accounting** — per-subscription usage analytics
- **Telegram integration** — OAuth login, user approval flow, admin notifications
- **Routing rules** — xray-native rule sets and load balancers per node
- **Config builder** — guided wizard for protocol and stream configuration
- **Double VPN** — proxy chain support via node outbounds
- **External subscriptions** — aggregate external VPN share links into user subscriptions

## Architecture

```
┌───────────────────────────────────┐
│              Panel                │
│       (Admin Web Interface)       │
└────────────────┬──────────────────┘
                 │
┌────────────────▼──────────────────┐
│               Core                │
│        (Control Plane API)        │
│   PostgreSQL ◄────────► Redis     │
└──────┬────────────────────────────┘
       │
  ┌────┴──────────────┐
  ▼                   ▼
Node 1   . . .      Node N
```

## Quick Start

### 1. Deploy Core and Panel

Download [`docker-compose.base.yml`](./docker-compose.base.yml), fill in your values, and run:

```bash
docker compose -f docker-compose.base.yml up -d
```

Open `http://your-server:3010` — the first registered account becomes admin.

### 2. Deploy a Node

On each VPN server, download [`docker-compose.node.yml`](./docker-compose.node.yml).

1. In the admin panel, open **Nodes** and generate a registration code.
2. Set `CORE_URL` and `REGISTRATION_CODE` in the file.
3. Run:

```bash
docker compose -f docker-compose.node.yml up -d
```

The node registers with Core automatically on first start. After that, remove the `REGISTRATION_CODE` line.

## Documentation

- [Core](./core.md) — configuration and API reference
- [Node](./node.md) — setup and registration
- [Panel](./panel.md) — features overview