Vynl - Local Development Setup

Prerequisites

Docker and Docker Compose installed
Spotify Developer account (for playlist import)
Anthropic API key (for recommendations)

1. Configure Environment

Edit backend/.env and fill in your API keys:

SPOTIFY_CLIENT_ID=your-client-id
SPOTIFY_CLIENT_SECRET=your-client-secret
ANTHROPIC_API_KEY=your-api-key

Stripe keys are optional for local dev — billing will just not work without them.

2. Start Everything

docker compose up --build

This starts:

PostgreSQL on port 5432
Redis on port 6379
Backend API on http://localhost:8000
Frontend on http://localhost:5173

The backend runs Alembic migrations automatically on startup.

3. Open the App

Go to http://localhost:5173

Register with email/password
Or connect Spotify (must configure Spotify Developer App first)

4. Spotify Developer App Setup

Go to https://developer.spotify.com/dashboard
Create an app
Set redirect URI to: http://localhost:5173/auth/spotify/callback
Copy Client ID and Client Secret to backend/.env

Note: Spotify apps start in Development Mode (25 user limit). This is fine for testing.

5. Test the Flow

Register an account
Connect Spotify
Import a playlist
Go to Discover, select the playlist, click "Discover"
Save some recommendations

External Access for Testers

To let others test without deploying to a server, use a Cloudflare Tunnel (free).

Setup Cloudflare Tunnel

# Install cloudflared
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared

# Login (one time)
cloudflared tunnel login

# Create a tunnel
cloudflared tunnel create vynl-test

# Run the tunnel (points to your local frontend)
cloudflared tunnel --url http://localhost:5173 run vynl-test

This gives you a URL like https://vynl-test-xxxxx.cfargotunnel.com that anyone can access.

Or use the quick method (no account needed)

cloudflared tunnel --url http://localhost:5173

This creates a temporary public URL instantly. Share it with testers. It expires when you stop the command.

Important for external access

When using a tunnel, update backend/.env:

FRONTEND_URL=https://your-tunnel-url.cfargotunnel.com
SPOTIFY_REDIRECT_URI=https://your-tunnel-url.cfargotunnel.com/auth/spotify/callback

And add the tunnel URL as a redirect URI in your Spotify Developer App settings.

Then restart the backend:

docker compose restart backend

2.6 KiB Raw Blame History