Wizarr Deployment and Usage Guide

1. Prerequisites

Before installing Wizarr, ensure you have the following:

System Requirements:

Python 3.8 or higher
SQLite database (included) or PostgreSQL
512MB RAM minimum (1GB recommended)
100MB disk space

Required Accounts/API Access:

Media server admin account (Plex, Jellyfin, Emby, Audiobookshelf, Komga, Kavita, or Romm)
Optional: Overseerr or Ombi account for request system integration
Optional: Discord server for Discord invite support

Supported Media Servers:

Plex
Jellyfin
Emby
Audiobookshelf
Komga
Kavita (v0.8.8.3+)
Romm

2. Installation

Docker Installation (Recommended)

# Create a directory for Wizarr
mkdir wizarr && cd wizarr

# Create docker-compose.yml
cat > docker-compose.yml << EOF
version: '3.8'

services:
  wizarr:
    image: ghcr.io/wizarrrr/wizarr:latest
    container_name: wizarr
    restart: unless-stopped
    ports:
      - "5690:5690"
    volumes:
      - ./data:/data
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
EOF

# Start Wizarr
docker-compose up -d

Manual Installation (Python)

# Clone the repository
git clone https://github.com/wizarrrr/wizarr.git
cd wizarr

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

# Install dependencies
pip install -r requirements.txt

# Initialize database
flask db upgrade

3. Configuration

Environment Variables

Create a .env file in your Wizarr directory:

# Database Configuration
DATABASE_URL=sqlite:///data/wizarr.db
# For PostgreSQL: postgresql://user:password@localhost/wizarr

# Flask Configuration
SECRET_KEY=your-secret-key-here
FLASK_ENV=production
FLASK_DEBUG=0

# Server Configuration
HOST=0.0.0.0
PORT=5690
BASE_URL=https://your-domain.com  # For reverse proxy setups

# Security
SESSION_COOKIE_SECURE=True
SESSION_COOKIE_HTTPONLY=True

Media Server Configuration

After initial setup, access the web interface at http://localhost:5690 and configure:

Add Media Server:
- Navigate to Settings → Servers
- Click "Add Server"
- Select server type (Plex, Jellyfin, etc.)
- Enter server URL and API key/token
API Key Requirements:
- Plex: X-Plex-Token from https://plex.tv/api/v2/user
- Jellyfin: API key from Dashboard → Advanced → API Keys
- Emby: API key from Dashboard → API Keys
- Kavita: API key from Settings → Authentication → API Keys
Library Access:
- Configure which libraries new users can access
- Set default permissions per invitation tier

Invitation Configuration

Configure invitation settings in the web interface:

Create Invitation Templates:
- Set expiration dates
- Configure multi-tier access levels
- Define pre-invite and post-invite wizard steps
Customize Wizard Steps:
- Add custom HTML snippets
- Configure media app download guides
- Integrate request systems (Overseerr/Ombi)

4. Build & Run

Development Mode

# Activate virtual environment
source venv/bin/activate

# Set development environment
export FLASK_ENV=development
export FLASK_DEBUG=1

# Run development server
flask run --host=0.0.0.0 --port=5690

Production Mode

# Using Gunicorn (recommended for production)
pip install gunicorn
gunicorn --bind 0.0.0.0:5690 --workers 4 "app:create_app()"

# Or using waitress (Windows compatible)
pip install waitress
waitress-serve --host 0.0.0.0 --port 5690 "app:create_app"

Building Docker Image

# Clone repository
git clone https://github.com/wizarrrr/wizarr.git
cd wizarr

# Build Docker image
docker build -t wizarr:latest .

# Run custom image
docker run -d \
  --name wizarr \
  -p 5690:5690 \
  -v ./data:/data \
  wizarr:latest

5. Deployment

Docker Deployment

# Using Docker Compose (recommended)
docker-compose up -d

# Check logs
docker-compose logs -f wizarr

Reverse Proxy Setup (Nginx)

server {
    listen 80;
    server_name wizarr.your-domain.com;
    
    location / {
        proxy_pass http://localhost:5690;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
    }
}

Reverse Proxy Setup (Caddy)

wizarr.your-domain.com {
    reverse_proxy localhost:5690
}

Platform Recommendations

Self-hosted: Docker on any Linux server
VPS: DigitalOcean, Linode, or Vultr with Docker
NAS: Unraid, TrueNAS, or Synology with Docker support
Cloud: AWS ECS, Google Cloud Run, or Azure Container Instances
Orchestration: Kubernetes with Helm chart (community-provided)

Database Backup

# SQLite backup
sqlite3 data/wizarr.db ".backup backup.db"

# PostgreSQL backup
pg_dump wizarr > wizarr_backup.sql

# Schedule automatic backups (cron)
0 2 * * * /usr/bin/sqlite3 /path/to/data/wizarr.db ".backup /backups/wizarr-$(date +\%Y\%m\%d).db"

6. Troubleshooting

Common Issues

Issue: "Cannot connect to media server"

# Check network connectivity
curl -v https://your-plex-server:32400

# Verify API key is valid
# For Plex: https://plex.tv/api/v2/user?X-Plex-Token=YOUR_TOKEN
# For Jellyfin: Check Dashboard → Advanced → API Keys

# Ensure CORS is configured on media server

Issue: Database errors

# Reset database (will lose data!)
flask db stamp head
flask db migrate
flask db upgrade

# Check database integrity
sqlite3 data/wizarr.db "PRAGMA integrity_check;"

Issue: Invitations not working

Check invitation expiration date
Verify media server connection is active
Ensure libraries are properly configured
Check user limit hasn't been reached on media server

Issue: API endpoints not accessible

# Check if API is running
curl http://localhost:5690/api/status

# Interactive API docs available at:
# http://localhost:5690/api/docs/
# OpenAPI spec: http://localhost:5690/api/swagger.json

Logs and Debugging

View Docker logs:

docker-compose logs -f wizarr
# Or for specific service
docker logs wizarr --tail 100 -f

Enable debug logging:

# In .env file
LOG_LEVEL=DEBUG
FLASK_DEBUG=1

Check session management:

# Session issues often relate to SECRET_KEY
# Generate a new secure key:
python -c "import secrets; print(secrets.token_hex(32))"

Media Server Specific Issues:

Jellyfin:

Ensure "Allow remote connections" is enabled
Verify X-Emby-Token is correctly set in headers
Check library IDs match between Wizarr and Jellyfin

Kavita:

Requires Kavita v0.8.8.3 or higher
API key must be generated in Settings → Authentication
JWT token caching issues: Clear _JWT_TOKEN_CACHE or restart

Plex:

Plex token must have admin privileges
Server must be claimed (not using Plex Relay)
Check Plex server logs for authentication errors

Performance Issues

High Memory Usage:

# Reduce worker count for Gunicorn
gunicorn --bind 0.0.0.0:5690 --workers 2 "app:create_app()"

# Increase cleanup interval for session manager
# Modify app/activity/monitoring/session_manager.py
self.cleanup_interval = 600  # 10 minutes

Database Locking:

# For SQLite, ensure proper file permissions
chown -R 1000:1000 ./data

# Consider switching to PostgreSQL for high concurrency
DATABASE_URL=postgresql://user:password@localhost/wizarr

Getting Help

Check Documentation: https://docs.wizarr.dev
API Documentation: Accessible at http://your-instance:5690/api/docs/
GitHub Issues: https://github.com/wizarrrr/wizarr/issues
Discord Community: https://discord.gg/NYxwcjCK9x
Check Logs: Always include relevant logs when seeking help

Maintenance

Regular maintenance tasks:

# Update Wizarr
docker-compose pull
docker-compose up -d

# Clean up old Docker images
docker image prune -a

# Backup database regularly
# Check for application updates
# Review invitation usage and clean up expired invites

How to Deploy & Use wizarr