202 lines
3.8 KiB
Markdown
202 lines
3.8 KiB
Markdown
# Groovy-Zilean Setup Guide
|
|
|
|
Quick start guide for getting groovy-zilean running locally or in production.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- **Python 3.11+** (3.9 deprecated by yt-dlp)
|
|
- **FFmpeg** installed on your system
|
|
- Discord Bot Token ([Discord Developer Portal](https://discord.com/developers/applications))
|
|
- Spotify API Credentials ([Spotify Developer Dashboard](https://developer.spotify.com/dashboard))
|
|
|
|
---
|
|
|
|
## 1. Clone & Setup Environment
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <your-repo-url>
|
|
cd groovy-zilean
|
|
|
|
# Create virtual environment (keeps dependencies isolated)
|
|
python3.12 -m venv venv
|
|
|
|
# Activate virtual environment
|
|
source venv/bin/activate # Linux/Mac
|
|
# OR
|
|
venv\Scripts\activate # Windows
|
|
|
|
# Install dependencies
|
|
pip install --upgrade pip
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Configuration
|
|
|
|
### Create `.env` file
|
|
|
|
```bash
|
|
# Copy the example file
|
|
cp .env.example .env
|
|
|
|
# Edit with your favorite editor
|
|
nano .env
|
|
# OR
|
|
vim .env
|
|
# OR
|
|
code .env # VS Code
|
|
```
|
|
|
|
### Fill in Required Values
|
|
|
|
At minimum, you need:
|
|
|
|
```env
|
|
# Choose environment: "dev" or "live"
|
|
ENVIRONMENT=dev
|
|
|
|
# Discord bot tokens (get from Discord Developer Portal)
|
|
DISCORD_TOKEN_DEV=your_dev_bot_token_here
|
|
DISCORD_TOKEN_LIVE=your_live_bot_token_here
|
|
|
|
# Spotify credentials (get from Spotify Developer Dashboard)
|
|
SPOTIFY_CLIENT_ID=your_spotify_client_id
|
|
SPOTIFY_CLIENT_SECRET=your_spotify_secret
|
|
```
|
|
|
|
**Optional but recommended:**
|
|
```env
|
|
# Bot settings
|
|
DISCORD_PREFIX==
|
|
STATUS_TYPE=listening
|
|
STATUS_TEXT=Zilean's Theme
|
|
|
|
# Colors (hex format)
|
|
COLOR_PRIMARY=#7289DA
|
|
COLOR_SUCCESS=#43B581
|
|
COLOR_ERROR=#F04747
|
|
COLOR_WARNING=#FAA61A
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Create Data Directory
|
|
|
|
```bash
|
|
# Create directory for database
|
|
mkdir -p data
|
|
|
|
# The database file (music.db) will be created automatically on first run
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Run the Bot
|
|
|
|
### Development Mode
|
|
|
|
```bash
|
|
# Make sure .env has ENVIRONMENT=dev
|
|
source venv/bin/activate # If not already activated
|
|
python main.py
|
|
```
|
|
|
|
### Production Mode
|
|
|
|
```bash
|
|
# Change .env to ENVIRONMENT=live
|
|
source venv/bin/activate
|
|
python main.py
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Switching Between Dev and Live
|
|
|
|
**Super easy!** Just change one line in `.env`:
|
|
|
|
```bash
|
|
# For development bot
|
|
ENVIRONMENT=dev
|
|
|
|
# For production bot
|
|
ENVIRONMENT=live
|
|
```
|
|
|
|
The bot will automatically use the correct token!
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### "Configuration Error: DISCORD_TOKEN_DEV not found"
|
|
- Make sure you copied `.env.example` to `.env`
|
|
- Check that `.env` has the token values filled in
|
|
- Token should NOT have quotes around it
|
|
|
|
### "No module named 'dotenv'"
|
|
```bash
|
|
pip install python-dotenv
|
|
```
|
|
|
|
### "FFmpeg not found"
|
|
```bash
|
|
# Debian/Ubuntu
|
|
sudo apt install ffmpeg
|
|
|
|
# macOS
|
|
brew install ffmpeg
|
|
|
|
# Arch Linux
|
|
sudo pacman -S ffmpeg
|
|
```
|
|
|
|
### Python version issues
|
|
yt-dlp requires Python 3.10+. Check your version:
|
|
```bash
|
|
python --version
|
|
```
|
|
|
|
If too old, install newer Python and recreate venv:
|
|
```bash
|
|
python3.12 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
groovy-zilean/
|
|
├── main.py # Entry point (run this!)
|
|
├── bot.py # Bot class definition
|
|
├── config.py # Configuration management
|
|
├── .env # YOUR secrets (never commit!)
|
|
├── .env.example # Template (safe to commit)
|
|
├── requirements.txt # Python dependencies
|
|
├── cogs/
|
|
│ └── music/ # Music functionality
|
|
│ ├── main.py # Commands
|
|
│ ├── queue.py # Queue management
|
|
│ ├── util.py # Utilities
|
|
│ └── translate.py # URL/search handling
|
|
└── data/
|
|
└── music.db # SQLite database (auto-created)
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- Check out `PRODUCTION_ROADMAP.md` for the full development plan
|
|
- See `README.md` for feature list and usage
|
|
- Join your test server and try commands!
|
|
|
|
**Happy coding!** 🎵⏱️
|