gh-christianlouis-quizzicalbeats/docs/admin-guide/installation.md

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

1. Install Docker
2. Install Docker Compose

Deployment Steps

1. Clone the repository:

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

2. Configure environment variables:

   cp .env.demo .env
   

   Edit the .env file to set your configuration options, including API keys and database settings.

3. Start the application:

   docker-compose up -d
   

4. 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

1. Install Python 3.8+ and pip
2. Set up a virtual environment (recommended):

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

Installation Steps

1. Clone the repository:

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

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment variables:

   cp .env.demo .env
   

   Edit the .env file with your configuration settings.

4. Create necessary directories:

   mkdir -p data/backups mp3
   

5. Initialize the database:

   python run_migration.py
   

6. Start the application:

   python run.py
   

7. Access the application at http://localhost:5000

Production Deployment

For production environments, consider the following:

Web Server Configuration

Use a production-ready web server:

1. Install Gunicorn:

   pip install gunicorn
   

2. Configure Gunicorn:

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

3. 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;
       }
   }
   

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

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

Database Configuration

For larger deployments, use PostgreSQL:

1. Install PostgreSQL and create a database:

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

2. Update the database URI in your .env file:

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

Security Configuration

1. Generate a strong secret key:

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

   Add this to your .env file.

2. Set debug mode to False in production:

   DEBUG=False
   

3. 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

1. Go to the Spotify Developer Dashboard
2. Create a new application
3. Add http://your-domain.com/auth/spotify/callback to the Redirect URIs
4. 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

1. Go to the Dropbox App Console
2. Create a new app with the following settings:
   • API: Dropbox API
   • Access type: Full Dropbox
   • Name: Quizzical Beats (or your preferred name)
3. Add http://your-domain.com/users/dropbox/callback to the OAuth 2 Redirect URIs
4. 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
   

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

OpenAI Integration (for AI-powered features)

1. Go to OpenAI API Keys
2. Create a new secret key
3. Add your API key to your .env file:

   OPENAI_API_KEY=your-api-key
   

Email Configuration

1. 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:

1. Check for database connection issues:

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

2. Reset the migration if needed:

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

File Permission Issues

If you encounter file permission errors:

1. Check ownership of data directories:

   ls -la data mp3 backups
   

2. Update permissions if needed:

   sudo chown -R $(whoami) data mp3 backups
   

OAuth Configuration Errors

If OAuth authentication fails:

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

Server Not Starting

If the server fails to start:

1. Check the logs for errors:

   tail -f logs/quizzical-beats.log
   

2. Verify that all required dependencies are installed:

   pip install -r requirements.txt
   

3. Check if another process is using port 5000:

   sudo lsof -i :5000