Installation Guide¶

This guide explains how to install and set up Quizzical Beats in various environments.

System Requirements¶

Before installation, ensure your system meets these requirements:

Operating System: Linux (recommended), macOS, or Windows
Python: Version 3.8 or higher
Database: SQLite (included), PostgreSQL, or MySQL
Storage: Minimum 2GB free space for application and database
Memory: 2GB RAM minimum, 4GB recommended
Optional: Docker and Docker Compose for containerized deployment

Docker Installation (Recommended)¶

The easiest way to deploy Quizzical Beats is using Docker:

Prerequisites¶

Install Docker
Install Docker Compose

Deployment Steps¶

Clone the repository:

git clone https://github.com/christianlouis/musicround.git
cd musicround

Configure environment variables:
```
cp .env.demo .env
```
Edit the .env file to set your configuration options, including API keys and database settings.
Start the application:
```
docker-compose up -d
```
Access the application at http://localhost:5000

Docker Volume Configuration¶

The Docker setup creates several persistent volumes:

data: Contains the SQLite database and uploaded files
mp3: Stores all generated and uploaded MP3 files
backups: Location for automated backups

You can configure these volumes in the docker-compose.yml file:

volumes:
  - ./data:/app/data
  - ./mp3:/app/mp3
  - ./backups:/app/backups

Manual Installation¶

For non-Docker environments:

Prerequisites¶

Install Python 3.8+ and pip

Set up a virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Installation Steps¶

Clone the repository:

git clone https://github.com/christianlouis/musicround.git
cd musicround

Install dependencies:
```
pip install -r requirements.txt
```
Configure environment variables:
```
cp .env.demo .env
```
Edit the .env file with your configuration settings.
Create necessary directories:
```
mkdir -p data/backups mp3
```
Initialize the database:
```
python run_migration.py
```
Start the application:
```
python run.py
```
Access the application at http://localhost:5000

Production Deployment¶

For production environments, consider the following:

Web Server Configuration¶

Use a production-ready web server:

Install Gunicorn:
```
pip install gunicorn
```

Configure Gunicorn:

gunicorn -w 4 -b 127.0.0.1:8000 "musicround:create_app()"

Set up Nginx as a reverse proxy:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /static {
        alias /path/to/musicround/static;
        expires 30d;
    }
}

Set up HTTPS using Certbot (Let's Encrypt):

sudo certbot --nginx -d your-domain.com

Database Configuration¶

For larger deployments, use PostgreSQL:

Install PostgreSQL and create a database:

sudo apt install postgresql
sudo -u postgres createuser -P quizzicalbeats
sudo -u postgres createdb -O quizzicalbeats musicround

Update the database URI in your .env file:

SQLALCHEMY_DATABASE_URI=postgresql://quizzicalbeats:password@localhost/musicround

Security Configuration¶

Generate a strong secret key:

python -c "import secrets; print('SECRET_KEY=' + secrets.token_hex(32))"

Add this to your .env file.

Set debug mode to False in production:
```
DEBUG=False
```

Configure proper file permissions:

sudo chown -R www-data:www-data data mp3 backups
sudo chmod -R 750 data mp3 backups

Setting Up Third-Party Services¶

Spotify Integration¶

Go to the Spotify Developer Dashboard
Create a new application
Add http://your-domain.com/auth/spotify/callback to the Redirect URIs

Copy your Client ID and Client Secret to your .env file:

SPOTIFY_CLIENT_ID=your-client-id
SPOTIFY_CLIENT_SECRET=your-client-secret
SPOTIFY_REDIRECT_URI=http://your-domain.com/auth/spotify/callback

Dropbox Integration¶

Go to the Dropbox App Console
Create a new app with the following settings:
API: Dropbox API
Access type: Full Dropbox
Name: Quizzical Beats (or your preferred name)
Add http://your-domain.com/users/dropbox/callback to the OAuth 2 Redirect URIs

Copy your App Key and App Secret to your .env file:

DROPBOX_APP_KEY=your-app-key
DROPBOX_APP_SECRET=your-app-secret
DROPBOX_REDIRECT_URI=http://your-domain.com/users/dropbox/callback

Under Permissions, select:
files.content.read
files.content.write
sharing.write

OpenAI Integration (for AI-powered features)¶

Go to OpenAI API Keys
Create a new secret key
Add your API key to your .env file:
```
OPENAI_API_KEY=your-api-key
```

Email Configuration¶

Configure your SMTP settings in the .env file:

MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USE_TLS=True
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_SENDER=quizzical-beats@example.com
MAIL_RECIPIENT=admin@example.com

Troubleshooting Installation Issues¶

Database Migration Errors¶

If you encounter errors during database migration:

Check for database connection issues:

python -c "from musicround import db; db.create_all()"

Reset the migration if needed:

rm -f data/song_data.db
python run_migration.py

File Permission Issues¶

If you encounter file permission errors:

Check ownership of data directories:
```
ls -la data mp3 backups
```

Update permissions if needed:

sudo chown -R $(whoami) data mp3 backups

OAuth Configuration Errors¶

If OAuth authentication fails:

Verify that your callback URLs exactly match what's configured in the provider's developer console
Check for typos in your client IDs and secrets
Ensure the application is in "production" status for Dropbox
Verify that all required scopes/permissions are enabled

Server Not Starting¶

If the server fails to start:

Check the logs for errors:
```
tail -f logs/quizzical-beats.log
```
Verify that all required dependencies are installed:
```
pip install -r requirements.txt
```
Check if another process is using port 5000:
```
sudo lsof -i :5000
```