local stack: env overrides for parallel E2E lanes (defaults unchanged) (#1222)

Lets several local stacks run on one machine for nomad-mobile's parallel
Maestro lanes (the spare MacBook Pro runner): \`LOCAL_STACK_PROJECT\`
(per-lane Firestore project on the shared emulator, so global
fake-config does not leak between lanes) and \`LOCAL_STACK_STATE_DIR\`,
plus \`LOCAL_STACK_KEEP_EMULATORS=1\` for \`down\`. Every default is
unchanged, so existing local and CI runs behave exactly as before. Docs:
docs/TESTING.md § Local stack.

Context: nomadkaraoke/nomad-mobile#21 (E2E off Andrew's Mac).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

<!-- coderabbit-ai-generated:v1 -->

## Summary by CodeRabbit

* **New Features**
* Local development stacks can now use configurable state directories
and Firestore project IDs, making it easier to run isolated stacks side
by side.
* You can keep shared emulators running when stopping a stack, and
backend log locations reflect the selected state directory.
* **Documentation**
* Updated local setup guidance with recommendations for ports, projects,
state directories, and sharing emulators across stacks.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Andrew Beveridge ☄️andClaude Opus 5.5 authored and GitHub committed 2026-10-26 21:55:52 +00:00
1 parent fe89795aec
commit 1715a07010
2 files changed
+19 -5

No files matched your search

+9
View File
@@ -321,6 +321,15 @@ Requirements: Docker (fake-gcs-server), Java 21 + the gcloud Firestore emulator,
ffmpeg, and the poetry env. The Playwright config starts the stack itself if it
isn't running (`scripts/local-stack.sh serve` + `next dev`).
**Several stacks on one machine** (the mobile app's parallel E2E lanes) share the
emulators. Give each its own `LOCAL_STACK_API_PORT` / `LOCAL_STACK_WEB_PORT`,
`LOCAL_STACK_PROJECT` (the Firestore project, default `test-project`; fake-config,
including the global search knobs, lives in Firestore per project),
`LOCAL_STACK_GCS_BUCKET` (default `test-bucket`; the test reset empties the bucket,
so each stack needs its own) and `LOCAL_STACK_STATE_DIR` (pids and logs, default `.local-stack`). Stop one with
`LOCAL_STACK_KEEP_EMULATORS=1 scripts/local-stack.sh down`, or the others lose
their emulators.
**What is faked, and where.** Each fake lives at one seam, guarded by
`fake_workers_enabled()`. That check is strict (`is True`), so a `MagicMock`
settings object in a unit test never turns it on.
+10 -5
View File
@@ -13,6 +13,11 @@
# scripts/local-stack.sh env print the backend env (for running uvicorn yourself)
#
# Ports (override via env): LOCAL_STACK_API_PORT (8010), LOCAL_STACK_WEB_PORT (3010).
# Several stacks on one machine (the mobile app's parallel E2E lanes) share the Firestore and GCS emulators but each
# needs its own ports, LOCAL_STACK_PROJECT (the Firestore project, default test-project: fake-config and data are
# per project, so one stack's global knobs don't leak into another), LOCAL_STACK_GCS_BUCKET (default test-bucket:
# the test reset empties the bucket, so each stack needs its own) and LOCAL_STACK_STATE_DIR (pids and logs,
# default .local-stack). `down` with LOCAL_STACK_KEEP_EMULATORS=1 leaves the shared emulators running.
# The backend binds 0.0.0.0 so the Android emulator (10.0.2.2) and iOS simulator
# can reach it; set LOCAL_STACK_API_URL to the address devices should use.
# See docs/TESTING.md § "Local stack".
@@ -21,7 +26,7 @@ set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
STATE_DIR="$PROJECT_ROOT/.local-stack"
STATE_DIR="${LOCAL_STACK_STATE_DIR:-$PROJECT_ROOT/.local-stack}"
mkdir -p "$STATE_DIR"
API_PORT="${LOCAL_STACK_API_PORT:-8010}"
@@ -36,8 +41,8 @@ FAKE_WORKERS=1
ENVIRONMENT=development
FIRESTORE_EMULATOR_HOST=127.0.0.1:8080
STORAGE_EMULATOR_HOST=http://127.0.0.1:4443
GOOGLE_CLOUD_PROJECT=test-project
GCS_BUCKET_NAME=test-bucket
GOOGLE_CLOUD_PROJECT=${LOCAL_STACK_PROJECT:-test-project}
GCS_BUCKET_NAME=${LOCAL_STACK_GCS_BUCKET:-test-bucket}
FIRESTORE_COLLECTION=jobs
ADMIN_TOKENS=$ADMIN_TOKEN
FRONTEND_URL=$WEB_URL
@@ -148,14 +153,14 @@ case "$cmd" in
down)
stop_pid frontend
stop_pid backend
"$SCRIPT_DIR/stop-emulators.sh" || true
[[ "${LOCAL_STACK_KEEP_EMULATORS:-}" == 1 ]] || "$SCRIPT_DIR/stop-emulators.sh" || true
;;
serve)
"$SCRIPT_DIR/start-emulators.sh"
export_backend_env
(cd "$PROJECT_ROOT" && poetry run python "$SCRIPT_DIR/seed-local-data.py")
cd "$PROJECT_ROOT"
echo "🌐 Backend on :$API_PORT (FAKE_WORKERS=1), logging to .local-stack/backend.log"
echo "🌐 Backend on :$API_PORT (FAKE_WORKERS=1), logging to $STATE_DIR/backend.log"
exec poetry run uvicorn backend.main:app --host 0.0.0.0 --port "$API_PORT" \
> "$STATE_DIR/backend.log" 2>&1
;;