smueller/Mace-AIO-Discord-Bot---With-Dashboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

CodeX - Updated Readme

Browse Source
This commit is contained in:
RayExo
2026-07-18 11:13:42 +05:30
parent 7e4c4d9100
commit 145a429f15
3 changed files with 137 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
README.md
View File

@@ -10,7 +10,9 @@
``` ```
<h3>A feature-rich Discord bot paired with a sleek Next.js dashboard</h3> <h3>A feature-rich Discord bot paired with a sleek Next.js dashboard</h3>
<a href="https://nexiohost.in"><img src="https://img.shields.io/badge/⭐%20PREMIUM%20HOSTING-NexioHost-FFD700?style=for-the-badge&labelColor=1a1a2e&color=FFD700&logoColor=FFD700"/></a> <a href="https://nexiohost.in"><img src="https://img.shields.io/badge/⭐%20PREMIUM%20HOSTING-NexioHost-FFD700?style=for-the-badge&labelColor=1a1a2e&color=FFD700&logoColor=FFD700"/></a>
<p> <p>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white"/></a> <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white"/></a>
<a href="https://nextjs.org"><img src="https://img.shields.io/badge/Next.js-14+-000000?style=for-the-badge&logo=nextdotjs&logoColor=white"/></a> <a href="https://nextjs.org"><img src="https://img.shields.io/badge/Next.js-14+-000000?style=for-the-badge&logo=nextdotjs&logoColor=white"/></a>
@@ -38,7 +40,7 @@ ZyroX-CV2-With-Dashboard/
│ ├── api/ Dashboard REST API (FastAPI) │ ├── api/ Dashboard REST API (FastAPI)
│ ├── cogs/ All bot features (commands, events, antinuke, automod…) │ ├── cogs/ All bot features (commands, events, antinuke, automod…)
│ ├── core/ Bot client, context, cog base │ ├── core/ Bot client, context, cog base
│ ├── utils/ Shared utilities (emoji, tools, sync, ngrok tunnel…) │ ├── utils/ Shared utilities (emoji, tools, sync, cloudflare tunnel…)
│ ├── games/ Standalone game modules │ ├── games/ Standalone game modules
│ ├── assets/ Fonts, backgrounds, GIFs │ ├── assets/ Fonts, backgrounds, GIFs
│ └── CodeX.py Entry point │ └── CodeX.py Entry point
@@ -96,7 +98,7 @@ ZyroX-CV2-With-Dashboard/
- Per-server settings management - Per-server settings management
- Live bot stats & metrics - Live bot stats & metrics
- Fully branded & customisable - Fully branded & customisable
- HTTPS via ngrok static domain - HTTPS via Cloudflare Tunnel (permanent URL)
- Deploys to Vercel in minutes - Deploys to Vercel in minutes
</td> </td>
@@ -119,7 +121,7 @@ ZyroX-CV2-With-Dashboard/
- Jishaku eval support - Jishaku eval support
- Slash + prefix commands - Slash + prefix commands
- FastAPI backend with API key auth + rate limiting - FastAPI backend with API key auth + rate limiting
- ngrok HTTPS tunnel (pyngrok — works on Pterodactyl) - Cloudflare Tunnel — unlimited bandwidth, permanent URL, zero system installs
- CodeX Devs watermark on every source file - CodeX Devs watermark on every source file
</td> </td>
@@ -137,7 +139,7 @@ ZyroX-CV2-With-Dashboard/
| Lavalink node | v4 | | Lavalink node | v4 |
| Discord bot token | — | | Discord bot token | — |
| Discord OAuth app | for dashboard login | | Discord OAuth app | for dashboard login |
| ngrok account (free) | for HTTPS tunnel | | Cloudflare account (free) | for HTTPS tunnel |
--- ---
@@ -150,7 +152,7 @@ git clone https://github.com/RayExo/ZyroX-CV2-With-Dashboard
cd ZyroX-CV2-With-Dashboard/bot cd ZyroX-CV2-With-Dashboard/bot
``` ```
**2 — Create a virtual environment and install dependencies** **2 — Install dependencies**
```bash ```bash
python -m venv .venv python -m venv .venv
@@ -173,24 +175,28 @@ Copy `.env.example` to `.env` and fill in the values:
TOKEN = your_discord_bot_token TOKEN = your_discord_bot_token
brand_name = 'ZyroX' brand_name = 'ZyroX'
# ── Owner IDs (comma-separated) ───────────────────────────────────
OWNER_IDS = 870179991462236170,767979794411028491
# ── Lavalink ────────────────────────────────────────────────────── # ── Lavalink ──────────────────────────────────────────────────────
LAVALINK_HOST = "lava-v4.ajieblogs.eu.org" LAVALINK_HOST = "your-lavalink-host"
LAVALINK_PASSWORD = "your_password" LAVALINK_PASSWORD = "your_password"
LAVALINK_SECURE = "true" # true = HTTPS (no port needed) LAVALINK_SECURE = "true"
LAVALINK_PORT = "" # only needed when LAVALINK_SECURE=false LAVALINK_PORT = ""
# ── Emoji Sync ──────────────────────────────────────────────────── # ── Emoji Sync ────────────────────────────────────────────────────
EMOJI_SYNC = "true" # auto-uploads & patches emoji.py on startup EMOJI_SYNC = "true"
# ── API / Dashboard Backend ─────────────────────────────────────── # ── API / Dashboard Backend ───────────────────────────────────────
API_ENABLED = "true" API_ENABLED = "true"
API_PORT = "8000" API_PORT = "8000"
DASHBOARD_API_KEY = "change_this_to_a_strong_secret" DASHBOARD_API_KEY = "change_this_to_a_strong_secret"
CORS_ORIGINS = ""
# ── HTTPS Tunnel (ngrok) ────────────────────────────────────────── # ── Cloudflare Tunnel ─────────────────────────────────────────────
TUNNEL_ENABLED = "true" TUNNEL_ENABLED = "true"
NGROK_AUTHTOKEN = "your_ngrok_authtoken" CF_TUNNEL_TOKEN = "your_tunnel_token"
NGROK_DOMAIN = "xxxx-xxxx-xxxx.ngrok-free.app" CF_TUNNEL_URL = "https://api.yourdomain.com"
# ── Webhooks ────────────────────────────────────────────────────── # ── Webhooks ──────────────────────────────────────────────────────
WEBHOOK_URL = "https://discord.com/api/webhooks/..." WEBHOOK_URL = "https://discord.com/api/webhooks/..."
@@ -215,10 +221,10 @@ npm install
**2 — Configure the environment** **2 — Configure the environment**
Copy `.env.example` to `.env.local` and fill in the values: Copy `.env.example` to `.env.local`:
```env ```env
NEXT_PUBLIC_API_URL = https://xxxx.ngrok-free.app/api/v1 NEXT_PUBLIC_API_URL = https://api.yourdomain.com/api/v1
NEXT_PUBLIC_DASHBOARD_API_KEY = your_shared_api_key NEXT_PUBLIC_DASHBOARD_API_KEY = your_shared_api_key
NEXTAUTH_URL = http://localhost:3000 NEXTAUTH_URL = http://localhost:3000
@@ -249,6 +255,7 @@ Open [http://localhost:3000](http://localhost:3000)
| Variable | Default | Description | | Variable | Default | Description |
|---|---|---| |---|---|---|
| `TOKEN` | — | Discord bot token | | `TOKEN` | — | Discord bot token |
| `OWNER_IDS` | — | Comma-separated owner Discord user IDs |
| `LAVALINK_HOST` | — | Lavalink server hostname (no protocol) | | `LAVALINK_HOST` | — | Lavalink server hostname (no protocol) |
| `LAVALINK_PASSWORD` | — | Lavalink password | | `LAVALINK_PASSWORD` | — | Lavalink password |
| `LAVALINK_SECURE` | `true` | `true` = HTTPS, `false` = HTTP | | `LAVALINK_SECURE` | `true` | `true` = HTTPS, `false` = HTTP |
@@ -257,16 +264,17 @@ Open [http://localhost:3000](http://localhost:3000)
| `API_ENABLED` | `true` | Start the FastAPI dashboard backend | | `API_ENABLED` | `true` | Start the FastAPI dashboard backend |
| `API_PORT` | `8000` | Port the backend listens on | | `API_PORT` | `8000` | Port the backend listens on |
| `DASHBOARD_API_KEY` | — | Shared secret between bot API and dashboard | | `DASHBOARD_API_KEY` | — | Shared secret between bot API and dashboard |
| `CORS_ORIGINS` | _(empty)_ | Extra CORS-allowed origins, comma-separated |
| `WEBHOOK_URL` | — | Discord webhook for command logs | | `WEBHOOK_URL` | — | Discord webhook for command logs |
| `TUNNEL_ENABLED` | `true` | Expose the API over HTTPS via ngrok | | `TUNNEL_ENABLED` | `true` | Expose the API over HTTPS via Cloudflare Tunnel |
| `NGROK_AUTHTOKEN` | — | ngrok auth token | | `CF_TUNNEL_TOKEN` | — | Token from Cloudflare Zero Trust dashboard |
| `NGROK_DOMAIN` | — | Reserved static domain (e.g. `xxxx.ngrok-free.app`) | | `CF_TUNNEL_URL` | — | Your permanent public URL (e.g. `https://api.yourdomain.com`) |
### Dashboard — `dashboard/.env.local` ### Dashboard — `dashboard/.env.local`
| Variable | Description | | Variable | Description |
|---|---| |---|---|
| `NEXT_PUBLIC_API_URL` | Full URL to the bot's FastAPI backend (use ngrok URL in production) | | `NEXT_PUBLIC_API_URL` | Full URL to the bot's FastAPI backend — use Cloudflare Tunnel URL |
| `NEXT_PUBLIC_DASHBOARD_API_KEY` | Must match `DASHBOARD_API_KEY` in the bot | | `NEXT_PUBLIC_DASHBOARD_API_KEY` | Must match `DASHBOARD_API_KEY` in the bot |
| `NEXTAUTH_URL` | Your dashboard's public URL | | `NEXTAUTH_URL` | Your dashboard's public URL |
| `NEXTAUTH_SECRET` | Random secret for NextAuth session signing | | `NEXTAUTH_SECRET` | Random secret for NextAuth session signing |
@@ -278,31 +286,37 @@ Open [http://localhost:3000](http://localhost:3000)
--- ---
## ✦ HTTPS Tunnel (ngrok) ## ✦ HTTPS Tunnel (Cloudflare)
The bot uses **pyngrok** to expose the API over HTTPS — no system installs needed, works on Pterodactyl and any Python host. The bot uses **pycloudflared** — a Python package that downloads the `cloudflared` binary automatically on first run. No CLI installs, no system packages — works on Pterodactyl and any Python host.
With a free ngrok static domain the URL never changes between restarts. **Why Cloudflare over ngrok:**
- ✅ Unlimited bandwidth & requests — no monthly caps
- ✅ Permanent URL that never changes between restarts
- ✅ Free — no paid plan needed
- ✅ Zero system installs — binary downloads via Python
**One-time setup:** **Setup (browser only, no CLI needed):**
```bash 1. Go to [one.dash.cloudflare.com](https://one.dash.cloudflare.com) → **Networks → Tunnels → Create a tunnel**
# 1. Sign up free at https://ngrok.com 2. Choose **Cloudflared**, give it a name (e.g. `zyrox-api`), save
# 2. Get your authtoken: https://dashboard.ngrok.com/get-started/your-authtoken 3. On the **Install connector** step, copy the token from the command shown:
# 3. Reserve a static domain: https://dashboard.ngrok.com/domains
``` ```
cloudflared tunnel run --token <COPY_THIS>
Add to `bot/.env`: ```
4. Go to **Public Hostname** tab → add a hostname:
- Subdomain: `api` · Domain: `yourdomain.com` · Service: `http://localhost:8000`
5. Add to `bot/.env`:
```env ```env
TUNNEL_ENABLED = "true" CF_TUNNEL_TOKEN = "eyJhIjoiXXXX..."
NGROK_AUTHTOKEN = "your_token" CF_TUNNEL_URL = "https://api.yourdomain.com"
NGROK_DOMAIN = "xxxx.ngrok-free.app"
``` ```
On every startup the console prints: On every startup the console prints:
``` ```
◈ Tunnel: API is live at https://xxxx.ngrok-free.app ◈ Tunnel: cloudflared binary ready — starting tunnel on port 8000…
↳ set NEXT_PUBLIC_API_URL=https://xxxx.ngrok-free.app/api/v1 ◈ Tunnel: API is live at https://api.yourdomain.com
↳ NEXT_PUBLIC_API_URL = https://api.yourdomain.com/api/v1
``` ```
--- ---
@@ -314,7 +328,7 @@ On every startup the console prints:
1. Upload the entire `bot/` folder to your host (Pterodactyl, Render, Railway, Fly.io, VPS…) 1. Upload the entire `bot/` folder to your host (Pterodactyl, Render, Railway, Fly.io, VPS…)
2. Set the start command to `python CodeX.py` 2. Set the start command to `python CodeX.py`
3. Add all environment variables 3. Add all environment variables
4. pyngrok downloads the ngrok binary automatically on first run — no extra steps 4. `pycloudflared` downloads the binary automatically on first run — no extra steps
> Recommended free/cheap hosts: Render · Railway · Fly.io · VPS > Recommended free/cheap hosts: Render · Railway · Fly.io · VPS
> >
@@ -364,9 +378,9 @@ Runs automatically on startup when `EMOJI_SYNC=true`:
| Dashboard auth error | Check Discord OAuth client ID/secret and redirect URI | | Dashboard auth error | Check Discord OAuth client ID/secret and redirect URI |
| Dashboard can't load data | Confirm `API_ENABLED=true`, bot is running, `NEXT_PUBLIC_API_URL` is correct | | Dashboard can't load data | Confirm `API_ENABLED=true`, bot is running, `NEXT_PUBLIC_API_URL` is correct |
| Emojis showing as plain text | Run with `EMOJI_SYNC=true` once to upload and patch IDs | | Emojis showing as plain text | Run with `EMOJI_SYNC=true` once to upload and patch IDs |
| CORS errors from dashboard | Make sure your Vercel URL is in the CORS origins list or add it via `CORS_ORIGINS` env var | | CORS errors from dashboard | Add your Vercel URL to `CORS_ORIGINS` in `bot/.env` |
| Tunnel not starting | Check `NGROK_AUTHTOKEN` is valid — get it from [dashboard.ngrok.com](https://dashboard.ngrok.com) | | Tunnel not starting | Check `CF_TUNNEL_TOKEN` is valid and `pycloudflared` is installed |
| Tunnel URL changes on restart | Set `NGROK_DOMAIN` to your reserved static domain | | Tunnel URL changed | Set `CF_TUNNEL_URL` — named tunnels always produce the same URL |
--- ---
@@ -385,6 +399,8 @@ Runs automatically on startup when `EMOJI_SYNC=true`:
*Built for protection. Designed for style.* *Built for protection. Designed for style.*
<a href="https://discord.gg/codexdev"><img src="https://discord.com/api/guilds/1301573144817045524/widget.png?style=banner2" alt="CodeX Development Discord Server" width="480"/></a>
<p> <p>
<a href="https://discord.gg/codexdev"><img src="https://img.shields.io/badge/Discord-Join_Server-5865F2?style=for-the-badge&logo=discord&logoColor=white"/></a> <a href="https://discord.gg/codexdev"><img src="https://img.shields.io/badge/Discord-Join_Server-5865F2?style=for-the-badge&logo=discord&logoColor=white"/></a>
<a href="https://youtube.com/@CodeXDevs"><img src="https://img.shields.io/badge/YouTube-CodeXDevs-FF0000?style=for-the-badge&logo=youtube&logoColor=white"/></a> <a href="https://youtube.com/@CodeXDevs"><img src="https://img.shields.io/badge/YouTube-CodeXDevs-FF0000?style=for-the-badge&logo=youtube&logoColor=white"/></a>

83
bot/README.md
View File

@@ -10,7 +10,9 @@
``` ```
<h3>ZyroX Bot — Python Discord Bot + FastAPI Backend</h3> <h3>ZyroX Bot — Python Discord Bot + FastAPI Backend</h3>
<a href="https://nexiohost.in"><img src="https://img.shields.io/badge/⭐%20PREMIUM%20HOSTING-NexioHost-FFD700?style=for-the-badge&labelColor=1a1a2e&color=FFD700&logoColor=FFD700"/></a> <a href="https://nexiohost.in"><img src="https://img.shields.io/badge/⭐%20PREMIUM%20HOSTING-NexioHost-FFD700?style=for-the-badge&labelColor=1a1a2e&color=FFD700&logoColor=FFD700"/></a>
<p> <p>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white"/></a> <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white"/></a>
<a href="https://fastapi.tiangolo.com"><img src="https://img.shields.io/badge/FastAPI-Backend-009688?style=for-the-badge&logo=fastapi&logoColor=white"/></a> <a href="https://fastapi.tiangolo.com"><img src="https://img.shields.io/badge/FastAPI-Backend-009688?style=for-the-badge&logo=fastapi&logoColor=white"/></a>
@@ -29,7 +31,7 @@
## ✦ Overview ## ✦ Overview
This folder contains the ZyroX Discord bot built on `discord.py v2` alongside a `FastAPI` backend that powers the web dashboard. It handles all server moderation, music, leveling, mini-games, and utility features — all from a single `python CodeX.py` command. This folder contains the ZyroX Discord bot built on `discord.py v2` alongside a `FastAPI` backend that powers the web dashboard. Everything runs from a single `python CodeX.py` command.
``` ```
bot/ bot/
@@ -44,7 +46,7 @@ bot/
│ └── zyrox/ Core ZyroX feature cogs │ └── zyrox/ Core ZyroX feature cogs
├── core/ Bot client, context, cog base classes ├── core/ Bot client, context, cog base classes
├── games/ Standalone game logic + button views ├── games/ Standalone game logic + button views
├── utils/ Emoji, tools, sync, ngrok tunnel ├── utils/ Emoji, tools, sync, Cloudflare tunnel
├── assets/ Fonts, backgrounds, GIFs ├── assets/ Fonts, backgrounds, GIFs
└── CodeX.py Entry point └── CodeX.py Entry point
``` ```
@@ -132,7 +134,8 @@ bot/
- Jishaku eval support - Jishaku eval support
- Application emoji auto-sync - Application emoji auto-sync
- Slash + prefix commands - Slash + prefix commands
- ngrok HTTPS tunnel (pyngrok — no system install) - Cloudflare Tunnel via pycloudflared — zero system installs, unlimited traffic
- Single `OWNER_IDS` env var controls all permission checks
- CodeX Devs watermark on every source file - CodeX Devs watermark on every source file
</td> </td>
@@ -148,7 +151,7 @@ bot/
| Python 3.10+ | — | | Python 3.10+ | — |
| Lavalink v4 node | for music features | | Lavalink v4 node | for music features |
| Discord bot token | from Developer Portal | | Discord bot token | from Developer Portal |
| ngrok free account | for HTTPS tunnel | | Cloudflare account (free) | for HTTPS tunnel — browser setup only |
--- ---
@@ -170,18 +173,21 @@ pip install -r requirements.txt
### 2 — Configure environment ### 2 — Configure environment
Create a `.env` file in this folder: Create a `.env` file (copy from `.env.example`):
```env ```env
# ── Core ────────────────────────────────────────────────────────── # ── Core ──────────────────────────────────────────────────────────
TOKEN = your_discord_bot_token TOKEN = your_discord_bot_token
brand_name = 'ZyroX' brand_name = 'ZyroX'
# ── Owner IDs (comma-separated — no code changes needed) ──────────
OWNER_IDS = 870179991462236170,767979794411028491
# ── Lavalink ────────────────────────────────────────────────────── # ── Lavalink ──────────────────────────────────────────────────────
LAVALINK_HOST = "lava-v4.ajieblogs.eu.org" LAVALINK_HOST = "your-lavalink-host"
LAVALINK_PASSWORD = "your_password" LAVALINK_PASSWORD = "your_password"
LAVALINK_SECURE = "true" # true = HTTPS (no port needed) LAVALINK_SECURE = "true"
LAVALINK_PORT = "" # only needed when LAVALINK_SECURE=false LAVALINK_PORT = ""
# ── Emoji Sync ──────────────────────────────────────────────────── # ── Emoji Sync ────────────────────────────────────────────────────
EMOJI_SYNC = "true" EMOJI_SYNC = "true"
@@ -190,12 +196,12 @@ EMOJI_SYNC = "true"
API_ENABLED = "true" API_ENABLED = "true"
API_PORT = "8000" API_PORT = "8000"
DASHBOARD_API_KEY = "change_this_to_a_strong_secret" DASHBOARD_API_KEY = "change_this_to_a_strong_secret"
CORS_ORIGINS = "" # extra allowed origins, comma-separated CORS_ORIGINS = ""
# ── HTTPS Tunnel (ngrok) ────────────────────────────────────────── # ── Cloudflare Tunnel ─────────────────────────────────────────────
TUNNEL_ENABLED = "true" TUNNEL_ENABLED = "true"
NGROK_AUTHTOKEN = "your_ngrok_authtoken" CF_TUNNEL_TOKEN = "your_tunnel_token"
NGROK_DOMAIN = "xxxx-xxxx-xxxx.ngrok-free.app" CF_TUNNEL_URL = "https://api.yourdomain.com"
# ── Webhooks ────────────────────────────────────────────────────── # ── Webhooks ──────────────────────────────────────────────────────
WEBHOOK_URL = "https://discord.com/api/webhooks/..." WEBHOOK_URL = "https://discord.com/api/webhooks/..."
@@ -214,6 +220,7 @@ python CodeX.py
| Variable | Default | Description | | Variable | Default | Description |
|---|---|---| |---|---|---|
| `TOKEN` | — | Discord bot token | | `TOKEN` | — | Discord bot token |
| `OWNER_IDS` | — | Comma-separated owner Discord user IDs |
| `LAVALINK_HOST` | — | Lavalink server hostname (no protocol) | | `LAVALINK_HOST` | — | Lavalink server hostname (no protocol) |
| `LAVALINK_PASSWORD` | — | Lavalink password | | `LAVALINK_PASSWORD` | — | Lavalink password |
| `LAVALINK_SECURE` | `true` | `true` = HTTPS, `false` = HTTP | | `LAVALINK_SECURE` | `true` | `true` = HTTPS, `false` = HTTP |
@@ -224,27 +231,47 @@ python CodeX.py
| `DASHBOARD_API_KEY` | — | Shared secret between bot API and dashboard | | `DASHBOARD_API_KEY` | — | Shared secret between bot API and dashboard |
| `CORS_ORIGINS` | _(empty)_ | Extra CORS-allowed origins, comma-separated | | `CORS_ORIGINS` | _(empty)_ | Extra CORS-allowed origins, comma-separated |
| `WEBHOOK_URL` | — | Discord webhook for command logs | | `WEBHOOK_URL` | — | Discord webhook for command logs |
| `TUNNEL_ENABLED` | `true` | Expose API over HTTPS via ngrok | | `TUNNEL_ENABLED` | `true` | Expose API over HTTPS via Cloudflare Tunnel |
| `NGROK_AUTHTOKEN` | — | ngrok auth token | | `CF_TUNNEL_TOKEN` | — | Token from Cloudflare Zero Trust dashboard |
| `NGROK_DOMAIN` | — | Reserved static domain (e.g. `xxxx.ngrok-free.app`) | | `CF_TUNNEL_URL` | — | Your permanent public URL |
--- ---
## ✦ HTTPS Tunnel (ngrok) ## ✦ HTTPS Tunnel (Cloudflare)
Uses **pyngrok** — downloads the ngrok binary automatically on first run. No system installs, works on Pterodactyl and any Python host. Uses **pycloudflared** — downloads the `cloudflared` binary automatically on first run. No system installs, no CLI, works on Pterodactyl and any Python host.
### One-time setup **Why Cloudflare over ngrok:**
1. Sign up free at [ngrok.com](https://ngrok.com) | | Cloudflare Tunnel | ngrok free |
2. Copy your authtoken from [dashboard.ngrok.com/get-started/your-authtoken](https://dashboard.ngrok.com/get-started/your-authtoken) |---|---|---|
3. Reserve a free static domain at [dashboard.ngrok.com/domains](https://dashboard.ngrok.com/domains) — looks like `xxxx.ngrok-free.app` | Bandwidth | Unlimited | 1 GB/month |
4. Add `NGROK_AUTHTOKEN` and `NGROK_DOMAIN` to `.env` | Requests | Unlimited | 10k/month |
| URL stability | Permanent | Permanent (1 domain) |
| System install | ❌ Not needed | ❌ Not needed |
| Cost | Free | Free |
**Setup (browser only — no CLI needed):**
1. Go to [one.dash.cloudflare.com](https://one.dash.cloudflare.com) → **Networks → Tunnels → Create a tunnel**
2. Choose **Cloudflared**, name it (e.g. `zyrox-api`), save
3. On **Install connector**, copy the token from the command shown:
```
cloudflared tunnel run --token <COPY_THIS_TOKEN>
```
4. On **Public Hostname** tab → add a hostname:
- Subdomain: `api` · Domain: `yourdomain.com` · Service: `http://localhost:8000`
5. Add to `.env`:
```env
CF_TUNNEL_TOKEN = "eyJhIjoiXXXX..."
CF_TUNNEL_URL = "https://api.yourdomain.com"
```
On every startup the console prints: On every startup the console prints:
``` ```
◈ Tunnel: API is live at https://xxxx.ngrok-free.app ◈ Tunnel: cloudflared binary ready — starting tunnel on port 8000…
↳ set NEXT_PUBLIC_API_URL=https://xxxx.ngrok-free.app/api/v1 ◈ Tunnel: API is live at https://api.yourdomain.com
↳ NEXT_PUBLIC_API_URL = https://api.yourdomain.com/api/v1
``` ```
Set `TUNNEL_ENABLED=false` to disable. Set `TUNNEL_ENABLED=false` to disable.
@@ -272,7 +299,7 @@ Upload the entire `bot/` folder to your host and set the start command to:
python CodeX.py python CodeX.py
``` ```
pyngrok downloads the ngrok binary on first run — no extra steps needed on any host. `pycloudflared` downloads the binary on first run — no extra steps on any host.
> Recommended free hosts: Render · Railway · Fly.io · Pterodactyl > Recommended free hosts: Render · Railway · Fly.io · Pterodactyl
> >
@@ -289,8 +316,8 @@ pyngrok downloads the ngrok binary on first run — no extra steps needed on any
| Dashboard can't reach API | Check `API_ENABLED=true` and `NEXT_PUBLIC_API_URL` in dashboard | | Dashboard can't reach API | Check `API_ENABLED=true` and `NEXT_PUBLIC_API_URL` in dashboard |
| CORS errors | Add your Vercel URL to `CORS_ORIGINS` in `.env` | | CORS errors | Add your Vercel URL to `CORS_ORIGINS` in `.env` |
| Emojis showing as plain text | Run once with `EMOJI_SYNC=true` to upload and patch IDs | | Emojis showing as plain text | Run once with `EMOJI_SYNC=true` to upload and patch IDs |
| Tunnel not starting | Check `NGROK_AUTHTOKEN` is valid | | Tunnel not starting | Check `CF_TUNNEL_TOKEN` is valid and `pycloudflared` is installed |
| Tunnel URL changes each restart | Set `NGROK_DOMAIN` to your reserved static domain | | Want to add an owner | Add their ID to `OWNER_IDS` in `.env` — no code changes needed |
--- ---
@@ -300,6 +327,8 @@ pyngrok downloads the ngrok binary on first run — no extra steps needed on any
*Built for protection. Designed for style.* *Built for protection. Designed for style.*
<a href="https://discord.gg/codexdev"><img src="https://discord.com/api/guilds/1301573144817045524/widget.png?style=banner2" alt="CodeX Development Discord Server" width="480"/></a>
<p> <p>
<a href="https://discord.gg/codexdev"><img src="https://img.shields.io/badge/Discord-Join_Server-5865F2?style=for-the-badge&logo=discord&logoColor=white"/></a> <a href="https://discord.gg/codexdev"><img src="https://img.shields.io/badge/Discord-Join_Server-5865F2?style=for-the-badge&logo=discord&logoColor=white"/></a>
<a href="https://youtube.com/@CodeXDevs"><img src="https://img.shields.io/badge/YouTube-CodeXDevs-FF0000?style=for-the-badge&logo=youtube&logoColor=white"/></a> <a href="https://youtube.com/@CodeXDevs"><img src="https://img.shields.io/badge/YouTube-CodeXDevs-FF0000?style=for-the-badge&logo=youtube&logoColor=white"/></a>

40
dashboard/README.md
View File

@@ -10,7 +10,9 @@
``` ```
<h3>ZyroX Dashboard — Next.js Web Interface</h3> <h3>ZyroX Dashboard — Next.js Web Interface</h3>
<a href="https://nexiohost.in"><img src="https://img.shields.io/badge/⭐%20PREMIUM%20HOSTING-NexioHost-FFD700?style=for-the-badge&labelColor=1a1a2e&color=FFD700&logoColor=FFD700"/></a> <a href="https://nexiohost.in"><img src="https://img.shields.io/badge/⭐%20PREMIUM%20HOSTING-NexioHost-FFD700?style=for-the-badge&labelColor=1a1a2e&color=FFD700&logoColor=FFD700"/></a>
<p> <p>
<a href="https://nextjs.org"><img src="https://img.shields.io/badge/Next.js-14+-000000?style=for-the-badge&logo=nextdotjs&logoColor=white"/></a> <a href="https://nextjs.org"><img src="https://img.shields.io/badge/Next.js-14+-000000?style=for-the-badge&logo=nextdotjs&logoColor=white"/></a>
<a href="https://typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-5+-3178C6?style=for-the-badge&logo=typescript&logoColor=white"/></a> <a href="https://typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-5+-3178C6?style=for-the-badge&logo=typescript&logoColor=white"/></a>
@@ -29,7 +31,7 @@
## ✦ Overview ## ✦ Overview
This folder contains the ZyroX web dashboard built with `Next.js 14` (App Router), `TypeScript`, and `Tailwind CSS`. It connects to the bot's FastAPI backend via HTTPS (ngrok tunnel) and lets server admins manage all bot settings through a sleek, branded UI. This folder contains the ZyroX web dashboard built with `Next.js 14` (App Router), `TypeScript`, and `Tailwind CSS`. It connects to the bot's FastAPI backend via a permanent Cloudflare Tunnel HTTPS URL and lets server admins manage all bot settings through a sleek, branded UI.
``` ```
dashboard/ dashboard/
@@ -66,7 +68,7 @@ dashboard/
- **Live bot stats** — real-time metrics pulled from the FastAPI backend - **Live bot stats** — real-time metrics pulled from the FastAPI backend
- **Admin panel** — owner-only configuration and announcements - **Admin panel** — owner-only configuration and announcements
- **Fully branded** — name, logo, and colours via environment variables - **Fully branded** — name, logo, and colours via environment variables
- **HTTPS ready** — works with the bot's ngrok static domain out of the box - **HTTPS ready** — connects to the bot's permanent Cloudflare Tunnel URL
- **Vercel-ready** — deploys in minutes with zero config changes - **Vercel-ready** — deploys in minutes with zero config changes
--- ---
@@ -95,8 +97,8 @@ Create a `.env.local` file in this folder:
```env ```env
# ── Bot API ─────────────────────────────────────────────────────── # ── Bot API ───────────────────────────────────────────────────────
# Use the ngrok static domain from the bot's tunnel # Use the Cloudflare Tunnel URL from the bot's console output
NEXT_PUBLIC_API_URL = https://xxxx-xxxx-xxxx.ngrok-free.app/api/v1 NEXT_PUBLIC_API_URL = https://api.yourdomain.com/api/v1
NEXT_PUBLIC_DASHBOARD_API_KEY = your_shared_api_key # must match bot's DASHBOARD_API_KEY NEXT_PUBLIC_DASHBOARD_API_KEY = your_shared_api_key # must match bot's DASHBOARD_API_KEY
# ── NextAuth ────────────────────────────────────────────────────── # ── NextAuth ──────────────────────────────────────────────────────
@@ -127,7 +129,7 @@ Open [http://localhost:3000](http://localhost:3000)
| Variable | Description | | Variable | Description |
|---|---| |---|---|
| `NEXT_PUBLIC_API_URL` | Full URL to the bot's FastAPI backend — use the ngrok static domain | | `NEXT_PUBLIC_API_URL` | Full URL to the bot's FastAPI backend — use the Cloudflare Tunnel URL |
| `NEXT_PUBLIC_DASHBOARD_API_KEY` | Must exactly match `DASHBOARD_API_KEY` in the bot `.env` | | `NEXT_PUBLIC_DASHBOARD_API_KEY` | Must exactly match `DASHBOARD_API_KEY` in the bot `.env` |
| `NEXTAUTH_URL` | Your dashboard's public URL (Vercel domain in production) | | `NEXTAUTH_URL` | Your dashboard's public URL (Vercel domain in production) |
| `NEXTAUTH_SECRET` | Random secret for NextAuth session signing | | `NEXTAUTH_SECRET` | Random secret for NextAuth session signing |
@@ -141,8 +143,6 @@ Open [http://localhost:3000](http://localhost:3000)
## ✦ Deployment (Vercel) ## ✦ Deployment (Vercel)
Vercel is the recommended host — the project is pre-configured for zero-config deployment.
**Step 1 — Connect your repo** **Step 1 — Connect your repo**
Go to [vercel.com](https://vercel.com) → **Add New Project** → connect your GitHub repo → set root directory to `dashboard/` Go to [vercel.com](https://vercel.com) → **Add New Project** → connect your GitHub repo → set root directory to `dashboard/`
@@ -155,12 +155,12 @@ In **Settings → Environment Variables**, add all keys from the table above.
| Variable | Production Value | | Variable | Production Value |
|---|---| |---|---|
| `NEXT_PUBLIC_API_URL` | `https://xxxx.ngrok-free.app/api/v1` | | `NEXT_PUBLIC_API_URL` | `https://api.yourdomain.com/api/v1` |
| `NEXTAUTH_URL` | `https://your-app.vercel.app` | | `NEXTAUTH_URL` | `https://your-app.vercel.app` |
| `NEXTAUTH_SECRET` | [generate one](https://generate-secret.vercel.app/32) | | `NEXTAUTH_SECRET` | [generate one](https://generate-secret.vercel.app/32) |
| `DISCORD_CLIENT_ID` | from [Discord Developer Portal](https://discord.com/developers/applications) | | `DISCORD_CLIENT_ID` | from [Discord Developer Portal](https://discord.com/developers/applications) |
**Step 3 — Add the redirect URI in Discord** **Step 3 — Add redirect URI in Discord**
In your Discord app → **OAuth2 → Redirects** → add: In your Discord app → **OAuth2 → Redirects** → add:
@@ -176,18 +176,20 @@ Hit **Deploy**. Vercel builds and publishes automatically. ✓
## ✦ Connecting to the Bot API ## ✦ Connecting to the Bot API
The dashboard talks to the bot's FastAPI backend. The URL comes from `NEXT_PUBLIC_API_URL`. The dashboard reads the API URL from `NEXT_PUBLIC_API_URL`.
- **Local dev** — set to `http://localhost:8000/api/v1` (bot running locally) | Environment | Value |
- **Production** — set to the bot's ngrok static domain: `https://xxxx.ngrok-free.app/api/v1` |---|---|
| Local dev | `http://localhost:8000/api/v1` |
| Production | `https://api.yourdomain.com/api/v1` (Cloudflare Tunnel URL) |
The bot prints the current tunnel URL every time it starts: The bot prints the confirmed URL on every startup:
``` ```
◈ Tunnel: API is live at https://xxxx.ngrok-free.app ◈ Tunnel: API is live at https://api.yourdomain.com
↳ set NEXT_PUBLIC_API_URL=https://xxxx.ngrok-free.app/api/v1 ↳ NEXT_PUBLIC_API_URL = https://api.yourdomain.com/api/v1
``` ```
If you set `NGROK_DOMAIN` in the bot's `.env`, this URL will never change between restarts. This URL is permanent — it never changes between restarts as long as the Cloudflare Tunnel token stays the same.
--- ---
@@ -197,10 +199,10 @@ If you set `NGROK_DOMAIN` in the bot's `.env`, this URL will never change betwee
|---|---| |---|---|
| Auth error on login | Check Discord OAuth client ID/secret and redirect URI in Developer Portal | | Auth error on login | Check Discord OAuth client ID/secret and redirect URI in Developer Portal |
| Dashboard can't load data | Confirm bot is running with `API_ENABLED=true` and `NEXT_PUBLIC_API_URL` is correct | | Dashboard can't load data | Confirm bot is running with `API_ENABLED=true` and `NEXT_PUBLIC_API_URL` is correct |
| CORS error in browser | Make sure your Vercel URL is allowed — add it to `CORS_ORIGINS` in the bot's `.env` | | CORS error in browser | Add your Vercel URL to `CORS_ORIGINS` in the bot's `.env` |
| `NEXTAUTH_SECRET` error | Make sure `NEXTAUTH_SECRET` is set and non-empty | | `NEXTAUTH_SECRET` error | Make sure `NEXTAUTH_SECRET` is set and non-empty |
| API key rejected (401) | `NEXT_PUBLIC_DASHBOARD_API_KEY` must exactly match `DASHBOARD_API_KEY` in the bot | | API key rejected (401) | `NEXT_PUBLIC_DASHBOARD_API_KEY` must exactly match `DASHBOARD_API_KEY` in the bot |
| ngrok warning page appears | The bot's FastAPI middleware already injects the skip-warning header automatically | | Tunnel URL changed | Cloudflare named tunnels always produce the same URL — check `CF_TUNNEL_TOKEN` is valid |
--- ---
@@ -210,6 +212,8 @@ If you set `NGROK_DOMAIN` in the bot's `.env`, this URL will never change betwee
*Built for protection. Designed for style.* *Built for protection. Designed for style.*
<a href="https://discord.gg/codexdev"><img src="https://discord.com/api/guilds/1301573144817045524/widget.png?style=banner2" alt="CodeX Development Discord Server" width="480"/></a>
<p> <p>
<a href="https://discord.gg/codexdev"><img src="https://img.shields.io/badge/Discord-Join_Server-5865F2?style=for-the-badge&logo=discord&logoColor=white"/></a> <a href="https://discord.gg/codexdev"><img src="https://img.shields.io/badge/Discord-Join_Server-5865F2?style=for-the-badge&logo=discord&logoColor=white"/></a>
<a href="https://youtube.com/@CodeXDevs"><img src="https://img.shields.io/badge/YouTube-CodeXDevs-FF0000?style=for-the-badge&logo=youtube&logoColor=white"/></a> <a href="https://youtube.com/@CodeXDevs"><img src="https://img.shields.io/badge/YouTube-CodeXDevs-FF0000?style=for-the-badge&logo=youtube&logoColor=white"/></a>