diff --git a/README.md b/README.md index 3a76599..e60cd06 100644 --- a/README.md +++ b/README.md @@ -1,173 +1,395 @@ -# ZyroX With Dashboard +
-A Discord bot project with a Next.js dashboard for managing bot features and server settings. +``` +███████╗██╗ ██╗██████╗ ██████╗ ██╗ ██╗ +╚══███╔╝╚██╗ ██╔╝██╔══██╗██╔═══██╗╚██╗██╔╝ + ███╔╝ ╚████╔╝ ██████╔╝██║ ██║ ╚███╔╝ + ███╔╝ ╚██╔╝ ██╔══██╗██║ ██║ ██╔██╗ +███████╗ ██║ ██║ ██║╚██████╔╝██╔╝ ██╗ +╚══════╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ +``` -## Project Structure +**A feature-rich Discord bot paired with a sleek Next.js dashboard** -- bot/ - Python Discord bot -- dashboard/ - Next.js frontend dashboard -- bot/api/ - FastAPI backend endpoints used by the dashboard +[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org) +[![Next.js](https://img.shields.io/badge/Next.js-14+-000000?style=for-the-badge&logo=nextdotjs&logoColor=white)](https://nextjs.org) +[![FastAPI](https://img.shields.io/badge/FastAPI-Backend-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com) +[![Discord](https://img.shields.io/badge/Discord.py-v2-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discordpy.readthedocs.io) +[![License](https://img.shields.io/badge/License-MIT-red?style=for-the-badge)](LICENSE) +[![Support](https://img.shields.io/badge/Support-discord.gg/codexdev-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/codexdev) -## 1) Bot Setup +
-### Requirements +--- -- Python 3.10+ -- pip -- A Discord bot token from the Discord Developer Portal +## ✦ Overview -### Install dependencies +ZyroX is a fully-featured Discord bot with a modern web dashboard for managing everything from antinuke to music. Built on `discord.py v2`, `FastAPI`, and `Next.js 14` with Tailwind CSS. + +``` +ZyroX-CV2-With-Dashboard/ +├── 🤖 bot/ Python Discord bot + FastAPI backend +│ ├── api/ Dashboard REST API (FastAPI) +│ ├── cogs/ All bot features (commands, events, antinuke, automod…) +│ ├── utils/ Shared utilities (emoji, tools, sync…) +│ ├── assets/ Fonts, backgrounds, GIFs +│ └── CodeX.py Entry point +│ +└── 🌐 dashboard/ Next.js frontend + ├── app/ App Router pages + ├── components/ Reusable UI components + ├── hooks/ Custom React hooks + └── lib/ API helpers & utilities +``` + +--- + +## ✦ Features + + + + + + + + + + + + + + +
+ +**🛡️ Security** +- Antinuke (ban, kick, channel/role flood, webhook abuse…) +- Automod (spam, caps, links, invites, mass mentions, emoji spam) +- Anti-member update protection +- Whitelist / unwhitelist system +- Emergency mode + + + +**🎵 Music** +- Lavalink v4 powered playback +- YouTube, SoundCloud, JioSaavn search +- Queue, loop, autoplay, shuffle +- Seek, rewind, forward controls +- Fully configurable via `.env` + +
+ +**⚙️ Management** +- Moderation (ban, kick, mute, warn, lock…) +- Logging system +- Reaction roles, vanity roles +- Tickets, giveaways, verification +- Join-to-create voice channels + + + +**🌐 Dashboard** +- Discord OAuth2 login +- Per-server settings management +- Bot stats & live data +- Fully branded & customisable +- Deployed to Vercel in minutes + +
+ +**🎉 Engagement** +- Leveling system with XP +- Birthday tracker +- Counting games, blackjack, slots +- AFK system, autorole, autoresponder +- Sticky messages, booster perks + + + +**🔧 Developer** +- Application emoji auto-sync +- Jishaku eval support +- Slash + prefix commands +- FastAPI backend with API key auth +- Hot-patchable emoji.py on startup + +
+ +--- + +## ✦ Quick Start + +### Prerequisites + +| Requirement | Version | +|---|---| +| Python | 3.10 or higher | +| Node.js | 18 or higher | +| A Lavalink node | v4 | +| Discord bot token | — | +| Discord OAuth app | (for dashboard) | + +--- + +## ✦ Bot Setup + +**1 — Clone and enter the bot folder** + +```bash +git clone https://github.com/your-org/ZyroX-CV2-With-Dashboard +cd ZyroX-CV2-With-Dashboard/bot +``` + +**2 — Create a virtual environment and install dependencies** ```bash -cd bot python -m venv .venv -.venv\Scripts\activate # Windows + +# Windows +.venv\Scripts\activate + +# Linux / macOS +source .venv/bin/activate + pip install -r requirements.txt ``` -### Configure environment - -Create a `.env` file inside the `bot/` folder with at least: - -```env -TOKEN=your_discord_bot_token -``` - -You may also need to update values in: - -- `bot/config.yml` -- `bot/api` configuration if you are using the API backend - -### Run the bot +**3 — Configure the environment** + +```bash +cp .env.example .env +``` + +Then edit `.env`: + +```env +# ── Core ────────────────────────────────────── +TOKEN = your_discord_bot_token +brand_name = 'ZyroX' + +# ── Lavalink ────────────────────────────────── +LAVALINK_HOST = "lava-v4.ajieblogs.eu.org" +LAVALINK_PASSWORD = "your_password" +LAVALINK_SECURE = "true" # true = https (no port needed) +LAVALINK_PORT = "" # only needed when LAVALINK_SECURE=false + +# ── Emoji Sync ──────────────────────────────── +EMOJI_SYNC = "true" # auto-uploads & patches emoji.py on startup + # restarts the bot automatically after patching + +# ── API / Dashboard Backend ─────────────────── +API_ENABLED = "true" # false = skip starting the FastAPI server +API_PORT = "8000" +DASHBOARD_API_KEY = "change_this_to_a_strong_secret" + +# ── Webhooks ────────────────────────────────── +WEBHOOK_URL = "https://discord.com/api/webhooks/..." +``` + +**4 — Run the bot** ```bash -cd bot python CodeX.py ``` -If you want to run the API backend separately, use: +--- -```bash -cd bot/api -uvicorn server:app --host 0.0.0.0 --port 8000 -``` +## ✦ Dashboard Setup -> The dashboard expects a reachable API base URL, so the bot API should be hosted somewhere public if you plan to use it outside localhost. - -## 2) Dashboard Setup - -### Requirements - -- Node.js 18+ -- npm - -### Install dependencies +**1 — Install dependencies** ```bash cd dashboard npm install +``` + +**2 — Configure the environment** + +```bash cp .env.example .env.local ``` -### Configure environment - -Edit `dashboard/.env.local` and update the values: +Edit `dashboard/.env.local`: ```env -NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1 -NEXTAUTH_URL=http://localhost:3000 -NEXTAUTH_SECRET=change_this_to_a_long_random_string -DISCORD_CLIENT_ID=your_discord_oauth_client_id -DISCORD_CLIENT_SECRET=your_discord_oauth_client_secret -NEXT_PUBLIC_DASHBOARD_API_KEY=ZYROX_SECURE_API_KEY_12345 -NEXT_PUBLIC_BRAND_NAME="Zyrox X" -NEXT_PUBLIC_BRAND_NAME_WORD="ZX" +NEXT_PUBLIC_API_URL = http://localhost:8000/api/v1 +NEXT_PUBLIC_DASHBOARD_API_KEY = your_shared_api_key # must match bot's DASHBOARD_API_KEY + +NEXTAUTH_URL = http://localhost:3000 +NEXTAUTH_SECRET = a_long_random_string + +DISCORD_CLIENT_ID = your_discord_oauth_client_id +DISCORD_CLIENT_SECRET = your_discord_oauth_client_secret + +NEXT_PUBLIC_ADMIN_IDS = your_discord_user_id +NEXT_PUBLIC_BRAND_NAME = "ZyroX" +NEXT_PUBLIC_BRAND_NAME_WORD = "ZX" ``` -### Run locally +**3 — Run locally** ```bash -cd dashboard npm run dev ``` -Open http://localhost:3000 +Open [http://localhost:3000](http://localhost:3000) -## 3) Deploy the Bot and Dashboard +--- -The first step is to upload the full bot folder to your hosting provider, and then upload the dashboard folder directly to Vercel. +## ✦ Environment Reference -### Bot hosting +### Bot — `bot/.env` -1. Upload the entire `bot/` folder and all of its files to your Python hosting provider. -2. Make sure the app starts with the bot entry file, such as `bot/CodeX.py`. -3. Set the required environment variables on your host. -4. Keep the bot API reachable at a public URL if the dashboard needs to call it. -5. You can also use https://nexiohost.in for bot hosting; it offers free and paid plans. +| Variable | Default | Description | +|---|---|---| +| `TOKEN` | — | Discord bot token | +| `LAVALINK_HOST` | — | Lavalink server hostname (no protocol) | +| `LAVALINK_PASSWORD` | — | Lavalink password | +| `LAVALINK_SECURE` | `true` | `true` = HTTPS, `false` = HTTP | +| `LAVALINK_PORT` | _(empty)_ | Port — only needed when `LAVALINK_SECURE=false` | +| `EMOJI_SYNC` | `true` | Run application emoji sync on startup | +| `API_ENABLED` | `true` | Start the FastAPI dashboard backend | +| `API_PORT` | `8000` | Port the backend listens on | +| `DASHBOARD_API_KEY` | — | Shared secret between bot API and dashboard | +| `WEBHOOK_URL` | — | Discord webhook for command logs | -### Dashboard deployment to Vercel +### Dashboard — `dashboard/.env.local` -1. Push the dashboard folder to GitHub as its own project, or import it directly in Vercel. -2. Open Vercel and click New Project. -3. Import the dashboard repository or folder. -4. Set the project root to the `dashboard/` folder. -5. Use these build settings: - - Framework Preset: Next.js - - Build Command: `npm run build` - - Output Directory: `.next` -6. Add the required environment variables in Vercel: - - `NEXT_PUBLIC_API_URL` - - `NEXTAUTH_URL` (set to `https://your-app.vercel.app`) - - `NEXTAUTH_SECRET` - - `DISCORD_CLIENT_ID` - - `DISCORD_CLIENT_SECRET` - - `NEXT_PUBLIC_DASHBOARD_API_KEY` - - `NEXT_PUBLIC_BRAND_NAME` - - `NEXT_PUBLIC_BRAND_NAME_WORD` -7. Deploy the project. +| Variable | Description | +|---|---| +| `NEXT_PUBLIC_API_URL` | Full URL to the bot's FastAPI backend | +| `NEXT_PUBLIC_DASHBOARD_API_KEY` | Must match `DASHBOARD_API_KEY` in the bot | +| `NEXTAUTH_URL` | Your dashboard's public URL | +| `NEXTAUTH_SECRET` | Random secret for NextAuth session signing | +| `DISCORD_CLIENT_ID` | Discord OAuth2 client ID | +| `DISCORD_CLIENT_SECRET` | Discord OAuth2 client secret | +| `NEXT_PUBLIC_ADMIN_IDS` | Comma-separated Discord user IDs with admin access | +| `NEXT_PUBLIC_BRAND_NAME` | Bot name shown in the dashboard UI | +| `NEXT_PUBLIC_BRAND_NAME_WORD` | Short abbreviation shown in the dashboard | -### Important Notes +--- -- `NEXTAUTH_URL` must point to your Vercel domain. -- Discord OAuth redirect URIs must include your Vercel URL, for example: - - `https://your-app.vercel.app/api/auth/callback/discord` -- If the dashboard uses the bot API, that API must be publicly reachable from Vercel. +## ✦ Deployment -## 4) Recommended Hosting for the Bot API +### 🤖 Bot — any Python host -If you want the dashboard to talk to the bot API in production, host the API on a service such as: +1. Upload the entire `bot/` folder to your host (Render, Railway, Fly.io, VPS…) +2. Set the start command to `python CodeX.py` +3. Add all environment variables from `.env.example` +4. Make sure port `API_PORT` (`8000` by default) is publicly reachable if you're using the dashboard -- Render -- Railway -- Fly.io -- VPS / Ubuntu server +> Recommended free/cheap hosts: [NexioHost](https://nexiohost.in) · Render · Railway -Then set `NEXT_PUBLIC_API_URL` to that public API URL. +### 🌐 Dashboard — Vercel (recommended) -## 5) Key Rules and Important Points +> **That's literally it — upload the folder, add the variables, done.** -- Keep your bot token private and never share it publicly. -- Use a strong `NEXTAUTH_SECRET` and rotate it if it is exposed. -- Only use Discord OAuth credentials from a trusted app you control. -- Make sure your bot has the required permissions before inviting it to servers. -- The dashboard should only be exposed through a trusted domain and HTTPS. -- If the bot API is public, protect it with authentication or a secure secret key. -- Never upload real tokens, secrets, or private keys to GitHub or public forums. -- Always test the bot and dashboard in a staging environment before using them in production. -- Respect Discord ToS and platform rules when running moderation or automation features. -- If you use third-party hosting, verify that the provider allows bot processes and long-running services. +**Step 1 — Upload to Vercel** -## 6) Credits +Go to [vercel.com](https://vercel.com) → **Add New Project** → drag and drop the `dashboard/` folder +*(or connect your GitHub repo and set the root directory to `dashboard/`)* -- Developed by CodeX Devs -- Community: https://discord.gg/codexdev -- Hosting partner: https://nexiohost.in +Vercel auto-detects Next.js — no build settings to touch. -## 7) License +--- -This project is licensed under the MIT License. +**Step 2 — Add environment variables** -Copyright (c) 2026 CodeX Devs +In your Vercel project → **Settings → Environment Variables**, add these: + +| Variable | Value | +|---|---| +| `NEXT_PUBLIC_API_URL` | Your bot API URL, e.g. `https://your-bot.render.com/api/v1` | +| `NEXT_PUBLIC_DASHBOARD_API_KEY` | Same value as `DASHBOARD_API_KEY` in the bot `.env` | +| `NEXTAUTH_URL` | Your Vercel domain, e.g. `https://your-app.vercel.app` | +| `NEXTAUTH_SECRET` | Any long random string — [generate one here](https://generate-secret.vercel.app/32) | +| `DISCORD_CLIENT_ID` | From [Discord Developer Portal](https://discord.com/developers/applications) | +| `DISCORD_CLIENT_SECRET` | From Discord Developer Portal | +| `NEXT_PUBLIC_ADMIN_IDS` | Your Discord user ID | +| `NEXT_PUBLIC_BRAND_NAME` | `ZyroX` *(or your custom name)* | +| `NEXT_PUBLIC_BRAND_NAME_WORD` | `ZX` *(short version)* | + +--- + +**Step 3 — Add the redirect URI in Discord** + +Go to your app in the [Discord Developer Portal](https://discord.com/developers/applications) +→ **OAuth2 → Redirects** → add: + +``` +https://your-app.vercel.app/api/auth/callback/discord +``` + +--- + +**Step 4 — Deploy** + +Hit **Deploy**. Vercel builds and publishes automatically. Your dashboard is live. ✓ + +--- + +## ✦ Emoji Sync + +ZyroX includes an automatic emoji sync system that runs on every startup (when `EMOJI_SYNC=true`): + +``` +★ Starting Application Emoji Sync — 140 unique emojis found in emoji.py +◈ Found 140 templates | Application hosts 98 emojis +↑ Uploading: ztick (not in application emojis) +✔ Uploaded: ztick [saved as ID: 1234567890] +✔ emoji.py patched in-place to reflect current API state. +★ Restarting bot to load updated emoji IDs... +``` + +- **New emoji** → downloaded from CDN, uploaded to your application, ID written to `emoji.py` +- **Stale ID** → `emoji.py` is patched automatically +- **No changes** → sync completes instantly, no restart +- **After any patch** → bot restarts itself so the fresh IDs are live immediately + +Set `EMOJI_SYNC=false` to disable entirely. + +--- + +## ✦ Security Notes + +- Never commit `.env` files or real tokens to a public repo — `.gitignore` already covers them +- Use a strong, unique `NEXTAUTH_SECRET` and `DASHBOARD_API_KEY` +- Rotate any secret that gets accidentally exposed +- Keep Discord OAuth credentials in environment variables only +- The bot API should always be behind an API key when publicly hosted + +--- + +## ✦ Troubleshooting + +| Problem | Fix | +|---|---| +| Bot fails to start | Check `TOKEN` is set correctly and the bot has the right gateway intents | +| Music not working | Verify `LAVALINK_HOST`, `LAVALINK_SECURE`, and `LAVALINK_PORT` are correct | +| Dashboard shows auth error | Check Discord OAuth client ID/secret and redirect URI in Developer Portal | +| Dashboard can't load data | Confirm `API_ENABLED=true`, the bot is running, and `NEXT_PUBLIC_API_URL` is correct | +| Emojis showing as plain text | Run with `EMOJI_SYNC=true` once to upload and patch IDs | +| Port conflict on API | Change `API_PORT` in `.env` and update `NEXT_PUBLIC_API_URL` in the dashboard | + +--- + +## ✦ Credits & Links + +
+ +Developed with ❤️ by **CodeX Devs** + +[![Discord](https://img.shields.io/badge/Join_Support_Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/codexdev) +[![Hosting](https://img.shields.io/badge/Bot_Hosting-NexioHost-FF6B6B?style=for-the-badge)](https://nexiohost.in) + +
+ +--- + +## ✦ License + +``` +MIT License — Copyright (c) 2026 CodeX Devs Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -176,19 +398,18 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +``` -## 8) Troubleshooting +
-- If the dashboard shows authentication issues, verify your Discord OAuth credentials and redirect URIs. -- If the dashboard cannot load data, confirm that the API backend is running and reachable. -- If the bot fails to start, confirm the bot token and required Python packages are installed. +--- + +*ZyroX — Built for protection. Designed for style.* + +