silverbullet-notes/docs/apps/mixarr.md

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

-   **Repository**: https://github.com/aquantumofdonuts/mixarr
-   **Web UI**: https://mixarr.3ddbrewery.com
-   **API**: https://api.mixarr.3ddbrewery.com
-   **Location**: `/mnt/docker-storage/appdata/mixarr`

## 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`:

```bash
# 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**:
```yaml
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**:
```yaml
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**:
```yaml
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**:
    ```bash
    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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
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

-   [Service Inventory](../00-service-inventory.md#mixarr) - Container details
-   [Database Documentation](../02-databases.md#mixarr-mysql) - Database information
-   [Troubleshooting Guide](../06-troubleshooting.md) - General troubleshooting steps
-   [Mixarr GitHub Repository](https://github.com/aquantumofdonuts/mixarr) - Upstream documentation