Files
karaoke-gen/scripts/run-backend-local.sh
T
Andrew Beveridge ☄️andClaude Fable 5 70ea964ca9 feat(dev): full local backend for external contributors (no GCP creds needed) (#946)
## Summary

Motivated by external contributor Martín (netux) asking "is there an
easy way to run the full backend without GCS?" — he couldn't test PR
#895's backend changes locally. This PR makes the whole backend runnable
locally against emulators with **zero GCP credentials and zero paid API
keys**.

### What was broken for contributors
- Workers migrated to Cloud Run Jobs for prod robustness
(audio-download, audio-separation, lyrics-transcription, bulk-search)
silently bypassed the direct-HTTP dev mode → local jobs stalled at
PENDING forever
- Signed URL generation called `google.auth.default()` → crashed with no
credentials (review audio, downloads, theme previews, upload URLs)
- Magic-link login 503'd locally (console email provider counted as "not
configured")
- Fresh emulator had no default theme → every job create returned 422
- `docs/DEVELOPMENT.md` told people to `cp .env.example .env` but the
file didn't exist — and nothing loaded `.env` anyway
- `run-backend-local.sh` defaulted to the production GCP project

### Changes
- **worker_service**: CRJ-based workers run as local subprocesses
(`python -m backend.workers.X --job-id Y`, exact CRJ parity) when
`ENABLE_CLOUD_TASKS=false` **and** not `is_production()`
(regression-tested both ways)
- **storage_service**: signed URLs → plain fake-gcs-server URLs when
`STORAGE_EMULATOR_HOST` set (GET via JSON API download path; PUT via
unvalidated-signature path, enabled by `-public-host` on the emulator)
- **users route**: magic-link 503 only in production; dev prints the
link to the console
- **file_upload bugfix**: a theme with style params but no asset files
never got `style_params_gcs_path` written (empty-dict falsiness in `elif
theme_style_assets:`) — surfaced by the minimal seed theme, latent in
prod
- **scripts/seed-local-data.py** (new): creates bucket + default theme;
wired into `run-backend-local.sh --with-emulators`, which now uses
`test-project`
- **config**: `load_dotenv()` so `.env` actually works; new root
`.env.example`
- **CONTRIBUTING.md** (new): no-credentials quickstart; README +
DEVELOPMENT.md link to it

### Verified end-to-end locally (no GCP credentials)
Upload job → local audio separation (real models) → transcription →
screens → `awaiting_review`; review endpoints all working including
`/api/review/{job}/audio/vocals` (the PR #895 endpoint) and 302 →
emulator audio URLs. Magic-link login round-trip via console link.

### Tests
- 224 tests across affected files pass; full backend unit suite: 3969
passed
- `backend/tests/test_emulator_integration.py` has 8 pre-existing
failures that reproduce identically on unmodified `main` locally (broken
theme-service mock in that file) — unrelated to this PR
- New tests: dev-mode subprocess dispatch (audio + bulk-search),
prod-mode never-Popen guard, emulator URL generation (GET + PUT)

@coderabbitai ignore

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-27 06:48:00 +00:00

59 lines
2.0 KiB
Bash
Executable File

#!/bin/bash
# Run the backend locally for manual testing
# Usage: ./scripts/run-backend-local.sh [--with-emulators]
set -e
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
echo "🚀 Starting local backend server..."
# Set environment variables for local development
export GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT:-nomadkaraoke}"
export GCS_BUCKET_NAME="${GCS_BUCKET_NAME:-karaoke-gen-storage-nomadkaraoke}"
export FIRESTORE_COLLECTION="${FIRESTORE_COLLECTION:-jobs-dev}"
export ENVIRONMENT="development"
export ADMIN_TOKENS="${ADMIN_TOKENS:-local-dev-token}"
export PORT="${PORT:-8000}"
# If --with-emulators flag, start emulators first
if [[ "$1" == "--with-emulators" ]]; then
echo "📦 Starting GCP emulators..."
"$SCRIPT_DIR/start-emulators.sh"
export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"
export STORAGE_EMULATOR_HOST="http://127.0.0.1:4443"
export GOOGLE_CLOUD_PROJECT="test-project"
export GCS_BUCKET_NAME="test-bucket"
export FIRESTORE_COLLECTION="test-jobs"
export FRONTEND_URL="${FRONTEND_URL:-http://localhost:3000}"
# Create the bucket and seed a default theme (idempotent) so jobs can be created
poetry run python "$SCRIPT_DIR/seed-local-data.py"
echo "✅ Emulators running"
else
echo "⚠️ Running WITHOUT emulators: this targets the real GCP project"
echo " ($GOOGLE_CLOUD_PROJECT) and requires GCP credentials."
echo " External contributors should use: $0 --with-emulators"
fi
# Change to project root
cd "$PROJECT_ROOT"
# Run the backend with uvicorn
echo ""
echo "🌐 Backend starting at http://localhost:$PORT"
echo "📋 API docs at http://localhost:$PORT/docs"
echo ""
echo "Test endpoints:"
echo " curl http://localhost:$PORT/api/health"
echo " curl -X POST http://localhost:$PORT/api/jobs -H 'Content-Type: application/json' -d '{\"url\": \"https://youtube.com/watch?v=...\"}'"
echo ""
echo "Press Ctrl+C to stop"
echo ""
poetry run uvicorn backend.main:app --host 0.0.0.0 --port "$PORT" --reload