groovy-zilean/SETUP.md

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)
• Spotify API Credentials (Spotify Developer Dashboard)

---

1. Clone & Setup Environment

# 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

# 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:

# 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:

# 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

# 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

# Make sure .env has ENVIRONMENT=dev
source venv/bin/activate  # If not already activated
python main.py

Production Mode

# 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:

# 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'"

pip install python-dotenv

"FFmpeg not found"

# 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:

python --version

If too old, install newer Python and recreate venv:

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! 🎵⏱️