From f799a12ed566f272bed00c7c0337281f1f570955 Mon Sep 17 00:00:00 2001
From: root <root@claude.deathstar-home.one>
Date: Mon, 30 Mar 2026 22:08:39 -0500
Subject: [PATCH] Add local dev setup guide and .env, fix defaults for local
 development

---
 LOCAL_SETUP.md             | 105 +++++++++++++++++++++++++++++++++++++
 backend/app/core/config.py |   4 +-
 2 files changed, 107 insertions(+), 2 deletions(-)
 create mode 100644 LOCAL_SETUP.md

diff --git a/LOCAL_SETUP.md b/LOCAL_SETUP.md
new file mode 100644
index 0000000..62ddef7
--- /dev/null
+++ b/LOCAL_SETUP.md
@@ -0,0 +1,105 @@
+# 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
+
+```bash
+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
+
+1. Go to https://developer.spotify.com/dashboard
+2. Create an app
+3. Set redirect URI to: `http://localhost:5173/auth/spotify/callback`
+4. 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
+
+1. Register an account
+2. Connect Spotify
+3. Import a playlist
+4. Go to Discover, select the playlist, click "Discover"
+5. Save some recommendations
+
+---
+
+## External Access for Testers
+
+To let others test without deploying to a server, use a **Cloudflare Tunnel** (free).
+
+### Setup Cloudflare Tunnel
+
+```bash
+# 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)
+
+```bash
+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:
+```bash
+docker compose restart backend
+```
diff --git a/backend/app/core/config.py b/backend/app/core/config.py
index e9df0a6..584b76a 100644
--- a/backend/app/core/config.py
+++ b/backend/app/core/config.py
@@ -17,7 +17,7 @@ class Settings(BaseSettings):
     # Spotify
     SPOTIFY_CLIENT_ID: str = ""
     SPOTIFY_CLIENT_SECRET: str = ""
-    SPOTIFY_REDIRECT_URI: str = "https://deepcutsai.com/auth/spotify/callback"
+    SPOTIFY_REDIRECT_URI: str = "http://localhost:5173/auth/spotify/callback"
 
     # Claude API
     ANTHROPIC_API_KEY: str = ""
@@ -29,7 +29,7 @@ class Settings(BaseSettings):
     STRIPE_WEBHOOK_SECRET: str = ""
 
     # Frontend
-    FRONTEND_URL: str = "https://deepcutsai.com"
+    FRONTEND_URL: str = "http://localhost:5173"
 
     # Rate limits (free tier)
     FREE_DAILY_RECOMMENDATIONS: int = 10