134 lines
4.3 KiB
Markdown
134 lines
4.3 KiB
Markdown
<div align="center">
|
|
|
|
# ZyroX Dashboard
|
|
|
|
Next.js web dashboard for configuring the ZyroX Discord bot.
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
- **Discord OAuth login** — users only see servers they can manage
|
|
- **Server-side API proxy** — `DASHBOARD_API_KEY` never exposed to the browser
|
|
- **Guild permission checks** — bot API verifies Discord Manage Server / Admin rights
|
|
- **Fully branded** — name and colours via environment variables
|
|
- **Vercel-ready**
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
| Requirement | Notes |
|
|
|---|---|
|
|
| Node.js 18+ | — |
|
|
| ZyroX bot running | with `API_ENABLED=true` on `127.0.0.1` (or via Cloudflare Tunnel) |
|
|
| Discord OAuth app | from [Discord Developer Portal](https://discord.com/developers/applications) |
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
### 1 — Install dependencies
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### 2 — Configure environment
|
|
|
|
Create `.env.local` in this folder (see `.env.example`):
|
|
|
|
```env
|
|
# ── Bot API (server-side only — never use NEXT_PUBLIC_ for the key) ──
|
|
DASHBOARD_API_URL = http://127.0.0.1:8000/api/v1
|
|
DASHBOARD_API_KEY = same_secret_as_bot_DASHBOARD_API_KEY
|
|
|
|
# ── NextAuth ──────────────────────────────────────────────────────
|
|
NEXTAUTH_URL = http://localhost:3000
|
|
NEXTAUTH_SECRET = a_long_random_string
|
|
|
|
# ── Discord OAuth ─────────────────────────────────────────────────
|
|
DISCORD_CLIENT_ID = your_discord_oauth_client_id
|
|
DISCORD_CLIENT_SECRET = your_discord_oauth_client_secret
|
|
|
|
# ── Admin & Branding ──────────────────────────────────────────────
|
|
ADMIN_IDS = your_discord_user_id
|
|
NEXT_PUBLIC_ADMIN_IDS = your_discord_user_id
|
|
NEXT_PUBLIC_BRAND_NAME = "ZyroX"
|
|
NEXT_PUBLIC_BRAND_NAME_WORD = "ZX"
|
|
```
|
|
|
|
### 3 — Run locally
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Open [http://localhost:3000](http://localhost:3000)
|
|
|
|
---
|
|
|
|
## Environment Reference
|
|
|
|
| Variable | Description |
|
|
|---|---|
|
|
| `DASHBOARD_API_URL` | Bot API URL (server-side). Local: `http://127.0.0.1:8000/api/v1` |
|
|
| `DASHBOARD_API_KEY` | Must match bot `DASHBOARD_API_KEY` — **server-side only** |
|
|
| `NEXTAUTH_URL` | Dashboard public URL |
|
|
| `NEXTAUTH_SECRET` | Random secret for NextAuth session signing |
|
|
| `DISCORD_CLIENT_ID` | Discord OAuth2 client ID |
|
|
| `DISCORD_CLIENT_SECRET` | Discord OAuth2 client secret |
|
|
| `ADMIN_IDS` | Server-side admin user IDs (for admin API routes) |
|
|
| `NEXT_PUBLIC_ADMIN_IDS` | Same IDs for admin panel UI visibility |
|
|
| `NEXT_PUBLIC_BRAND_NAME` | Bot name in the dashboard UI |
|
|
| `NEXT_PUBLIC_BRAND_NAME_WORD` | Short abbreviation (e.g. `ZX`) |
|
|
|
|
> Do **not** set `NEXT_PUBLIC_DASHBOARD_API_KEY`. The browser uses `/api/proxy`, which adds the secret server-side.
|
|
|
|
---
|
|
|
|
## How API auth works
|
|
|
|
```
|
|
Browser → /api/proxy/guilds/... → Next.js (session check)
|
|
→ Bot API with:
|
|
Authorization: Bearer DASHBOARD_API_KEY
|
|
X-Discord-Access-Token: <oauth token>
|
|
X-Discord-User-Id: <user id>
|
|
→ Bot verifies Discord Manage Server permission per guild
|
|
```
|
|
|
|
SSR (server components) call the bot API directly with the same headers from the active session.
|
|
|
|
---
|
|
|
|
## Deployment (Vercel)
|
|
|
|
1. Connect repo → set root directory to `dashboard/`
|
|
2. Add all environment variables from the table above
|
|
3. Set `NEXTAUTH_URL` to your Vercel domain
|
|
4. Add OAuth redirect: `https://your-app.vercel.app/api/auth/callback/discord`
|
|
5. Deploy
|
|
|
|
For production with Cloudflare Tunnel, set:
|
|
|
|
```env
|
|
DASHBOARD_API_URL=https://api.yourdomain.com/api/v1
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Problem | Fix |
|
|
|---|---|
|
|
| Dashboard can't load data | Bot running with `API_ENABLED=true`, `DASHBOARD_API_URL` correct |
|
|
| 401 from bot API | `DASHBOARD_API_KEY` must match bot `.env` exactly |
|
|
| 403 on guild routes | User must have Manage Server or Admin on that Discord server |
|
|
| Admin panel 403 | Add your Discord ID to `ADMIN_IDS` and bot `DASHBOARD_ADMIN_IDS` |
|
|
| Auth error on login | Check Discord OAuth client ID/secret and redirect URI |
|
|
|
|
See also `SECURITY_FIXES.md` in the project root.
|