martitoci/sonarr-analyzer repository overview

⁠📊 Sonarr Analyzer

A web application built with Streamlit for analyzing and monitoring your Sonarr library. Track episode file sizes, detect outliers, compare historical analyses, forecast storage growth, and manage multiple Sonarr instances — all from a single, multi-user interface with role-based access control and encrypted credential storage.

⁠📋 Table of Contents

• What's New in v0.4⁠
• Prerequisites⁠
• Quick Start⁠
• Screenshots⁠
• Usage Guide⁠
• Authentication Flow⁠
• User Roles⁠
• User Management⁠
• Multi-Instance Support⁠
• Token Security⁠
• Running Your First Analysis⁠
• Historical Data⁠
• Scheduled Analysis⁠
• Running Tests⁠
• Data Persistence⁠
• Understanding the Results⁠
• Configuration⁠
• Docker Image Details⁠
• Troubleshooting⁠
• Use Cases⁠
• Building from Source⁠
• Version History⁠
• Contributing⁠
• License⁠
• Quick Commands Reference⁠

⁠🆕 What's New in v0.4

• 📊 Dashboard — Overview with key metrics and comparisons from the last two analyses
• 🎬 Episode Breakdown — Per-episode file detail within the current analysis result
• 📈 Storage Forecast — Linear regression trend to project future storage needs
• 🎞️ Codec Distribution — Historical view of storage usage grouped by quality profile
• 🏠 Multi-Instance Sonarr — Manage multiple Sonarr servers per user with separate history
• ⏰ Scheduled Analysis — Configure automatic analyses per instance (hourly/daily/weekly)
• 🔒 Profile & Password Change — Each user can update their own password

⁠✅ Prerequisites

Before you start, make sure you have:

• Docker v20.10+ installed (Get Docker⁠)
• Docker Compose v2.0+ (included with Docker Desktop)
• A running Sonarr instance with API access
• Your Sonarr API key (Settings → General → Security)

⁠🚀 Quick Start with Docker

⁠Pull and Run (Recommended)

# Pull the latest image
docker pull martitoci/sonarr-analyzer:latest

# Run with persistent data
docker run -d \
  --name sonarr-analyzer \
  -p 8501:8501 \
  -v sonarr-data:/app/data \
  --restart unless-stopped \
  martitoci/sonarr-analyzer:latest

Access the application: http://localhost:8501⁠

⁠Using Docker Compose

Save this as docker-compose.yml and run docker compose up -d:

services:
  sonarr-analyzer:
    image: martitoci/sonarr-analyzer:latest
    container_name: sonarr-analyzer
    ports:
      - "8501:8501"
    volumes:
      - sonarr-data:/app/data
    restart: unless-stopped

volumes:
  sonarr-data:

⁠📸 Screenshots

⁠Dashboard & Analysis

Main dashboard showing series analysis with file sizes, outliers, and detailed metrics

⁠Historical Data & Trends

Historical data view with storage evolution, trends over time, and date comparisons

⁠📖 Usage Guide

⁠First Time Setup

1. Start the container (see Quick Start above)
2. Open your browser: http://localhost:8501⁠
3. Create Admin Account:
   • On first launch you'll see the "Create Admin Account" screen
   • Enter username (min 3 characters) and password (min 8 characters)
   • Click "Create Admin Account"
4. Login with your new admin credentials
5. Configure Sonarr:
   • Go to "🔑 Configuration" in the sidebar
   • Add your first Sonarr instance (URL + API Key)
   • Give it a name (e.g., home, remote)
6. Activate the instance and run your first analysis

⁠🔐 Authentication Flow

⁠First Run (No Admin Exists)

Start App → Create Admin Screen → Create Admin → Login Screen → Dashboard

⁠Subsequent Runs (Admin Exists)

Start App → Login Screen → Enter Credentials → Dashboard

⁠👤 User Roles

⁠👥 User Management (Admin Only)

1. Login as admin
2. Go to "👥 User Management" in the sidebar
3. Create users with username, password, and role (admin or readonly)
4. View all users (created date, last login)
5. Delete users (cannot delete yourself or the last admin)

⁠🌐 Multi-Instance Support

Each user can add and manage multiple Sonarr instances independently.

⁠Adding an Instance

1. Go to "🔑 Configuration"
2. Under Add / Update Instance, enter:
   • Instance name (e.g., home, 4k, remote)
   • Sonarr URL
   • API Key
3. Click Save Instance

⁠Switching Instances

• Use the Active Instance selector at the top of the Configuration page
• All analyses, history, and schedules are stored separately per instance

⁠Deleting an Instance

• Select the instance and click Delete Instance
• This removes the saved credentials; historical data is preserved

⁠🔑 Token Security

• Each user's Sonarr URL and API key are encrypted with Fernet (AES-128 CBC) before being stored in SQLite
• A master encryption key is generated on first startup and stored in /app/data/.master.key
• Tokens are decrypted in-session only — never stored in plain text

⁠Best Practices

✅ Use strong passwords · Back up your data volume · Use HTTPS behind a reverse proxy
❌ Don't share the master key · Don't expose port 8501 directly to the internet

⁠📊 Running Your First Analysis

1. Login and ensure an instance is active (see Configuration)
2. Go to "🔍 Analysis" in the sidebar
3. Configure options (optional):
   • Request timeout
   • Z-Score threshold
   • Absolute threshold (MB)
   • Enable "Save to history"
4. Click "🚀 Run Analysis"
5. Explore results across 4 tabs:
   • Table — All series with detailed metrics
   • Charts — Visual representations (size distribution, top series)
   • Episode Breakdown — Per-episode file detail for each series
   • Outliers — Series with unusually large files

⁠📈 Using Historical Data

Navigate to "📈 Historical Data" in the sidebar. Five tabs are available:

⁠All Analyses

Overview table of every saved analysis with storage evolution and average-size trend charts.

⁠Compare Dates

Select two past dates to compare. See new/removed series, storage delta, and a top-changers chart. Download as CSV.

⁠Trends

Select a series and view its total size, episode count, and average size over time.

⁠Codec Distribution

Stacked area chart showing storage breakdown by quality profile (codec) over time.

⁠Storage Forecast

Linear regression projection of total library size. Estimates when you'll hit storage milestones.

⁠⏰ Scheduled Analysis

Sonarr Analyzer supports passive scheduling: analyses run automatically when the app is loaded (no background process needed).

⁠Configuring a Schedule

1. Go to "⏰ Scheduler" in the sidebar
2. Select a frequency: every 1 h, 6 h, 12 h, 24 h, 48 h, or 168 h (weekly)
3. Click Save Schedule
4. The next run time is displayed; the analysis triggers on the next page load after that time

⁠Notes

• Each instance has its own schedule
• Results are saved to history automatically
• The scheduler tab shows the last run time and current status

⁠🧪 Running Tests

# Install dependencies
pip install -r requirements.txt

# Run all tests
pytest -v

# Run with coverage
pytest --cov=. --cov-report=html tests/

Coverage includes: Authentication, token encryption, storage operations, integration workflows, role enforcement, and schema migrations.

⁠💾 Data Persistence

⁠Files Stored in /app/data

⁠Backup

# Backup named volume
docker run --rm \
  -v sonarr-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/sonarr-backup.tar.gz -C /data .

# Restore
docker run --rm \
  -v sonarr-data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/sonarr-backup.tar.gz -C /data

⁠Bind Mount (Host Directory)

mkdir -p ./sonarr-data
# Linux/macOS: fix ownership for UID 1000 (container user)
sudo chown -R 1000:1000 ./sonarr-data

docker run -d \
  --name sonarr-analyzer \
  -p 8501:8501 \
  -v $(pwd)/sonarr-data:/app/data \
  martitoci/sonarr-analyzer:latest

⁠📊 Understanding the Results

⁠Metrics Explained

⁠Z-Score Interpretation

Z-Score = (Value − Mean) / Std Deviation

⁠🔧 Configuration

⁠Environment Variables

⁠Custom Port

docker run -d --name sonarr-analyzer -p 9000:8501 \
  -v sonarr-data:/app/data \
  martitoci/sonarr-analyzer:latest
# Access at http://localhost:9000

⁠🐳 Docker Image Details

• Base Image: python:3.11-slim
• Architecture: linux/amd64, linux/arm64
• User: Non-root (UID 1000, appuser)
• Health Check: Built-in Python-based check (no curl required)
• Privilege Drop: gosu (GPG-verified, official Docker pattern)

⁠Tags

docker pull martitoci/sonarr-analyzer:latest
docker pull martitoci/sonarr-analyzer:v0.4.0

⁠🔍 Troubleshooting

⁠Cannot Login

• Verify credentials (case-sensitive)
• Check logs: docker logs sonarr-analyzer
• To reset all user accounts (tokens and history preserved):

  docker exec sonarr-analyzer rm /app/data/users.db
  docker restart sonarr-analyzer
  

  Copy

⁠Database Permission Error (Bind Mounts)

# Fix ownership on the host
sudo chown -R 1000:1000 /path/to/your/data

The entrypoint script attempts to fix this automatically when the container runs as root. For persistent issues, switch to a named volume.

⁠Cannot Connect to Sonarr

• Use the full URL including protocol: http://192.168.1.10:8989
• Use the host's LAN IP or container name, not localhost
• Verify the API key in Sonarr → Settings → General → Security

⁠Database Locked

docker restart sonarr-analyzer

⁠Master Key Lost

All encrypted tokens become unrecoverable — users must re-enter their Sonarr credentials. Always back up /app/data.

⁠📈 Use Cases

Monthly Storage Audit: Run on the 1st of each month, compare with the previous run to identify growth outliers.

Pre/Post Re-encoding: Run before and after re-encoding high-Z-score series to measure savings.

Multi-Server Monitoring: Each team member or household user manages their own Sonarr instance credentials and sees only their own history.

Proactive Planning: Use the Storage Forecast tab to know when to add drives before you run out of space.

⁠🛠️ Building from Source

git clone https://github.com/chmedinap/sonarr-analyzer.git
cd sonarr-analyzer

docker build -t sonarr-analyzer:local .

docker run -d \
  --name sonarr-analyzer \
  -p 8501:8501 \
  -v sonarr-data:/app/data \
  sonarr-analyzer:local

⁠📝 Version History

⁠v0.4.0 (Current)

• ➕ Dashboard with key metrics and last-analysis comparison
• ➕ Episode breakdown tab in analysis results
• ➕ Storage forecast (linear regression) in historical view
• ➕ Codec/quality distribution chart in historical view
• ➕ Multi-instance Sonarr support (separate history per instance)
• ➕ Passive scheduler (hourly → weekly, per instance)
• ➕ Profile page with password change
• 🔧 Fixed @st.cache_data incompatibility with progress UI
• 🔧 Fixed requests.Session resource leak
• 🔧 Fixed rowcount capturing wrong table in delete operations
• 🔧 Schema migrations for existing databases (no data loss on upgrade)

⁠v0.3.0

• ➕ User authentication with bcrypt
• ➕ Role-based access control (admin / read-only)
• ➕ Per-user encrypted token storage (Fernet)
• ➕ First-run admin creation flow
• ➕ User management (admin only)
• ➕ 60+ comprehensive unit tests

⁠v0.2.0

• ➕ Credential encryption (AES-256)
• ➕ SQLite historical database
• ➕ Date comparison feature
• ➕ Trend visualizations

⁠v0.1.0

• Initial release: current analysis, Z-score detection, outlier identification

⁠🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Run pytest -v and verify all pass
5. Submit a pull request

⁠📄 License

MIT License — see LICENSE file for details.

⁠📞 Support

• 🐳 Docker Hub: https://hub.docker.com/r/martitoci/sonarr-analyzer⁠
• 📧 Issues: https://github.com/chmedinap/sonarr-analyzer/issues⁠
• 💬 Discussions: https://github.com/chmedinap/sonarr-analyzer/discussions⁠

⁠⚡ Quick Commands Reference

# Pull latest image
docker pull martitoci/sonarr-analyzer:latest

# Run with persistent data
docker run -d --name sonarr-analyzer -p 8501:8501 \
  -v sonarr-data:/app/data --restart unless-stopped \
  martitoci/sonarr-analyzer:latest

# View logs
docker logs -f sonarr-analyzer

# Stop / remove
docker stop sonarr-analyzer
docker rm sonarr-analyzer

# Backup data volume
docker run --rm -v sonarr-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/sonarr-backup.tar.gz -C /data .

# Update to latest
docker pull martitoci/sonarr-analyzer:latest
docker stop sonarr-analyzer && docker rm sonarr-analyzer
docker run -d --name sonarr-analyzer -p 8501:8501 \
  -v sonarr-data:/app/data --restart unless-stopped \
  martitoci/sonarr-analyzer:latest

Made with ❤️ for the Sonarr community