TrackWatch

Self-hosted music release tracker for Spotify users. Never miss a new release from your favorite artists again.

Why TrackWatch?

• Your data stays yours - Self-hosted means no third-party tracking your listening habits
• Automatic playlist updates - New releases are automatically added to your TrackWatch playlist
• Never miss a release - Checks for new music multiple times daily
• Simple deployment - Up and running in minutes with Docker

Quick Start

Prerequisites

• Docker installed
• A Spotify Developer app with Redirect URI: http://127.0.0.1:80/callback

Option A: Multi-Container (Docker Compose, Recommended)

Recommended for both self-hosting and deployment. Each service runs as its own container:

• frontend: Nginx serving the React app and proxying /api
• backend: Django + Gunicorn
• scheduler: optional APScheduler worker
• db: PostgreSQL

git clone https://github.com/emlopezr/trackwatch.git
cd trackwatch
cp .env.docker.example .env

Edit .env with your configuration:

SECRET_KEY=your-random-secret-key
DATABASE_PASSWORD=your-secure-password
SPOTIFY_CLIENT_ID=your-client-id
SPOTIFY_CLIENT_SECRET=your-client-secret

docker-compose up -d --build

Open http://127.0.0.1 and you're done.

To also run the internal scheduler:

docker-compose --profile scheduler up -d --build

If you want to deploy using prebuilt images instead of local builds, set these optional variables and pull them explicitly:

FRONTEND_IMAGE=ghcr.io/emlopezr/trackwatch-frontend:latest
BACKEND_IMAGE=ghcr.io/emlopezr/trackwatch-backend:latest
SCHEDULER_IMAGE=ghcr.io/emlopezr/trackwatch-scheduler:latest

docker-compose pull
docker-compose up -d

Option B: All-in-One Image (Legacy)

The previous AiO image is still documented for compatibility, but the active deployment model is now the multi-container setup above.

For the full legacy guide, see docs/DOCKER_AIO_SETUP.md.

For production deployment details, including running without the scheduler and triggering updates from n8n, see docs/DOCKER_MULTI_CONTAINER_SETUP.md.

For Dokploy deployments with each component as a separate app, see docs/DOKPLOY_SETUP.md.

Stop TrackWatch

docker-compose down

Configuration

Spotify Developer Setup

1. Go to Spotify Developer Dashboard
2. Click Create App
3. Fill in the app details:
   • App name: TrackWatch (or any name)
   • App description: Your description
   • Redirect URI: http://127.0.0.1:80/callback
   • Which API/SDKs are you planning to use? Web API
4. Click Settings and note your Client ID and Client Secret
5. Add these to your .env file

Important: Spotify only allows http:// for 127.0.0.1. Any other address (LAN IPs like 192.168.x.x, custom domains) requires HTTPS. localhost is not accepted at all.

Custom Domain

If deploying to a custom domain:

1. Update the redirect URI in your Spotify app settings to match your domain:

   https://your-domain.com/callback

2. Update your .env:

   VITE_SPOTIFY_REDIRECT_URI=https://your-domain.com/callback

3. Rebuild the frontend:

   docker-compose up -d --build frontend

Environment Variables Reference

Features

• Spotify Integration - Connect your Spotify account securely via OAuth
• Artist Tracking - Follow artists and track their releases automatically
• Automatic Playlist - New releases are added to a dedicated TrackWatch playlist
• Ghost Track Detection - Find and remove unavailable tracks from your playlists
• Scheduled Checks - Automatically checks for new releases 3x daily (7am, 2pm, 9pm)

Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                              Docker                                      │
├─────────────┬─────────────────────┬─────────────────┬────────────────────┤
│   Frontend  │      Backend        │    Scheduler    │     Database       │
│   (Nginx)   │     (Gunicorn)      │   (APScheduler) │    (PostgreSQL)    │
│             │                     │                 │                    │
│  React SPA  │     REST API        │   Background    │   User data +      │
│  + Reverse  │  + Spotify Auth     │   task runner   │   Track history    │
│    Proxy    │                     │                 │                    │
└─────────────┴─────────────────────┴─────────────────┴────────────────────┘

Background Tasks

The scheduler service is optional and runs independently from the web server when enabled with --profile scheduler, checking for new releases at configured times (default: 7am, 2pm, 9pm).

Alternative: External Triggers

If you prefer external scheduling (e.g., n8n, system cron), you can:

1. Start Compose without the scheduler profile: docker-compose up -d
2. Trigger updates via webhook:

   curl -X POST http://localhost/api/actions/releases \
     -H "X-Admin-Key: YOUR_SECRET_KEY"

Development

For local development without Docker, see docs/MANUAL_SETUP.md.

Tech Stack

• Frontend: React 18, TypeScript, Vite, React Router 7
• Backend: Django 5, Django REST Framework, APScheduler, Gunicorn
• Database: PostgreSQL 15
• Deployment: Docker, Nginx

Troubleshooting

"Invalid redirect URI" error

Ensure the redirect URI in your Spotify app settings matches exactly:

• For local Docker: http://127.0.0.1:80/callback
• For custom domain: https://your-domain.com/callback

Note: Spotify only allows http:// for 127.0.0.1. LAN IPs (e.g. 192.168.x.x) and custom domains require HTTPS. localhost is not accepted.

Container won't start

Check logs:

docker-compose logs backend
docker-compose logs frontend
docker-compose logs scheduler

Database connection issues

Ensure the database is healthy:

docker-compose ps

If db shows unhealthy, check PostgreSQL logs:

docker-compose logs db

Reset everything

docker-compose down -v
docker-compose up -d --build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License. See also the Data Handling Statement for information about how the application processes data.