Testerfy

Spotify Playlist Curation Made Easy

Quickly rate tracks with Like/Dislike buttons that auto-skip to the next song. Perfect for curating Discover Weekly, Release Radar, or any playlist you're auditioning.

Features

• 👍 Like → saves to your designated playlists, auto-skips
• 👎 Dislike → removes from current playlist, auto-skips
• 🛡️ Playlist Guard → lock to specific playlists to prevent accidents
• 📱 Mobile Friendly → works great on phones and tablets

One tap to rate and move on — no more fumbling through Spotify's UI!

Requirements

Unraid users can install from Community Applications (search Testerfy). Docker Compose and plain docker run also work — see Docker (Non-Unraid).

Setup

Spotify needs a public HTTPS callback URL that matches your SPOTIFY_REDIRECT_URI exactly. Pick any approach that gives you one:

• Reverse proxy / TLS — Nginx Proxy Manager, SWAG, Caddy, Cloudflare Tunnel, etc. in front of http://localhost:5247
• Tailscale Serve (optional) — quick HTTPS on your tailnet without a public domain

Your redirect URI is always: https://YOUR-PUBLIC-URL/api/auth/callback

Step 1: Expose Testerfy over HTTPS

Choose one method below. You only need one.

Option A: Reverse proxy (recommended for a public domain)

1. Point a subdomain at your server (e.g. testerfy.example.com)
2. Proxy https://testerfy.example.com → http://localhost:5247
3. Your redirect URI: https://testerfy.example.com/api/auth/callback

See Alternative HTTPS Methods for SWAG, NPM, and Cloudflare Tunnel examples.

Option B: Tailscale Serve (optional, no public domain)

1. Unraid → Apps → Search "Tailscale" → Install

2. Settings → Tailscale → Authenticate

3. Find your machine URL (hostname + tailnet) at login.tailscale.com/admin

   • Example machine URL: tower.tail1234.ts.net

4. Before installing Testerfy, enable HTTPS proxying:

   tailscale serve --bg --https 5247 http://localhost:5247
   tailscale serve status
   

5. Your Testerfy URL: https://HOSTNAME.TAILNET.ts.net:5247

6. Your redirect URI: https://HOSTNAME.TAILNET.ts.net:5247/api/auth/callback

Note: Tailscale Serve persists across reboots. To remove: tailscale serve --https=5247 off

Step 2: Create Spotify Developer App

1. Go to developer.spotify.com/dashboard
2. Click Create App
3. Fill in:
   • App name: Testerfy
   • App description: Personal music rating app
   • Redirect URI: your HTTPS callback from Step 1, e.g.:
     • https://testerfy.example.com/api/auth/callback, or
     • https://tower.tail1234.ts.net:5247/api/auth/callback (Tailscale Serve)
   • APIs used: Check ✅ Web API
4. Check the terms box and click Save
5. Click Settings and copy:
   • Client ID (visible on settings page)
   • Client Secret (click "View client secret")

Step 3: Generate a Session Secret

openssl rand -hex 32

Copy the output — you'll need it in Step 4.

Step 4: Install Testerfy (Unraid)

1. Unraid → Apps → Search "Testerfy" → Install

2. Fill in the configuration:

   Field	Value
   Web UI Port	5247 (default)
   Data Path	/mnt/user/appdata/testerfy/data (default)
   Spotify Client ID	From Step 2
   Spotify Client Secret	From Step 2
   Spotify Redirect URI	Exact HTTPS callback from Step 1
   Session Secret	From Step 3

3. Click Apply

Advanced: If you also run Mellodex with the same Spotify Client ID, mount a shared path for rate-limit state (see the template's Spotify Shared Path fields).

Step 5: Connect to Spotify

1. Open your public HTTPS URL (from Step 1)
2. Click Connect to Spotify
3. Authorize the app
4. Start rating tracks! 🎵

Usage

1. Open Spotify on any device and start playing from a playlist
2. Open Testerfy in your browser
3. Rate tracks:
   • 👍 Like — saves to your liked playlists, skips to next
   • 👎 Dislike — removes from playlist, skips to next

Settings

• Liked Playlists — choose which playlists to save liked tracks to
• Playlist Guard — restrict Testerfy to specific playlists only (prevents accidental deletions from important playlists)

Troubleshooting

"Invalid redirect URI" or "Insecure redirect URI"

The redirect URI must match exactly in two places:

1. Your container's SPOTIFY_REDIRECT_URI environment variable
2. Your Spotify app settings at developer.spotify.com/dashboard

Check for:

• Typos
• Missing /api/auth/callback at the end
• http vs https (must be https for production)
• Wrong hostname, port, or domain

App not loading / Connection refused

1. Check container is running:

   docker ps | grep testerfy
   docker logs testerfy
   

2. If using Tailscale Serve, confirm it is running:

   tailscale serve status
   

   You should see :5247 proxying to localhost:5247

3. If using a reverse proxy, confirm it forwards to http://localhost:5247

4. Check port binding: Container should be on host port 5247

Port conflict

If you see "address already in use":

• Check what's using the port: ss -tlnp | grep 5247
• With Tailscale Serve, the container and Serve both use port 5247 on different layers — they should not conflict

HTTPS certificate errors

• Reverse proxy: confirm your certificate is valid for the hostname in SPOTIFY_REDIRECT_URI
• Tailscale Serve: enable HTTPS Certificates in Tailscale Admin → DNS and wait a minute for provisioning

Alternative HTTPS Methods

If you don't want to use Tailscale, you can use any method that provides HTTPS:

SWAG / Nginx Proxy Manager

1. Set up a subdomain proxy to http://localhost:5247
2. Use port 5247 (not 127.0.0.1:5247)
3. Redirect URI: https://testerfy.yourdomain.com/api/auth/callback

Cloudflare Tunnel

1. Create a tunnel pointing to http://localhost:5247
2. Use port 5247 (not 127.0.0.1:5247)
3. Redirect URI: https://testerfy.yourdomain.com/api/auth/callback

Docker (Non-Unraid)

docker run -d \
  --name testerfy \
  -p 5247:5247 \
  -v /path/to/data:/data \
  -e SPOTIFY_CLIENT_ID=your_client_id \
  -e SPOTIFY_CLIENT_SECRET=your_client_secret \
  -e SPOTIFY_REDIRECT_URI=https://your-domain/api/auth/callback \
  -e SESSION_SECRET=$(openssl rand -hex 32) \
  -e TZ=America/New_York \
  ghcr.io/ozmoetr/testerfy:latest

You'll need to set up HTTPS yourself (reverse proxy, Tailscale, etc.).

Tech Stack

• Frontend: React, TypeScript, Tailwind CSS, shadcn/ui
• Backend: Node.js, Express
• Database: SQLite
• Auth: Spotify OAuth 2.0

Support

• Issues: github.com/ozmoetr/testerfy/issues

License

MIT License