maddox/silverbullet-notes
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
silverbullet-notes/docs/apps/mixarr.md
maddox 3dc0f4dacf Initial SilverBullet sync
2026-01-25 00:20:24 +00:00

9.3 KiB
Raw Blame History

Mixarr

Last updated: 2026-01-05

Overview

Mixarr is an AI-powered music discovery and automation tool that enhances Lidarr with intelligent artist recommendations. It integrates with multiple music streaming services and uses LLM providers to discover new music based on listening history and preferences.

Architecture

Mixarr consists of four containerized services:

Services

  1. mixarr_web - Next.js 14 frontend

    • Port: 3006 (host) → 3000 (container)
    • Networks: mixarr_internal, traefik_proxy
    • Purpose: User interface for configuration and monitoring

  2. mixarr_api - Express.js backend

    • Port: 3005
    • Networks: mixarr_internal, traefik_proxy
    • Purpose: Handles Lidarr integration, music service APIs, and LLM interactions
    • Startup: Runs Prisma database migrations automatically

  3. mixarr_mysql - MySQL 8.0 database

    • Port: 3306 (internal only)
    • Network: mixarr_internal
    • Volume: mixarr_mysql_data (Docker volume)
    • Character Set: utf8mb4_unicode_ci

  4. mixarr_redis - Redis 7 cache

    • Port: 6379 (internal only)
    • Network: mixarr_internal
    • Volume: mixarr_redis_data (Docker volume)
    • Purpose: Session storage and job queue

Music Service Integrations

Mixarr can connect to multiple music services for discovery and metadata:

  • Spotify: OAuth-based (requires HTTPS)
  • TIDAL: OAuth-based
  • Deezer: OAuth-based
  • Last.fm: API key-based
  • MusicBrainz: API access (free, no key required)
  • Plex/Tautulli: API key-based (for listening history)
  • Jellyfin: API key-based (for listening history)
  • ListenBrainz: Token-based (open source Last.fm alternative)

LLM Providers

Mixarr uses Large Language Models to analyze listening patterns and recommend new artists:

  • OpenAI: Requires API key
  • Anthropic: Requires API key
  • Ollama: Self-hosted, no API key needed (can run locally)

Configuration

Environment Variables

Located in /mnt/docker-storage/appdata/mixarr/.env:

# Database
MYSQL_ROOT_PASSWORD=<secure-password>
MYSQL_DATABASE=mixarr
MYSQL_USER=mixarr
MYSQL_PASSWORD=<secure-password>

# Session Security
SESSION_SECRET=<generated-with-openssl>

# API URL (must match Traefik configuration)
NEXT_PUBLIC_API_URL=https://api.mixarr.3ddbrewery.com

Traefik Configuration

Traefik routes are configured on the central Traefik server (dyno.yml):

Web UI Router:

mixarr-web:
  entryPoints:
  - web-secure
  tls:
    certResolver: default
  service: mixarr-web
  rule: Host(`mixarr.fails.me`) || Host(`mixarr.3ddbrewery.com`)
  middlewares:
  - secure-headers
  - authentik

API Router:

mixarr-api:
  entryPoints:
  - web-secure
  tls:
    certResolver: default
  service: mixarr-api
  rule: Host(`api.mixarr.fails.me`) || Host(`api.mixarr.3ddbrewery.com`)
  middlewares:
  - secure-headers
  - authentik

Services:

mixarr-web:
  loadBalancer:
    servers:
    - url: http://192.168.1.252:3006
    passHostHeader: false

mixarr-api:
  loadBalancer:
    servers:
    - url: http://192.168.1.252:3005
    passHostHeader: false

Initial Setup

  1. Start the containers:

    cd /mnt/docker-storage/appdata/mixarr
docker-compose up -d

  2. Access the web UI: Navigate to https://mixarr.3ddbrewery.com

  3. Create an admin account: First user to register becomes admin

  4. Configure Base URL:

    • Go to Settings → General
    • Set Base URL to https://mixarr.3ddbrewery.com
    • This is required for OAuth callbacks to work

  5. Connect to Lidarr:

    • Go to Settings → Lidarr
    • Add Lidarr URL and API key

  6. Connect music services:

    • Go to Settings → Integrations
    • Connect Spotify, Last.fm, or other services
    • OAuth services require HTTPS (provided by Traefik)

  7. Configure LLM provider:

    • Go to Settings → LLM
    • Choose OpenAI, Anthropic, or Ollama
    • Add API key if required

Common Operations

Container Management

# Navigate to mixarr directory
cd /mnt/docker-storage/appdata/mixarr

# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f web
docker-compose logs -f api

# Restart after configuration changes
docker-compose restart web
docker-compose restart api

# Stop all services
docker-compose down

# Start all services
docker-compose up -d

Database Operations

# Connect to MySQL
docker exec -it mixarr_mysql mysql -u mixarr -p

# View current migration status
docker exec -it mixarr_api npx prisma migrate status

# Manually run migrations
docker exec -it mixarr_api npx prisma migrate deploy

Redis Operations

# Connect to Redis CLI
docker exec -it mixarr_redis redis-cli

# View all keys
docker exec -it mixarr_redis redis-cli KEYS '*'

# Flush cache (if needed for troubleshooting)
docker exec -it mixarr_redis redis-cli FLUSHALL

Troubleshooting

OAuth Callbacks Failing

Symptoms: Spotify or TIDAL authentication fails after redirecting back to mixarr.

Resolution:

  1. Ensure Base URL is set correctly in Settings → General
  2. Verify Traefik is providing HTTPS for both web and API
  3. Check that DNS resolves correctly for your domains
  4. Review API logs: docker-compose logs -f api

API Not Connecting to Database

Symptoms: API container restarts repeatedly, web UI shows "Cannot connect to API".

Resolution:

  1. Check MySQL health: docker exec -it mixarr_mysql mysqladmin ping -u root -p
  2. View API logs: docker logs mixarr_api
  3. Verify database credentials in .env file
  4. Ensure Prisma migrations completed: Look for "Running database migrations" in logs

Session Issues

Symptoms: Logged out frequently, cannot stay authenticated.

Resolution:

  1. Verify SESSION_SECRET is set in both api and web services in docker-compose.yml
  2. Clear Redis cache: docker exec -it mixarr_redis redis-cli FLUSHALL
  3. Restart services: docker-compose restart api web

Port 3006 Conflict

Symptoms: Web container fails to start, port already in use.

Solution: The Books V2 frontend was originally on port 3000, which is why mixarr web is on 3006. If you need to change the port:

  1. Edit docker-compose.yml and change 3006:3000 to a different port
  2. Update Traefik service configuration with the new port
  3. Restart: docker-compose up -d

Backup and Restore

Backup

# Navigate to mixarr directory
cd /mnt/docker-storage/appdata/mixarr

# Backup database
docker exec mixarr_mysql mysqldump -u root -p mixarr > mixarr_backup_$(date +%Y%m%d).sql

# Backup environment variables
cp .env .env.backup_$(date +%Y%m%d)

# Backup docker-compose configuration
cp docker-compose.yml docker-compose.yml.backup_$(date +%Y%m%d)

Restore

# Restore database
docker exec -i mixarr_mysql mysql -u root -p mixarr < mixarr_backup_YYYYMMDD.sql

# Restore environment variables
cp .env.backup_YYYYMMDD .env

# Restart containers
docker-compose down
docker-compose up -d

Updates

Mixarr is configured with Watchtower for automatic updates. To manually update:

cd /mnt/docker-storage/appdata/mixarr
docker-compose pull
docker-compose down
docker-compose up -d

Performance Considerations

  • LLM API Costs: Be mindful of API usage if using OpenAI or Anthropic. Set appropriate limits in mixarr settings.
  • Ollama Local Hosting: For cost-free LLM usage, consider running Ollama locally. Requires GPU for best performance.
  • Rate Limiting: Music services (especially Spotify) have rate limits. Mixarr handles this automatically but very aggressive discovery schedules may hit limits.
  • Redis Memory: Monitor Redis memory usage if running many concurrent jobs. Default configuration should be sufficient for typical use.

Integration with Lidarr

Mixarr works by:

  1. Analyzing listening history from connected services (Last.fm, Plex, etc.)
  2. Using LLM to generate artist recommendations based on preferences
  3. Searching for recommended artists in music services (Spotify, MusicBrainz, etc.)
  4. Automatically adding matching artists to Lidarr for download
  5. Running on scheduled basis for continuous music discovery

Configure discovery schedules and preferences in Settings → Discovery.

Security Notes

  • Database Credentials: Strong passwords recommended in .env
  • SESSION_SECRET: Must be cryptographically random (generated with openssl rand -base64 32)
  • Authentication: Both web and API endpoints protected by Authentik
  • Network Isolation: MySQL and Redis only accessible on internal network
  • HTTPS: Enforced by Traefik for all external access
  • OAuth Secrets: Stored encrypted in database

Related Documentation