gitea-admin/gh-christianlouis-quizzicalbeats
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive documentation for Quizzical Beats

Browse Source 
- Created a detailed database schema document outlining tables, relationships, and key fields.
- Added OAuth integration documentation covering Spotify and Dropbox authentication processes.
- Introduced a FAQ section addressing common user inquiries about the application.
- Developed a user-friendly index page for easy navigation of the documentation.
- Specified documentation dependencies in requirements.txt for building the documentation site.
- Expanded user guide with sections on account management, creating rounds, exporting rounds, getting started, importing songs, and user interface navigation.
- Updated mkdocs.yml for improved site structure and navigation.
This commit is contained in:
Christian Krakau-Louis
2025-05-13 11:25:20 +02:00
parent 4646c80a15
commit 204941a1dc
23 changed files with 3558 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin-guide/backup-restore.md
+132
View File
@@ -0,0 +1,132 @@
# Backup and Restore
This guide explains how to back up and restore Quizzical Beats data, ensuring your music quiz system remains protected against data loss.
## Understanding Backup Components
A complete Quizzical Beats backup includes:
- **Database**: Contains all rounds, songs, user accounts, and system settings
- **Media Files**: MP3 snippets, custom intro/outro sounds, and uploaded audio
- **Configuration**: Environment variables and application settings
- **Metadata**: Version information and backup manifest
## Manual Backup Process
Perform a manual backup through the admin interface:
1. Log in as an administrator
2. Navigate to Admin > System > Backup Manager
3. Click "Create New Backup" or use the "Quick Actions" button
4. Options you can configure:
- Custom backup name (optional)
- Include MP3 files (enabled by default)
- Include configuration files (enabled by default)
5. The backup will be stored in the `/data/backups` directory
6. Once completed, you can download the backup ZIP file
## Automated Backup Configuration
Set up scheduled automatic backups:
1. Go to Admin > System > Backup Manager
2. Click "Schedule Backups"
3. Configure:
- Frequency (hourly, daily, weekly)
- Time of execution (HH:MM format)
- Retention policy (days to keep backups)
4. Click "Save Schedule" to apply the settings
For Docker deployments, you can configure automated backups using the Docker labels or Ofelia scheduler:
1. Click "View Configuration Suggestion" in the scheduler form
2. Choose the appropriate configuration option:
- Docker Compose labels
- Ofelia.ini configuration
3. Apply the suggested configuration to your Docker setup
4. Restart your containers to activate the schedule
## Backup Retention Policies
Configure how long backups are kept:
1. Navigate to Admin > System > Backup Manager
2. Click "Configure Retention"
3. Set the number of days to keep backups:
- Enter a value between 1-365 days
- Enter 0 to keep all backups indefinitely
4. Options:
- Save Policy: Updates the retention settings
- Apply Now: Immediately deletes backups older than the specified period
## Backup Management
Manage your existing backups:
1. Go to Admin > System > Backup Manager > Existing Backups
2. For each backup, you can:
- Download: Save the backup file to your local system
- Verify: Check the backup integrity
- Restore: Revert your system to this backup state
- Delete: Remove the backup file
## Restoring from Backup
Restore your system when needed:
1. Go to Admin > System > Backup Manager > Existing Backups
2. You can either:
- Select an existing backup from the list
- Upload a backup file using the "Upload Backup" button
3. Click the "Restore" icon next to the backup you wish to restore
4. Confirm the restore operation
5. The system will:
- Create safety backups of your current state
- Restore the database, MP3 files, and configuration
- Preserve all file history
## Command-Line Backup
For scripting and automation, use the CLI commands:
```bash
# Create a backup
python run.py backup create --auto
# Apply retention policy
python run.py backup retention --days 30
```
## Backup Verification
Ensure your backups are valid:
1. Go to Admin > System > Backup Manager > Existing Backups
2. Click the "Verify" icon next to the backup
3. The system will check:
- File integrity (ZIP structure)
- Required files presence (database)
- Version metadata
4. A notification will appear with the verification results
## System Health
The Backup Manager also provides a system health overview:
1. Check the "System Health" section at the bottom of the page
2. It displays the status of critical components:
- Database connectivity
- File storage access
- Configuration status
## Troubleshooting Backup Issues
**Backup Failure**:
- Check storage permissions for the `/data/backups` directory
- Verify sufficient disk space
- Ensure the database is not locked by another process
**Restore Failure**:
- Ensure the backup format is compatible with your version
- Check system logs for detailed error messages
- Verify backup file integrity using the verification tool
docs/admin-guide/configuration.md
+255
View File
@@ -0,0 +1,255 @@
# Configuration Guide
This guide explains how to configure Quizzical Beats for different environments and use cases.
## Environment Variables
Quizzical Beats uses environment variables for configuration. These can be set in the `.env` file or directly in your environment.
### Core Configuration
```bash
# Debug settings
DEBUG=True
DEBUG2=False
SECRET_KEY=your-secret-key-here-make-it-long-and-random
```
### API Keys and Services
```bash
# OpenAI API settings
OPENAI_API_KEY=your-openai-api-key
OPENAI_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
OPENAI_SEARCH_MODEL=gpt-4o-mini-search-preview
# Translation and language services
DEEPL_API_KEY=your-deepl-api-key
MEANINGCLOUD_API_KEY=your-meaningcloud-api-key
# Audio services
ELEVENLABS_API_KEY=your-elevenlabs-api-key
ACRCLOUD_TOKEN=your-acrcloud-token
# Music APIs
LASTFM_API_KEY=your-lastfm-api-key
```
## Music Metadata APIs
Quizzical Beats uses multiple API services to gather comprehensive music metadata. Configuring these services enhances the quality and completeness of your music library.
### Last.fm
Last.fm provides genre information and tag data that's often missing from streaming services:
- **Configuration**: Set the `LASTFM_API_KEY` environment variable
- **Usage**: Automatically enriches tracks with genre metadata
- **Benefits**: Improves genre-based round generation
- **Obtain API Key**: [Last.fm API](https://www.last.fm/api/account/create)
### Spotify
Spotify provides comprehensive track metadata and audio features analysis:
- **Configuration**: Set `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`
- **Usage**: Primary source for song previews, artwork, and audio characteristics
- **Benefits**: Enables audio feature analysis (tempo, danceability, energy, etc.)
- **Obtain API Keys**: [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/)
### Deezer
Deezer serves as an alternative source for track metadata and previews:
- **Configuration**: Set `DEEZER_APP_ID` and `DEEZER_APP_SECRET`
- **Usage**: Alternative source when Spotify data is unavailable
- **Benefits**: Provides additional preview URLs and metadata
- **Obtain API Keys**: [Deezer Developers](https://developers.deezer.com/myapps)
### ACRCloud
ACRCloud can be used for music recognition and metadata enrichment:
- **Configuration**: Set `ACRCLOUD_TOKEN`
- **Usage**: Identify songs from audio samples
- **Benefits**: Enhanced metadata lookups using audio fingerprinting
- **Obtain API Keys**: [ACRCloud](https://www.acrcloud.com/)
### Metadata Enrichment Process
When a song is imported into Quizzical Beats:
1. The system first checks if the song has an ISRC (International Standard Recording Code)
2. If an ISRC is available, it's used to find metadata across all configured services
3. The system consolidates data from multiple sources to create a comprehensive record
4. If an ISRC is unavailable, the system relies on the original source's data
5. Genre information is converted to tags for improved searchability
For optimal metadata quality, we recommend configuring at least Spotify and Last.fm APIs.
### Database Configuration
```bash
# SQLite (default)
SQLALCHEMY_DATABASE_URI=sqlite:///data/song_data.db
SQLALCHEMY_TRACK_MODIFICATIONS=False
# For MySQL/MariaDB:
# SQLALCHEMY_DATABASE_URI=mysql+pymysql://username:password@localhost/musicround
# For PostgreSQL:
# SQLALCHEMY_DATABASE_URI=postgresql://username:password@localhost/musicround
```
### OAuth Provider Configuration
```bash
# Spotify API configuration
SPOTIFY_CLIENT_ID=your-spotify-client-id
SPOTIFY_CLIENT_SECRET=your-spotify-client-secret
SPOTIFY_REDIRECT_URI=http://localhost:5000/auth/spotify/callback
# Deezer API configuration
DEEZER_APP_ID=your-deezer-app-id
DEEZER_APP_SECRET=your-deezer-app-secret
DEEZER_REDIRECT_URI=http://localhost:5000/deezer-callback
# Google OAuth configuration
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
# Authentik OAuth configuration
AUTHENTIK_CLIENT_ID=your-authentik-client-id
AUTHENTIK_CLIENT_SECRET=your-authentik-client-secret
AUTHENTIK_METADATA_URL=https://authentik.example.com/.well-known/openid-configuration
# Dropbox OAuth configuration
DROPBOX_APP_KEY=your-dropbox-app-key
DROPBOX_APP_SECRET=your-dropbox-app-secret
DROPBOX_REDIRECT_URI=http://localhost:5000/users/dropbox/callback
```
### Email Configuration
```bash
# Email settings
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USE_TLS=True
MAIL_USE_SSL=False
MAIL_USERNAME=your-email-username
MAIL_PASSWORD=your-email-password
MAIL_SENDER=quizzical-beats@example.com
MAIL_RECIPIENT=admin@example.com
```
### Automation Settings
```bash
# Used for automated tasks and API access
AUTOMATION_TOKEN=your-secure-automation-token
```
## Configuration File (.env)
Create a `.env` file in the root directory with your configuration variables. You can copy the provided `.env.demo` file as a starting point:
```bash
cp .env.demo .env
```
Then edit the `.env` file with your actual configuration values:
```bash
# Example .env file (simplified)
SECRET_KEY=your-secure-secret-key
DEBUG=True
SQLALCHEMY_DATABASE_URI=sqlite:///data/song_data.db
SPOTIFY_CLIENT_ID=your-spotify-client-id
SPOTIFY_CLIENT_SECRET=your-spotify-client-secret
# Add other variables as needed
```
## Configuration Priority
Quizzical Beats loads configuration in the following order of priority:
1. Environment variables set in the system
2. Variables in the `.env` file
3. Default values defined in the `config.py` file
## Docker Environment Variables
When using Docker, you can pass environment variables through the `docker-compose.yml` file:
```yaml
version: '3'
services:
app:
build: .
environment:
- SECRET_KEY=your-secure-secret-key
- SQLALCHEMY_DATABASE_URI=postgresql://postgres:password@db/musicround
- SPOTIFY_CLIENT_ID=your-spotify-client-id
- SPOTIFY_CLIENT_SECRET=your-spotify-client-secret
# Add other variables as needed
volumes:
- ./data:/app/data
```
## Required Configuration
The following variables are required for core functionality:
- `SECRET_KEY`: Used for securing sessions and CSRF tokens
- `SQLALCHEMY_DATABASE_URI`: Database connection string
## Optional Configuration
These configurations enable additional features:
### Spotify Integration
Required for importing playlists and tracks from Spotify:
- `SPOTIFY_CLIENT_ID`
- `SPOTIFY_CLIENT_SECRET`
- `SPOTIFY_REDIRECT_URI`
### Dropbox Integration
Required for exporting rounds to Dropbox:
- `DROPBOX_APP_KEY`
- `DROPBOX_APP_SECRET`
- `DROPBOX_REDIRECT_URI`
### OAuth Authentication
Required for sign-in with external providers:
- Google: `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
- Authentik: `AUTHENTIK_CLIENT_ID`, `AUTHENTIK_CLIENT_SECRET`, `AUTHENTIK_METADATA_URL`
## Applying Configuration Changes
After changing configuration:
1. For a standard installation, restart the application:
```bash
sudo systemctl restart quizzical-beats
# Or if using Gunicorn directly:
kill -HUP $(cat gunicorn.pid)
```
2. For Docker installations:
```bash
docker-compose down
docker-compose up -d
```
## Verifying Configuration
To verify your configuration:
1. Check the application logs after startup
2. Visit the Admin > System > Settings page in the web interface
3. Check the system health on the Admin > System > Health Dashboard page
docs/admin-guide/installation.md
+304
View File
@@ -0,0 +1,304 @@
# 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](https://docs.docker.com/get-docker/)
2. Install [Docker Compose](https://docs.docker.com/compose/install/)
### Deployment Steps
1. Clone the repository:
```bash
git clone https://github.com/christianlouis/musicround.git
cd musicround
```
2. Configure environment variables:
```bash
cp .env.demo .env
```
Edit the `.env` file to set your configuration options, including API keys and database settings.
3. Start the application:
```bash
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:
```yaml
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):
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
### Installation Steps
1. Clone the repository:
```bash
git clone https://github.com/christianlouis/musicround.git
cd musicround
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Configure environment variables:
```bash
cp .env.demo .env
```
Edit the `.env` file with your configuration settings.
4. Create necessary directories:
```bash
mkdir -p data/backups mp3
```
5. Initialize the database:
```bash
python run_migration.py
```
6. Start the application:
```bash
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:
```bash
pip install gunicorn
```
2. Configure Gunicorn:
```bash
gunicorn -w 4 -b 127.0.0.1:8000 "musicround:create_app()"
```
3. Set up Nginx as a reverse proxy:
```nginx
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):
```bash
sudo certbot --nginx -d your-domain.com
```
### Database Configuration
For larger deployments, use PostgreSQL:
1. Install PostgreSQL and create a database:
```bash
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:
```bash
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:
```bash
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](https://developer.spotify.com/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](https://www.dropbox.com/developers/apps)
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](https://platform.openai.com/account/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:
```bash
python -c "from musicround import db; db.create_all()"
```
2. Reset the migration if needed:
```bash
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:
```bash
ls -la data mp3 backups
```
2. Update permissions if needed:
```bash
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:
```bash
tail -f logs/quizzical-beats.log
```
2. Verify that all required dependencies are installed:
```bash
pip install -r requirements.txt
```
3. Check if another process is using port 5000:
```bash
sudo lsof -i :5000
```
docs/admin-guide/system-health.md
+141
View File
@@ -0,0 +1,141 @@
# System Health Monitoring
This guide explains how to monitor, troubleshoot, and maintain the health of your Quizzical Beats installation.
## Health Dashboard
Quizzical Beats provides a built-in health dashboard that gives you a comprehensive overview of your system:
1. Log in as an administrator
2. Navigate to Admin > System > Health Dashboard
3. The dashboard displays:
- Database information (status, song count, round count, user count)
- Storage information (directory status, file counts, sizes)
- External service status
- Memory usage
- Version information
### Health Status Cards
The top of the health dashboard features status cards that provide a quick overview of your system's health:
- **Database**: Connection status and database health
- **Storage**: File storage status and access permissions
- **API Services**: Status of external API connections
- **Memory**: System memory availability and usage
Each card is color-coded to indicate status:
- Green: Good/healthy
- Yellow: Warning/potential issues
- Red: Error/critical issues
## Database Monitoring
### Database Statistics
The database section of the health dashboard shows:
- Total number of songs in the database
- Total number of rounds
- Total number of users
- Database file size
- Last backup timestamp
This information helps you track database growth and ensure you're performing regular backups.
## Storage Monitoring
The storage section provides information about key directories:
- Directory name
- Number of files in each directory
- Total size of files
- Write permission status
This helps you identify potential storage issues such as:
- Lack of write permissions
- Unexpected growth in file count or size
- Directories approaching storage limits
## External Service Monitoring
The External Services section displays the status of integrated third-party services:
- Service name
- Connection status (Available, Warning, Unavailable)
- Status details or error messages
Services monitored may include:
- Spotify API
- Dropbox API
- OpenAI API
- Email service
- Other integrated services based on your configuration
## Version Information
The Version Information section shows:
- Application version
- Release name
- Release date
- Python version
- Operating system platform
- Flask version
This information is essential when troubleshooting issues or planning updates.
## Troubleshooting Common Issues
### Database Connection Issues
If the database status shows errors:
1. Check database credentials in your `.env` file
2. Verify that the database file exists at the configured location
3. Check file permissions on the database file
4. Ensure there's enough disk space for database growth
### Storage Issues
If the Storage status shows problems:
1. Check directory permissions for the affected directories
2. Verify that the application has write access to these directories
3. Ensure sufficient disk space is available
4. Check for file corruption or missing critical files
### External Service Connectivity
If service connections are failing:
1. Verify API keys and credentials in your `.env` file
2. Check that redirect URIs are correctly configured
3. Test external connectivity to the service endpoints
4. Verify SSL certificates are valid for secure connections
5. Check for API rate limiting or service outages
## CLI Health Checks
For command-line health checks, you can use:
```bash
python run.py health check
```
This command performs basic health checks and outputs the results to the console, which is useful for automated monitoring scripts.
## Best Practices for System Health
1. **Regular Monitoring**: Check the health dashboard at least weekly
2. **Automated Alerts**: Set up external monitoring for critical services
3. **Preventive Maintenance**: Address warning signs before they become critical
4. **Regular Backups**: Configure automated backups and verify them regularly
5. **Update Management**: Keep the application and dependencies up to date
6. **Resource Planning**: Monitor growth trends to plan for future resource needs
## Related Documentation
- [Backup and Restore](backup-restore.md) - For information on configuring backups
- [Configuration Guide](configuration.md) - For details on configuring external services
- [Installation Guide](installation.md) - For system requirements and setup