Files
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

43 lines
1.6 KiB
Bash

# karaoke-gen backend environment — copy to .env and adjust.
#
# NOTE: scripts/run-backend-local.sh --with-emulators sets all the required
# variables itself; you only need a .env for optional API keys or overrides.
# None of the keys below are required to boot the backend locally.
# --- Core (defaults shown are what run-backend-local.sh uses in emulator mode) ---
# ENVIRONMENT=development
# GOOGLE_CLOUD_PROJECT=test-project
# GCS_BUCKET_NAME=test-bucket
# FIRESTORE_COLLECTION=test-jobs
# ADMIN_TOKENS=local-dev-token
# PORT=8000
# FRONTEND_URL=http://localhost:3000
# --- Emulators (set automatically by run-backend-local.sh --with-emulators) ---
# FIRESTORE_EMULATOR_HOST=127.0.0.1:8080
# STORAGE_EMULATOR_HOST=http://127.0.0.1:4443
# --- Audio separation (pick one; without either, jobs stall at separation) ---
# Local CPU/GPU separation via the audio-separator package. Models are
# downloaded into this directory on first use (~2GB). CPU works but is slow.
# MODEL_DIR=./models
# ...or point at a remote audio-separator API service:
# AUDIO_SEPARATOR_API_URL=
# --- Lyrics transcription ---
# The lyrics worker reads AUDIOSHAKE_API_TOKEN (not AUDIOSHAKE_API_KEY).
# Without it, transcription falls back to local Whisper if installed
# (poetry install --extras local-whisper).
# AUDIOSHAKE_API_TOKEN=
# --- Lyrics sources (optional; improves reference lyrics) ---
# GENIUS_API_KEY=
# SPOTIFY_COOKIE_SP_DC=
# --- Email (optional; without it, emails are logged to the console) ---
# POSTMARK_SERVER_TOKEN=
# --- Payments (optional; only needed to exercise payment endpoints) ---
# STRIPE_SECRET_KEY=
# STRIPE_WEBHOOK_SECRET=