Clean

README.md

@@ -141,14 +141,89 @@ Note: it's normal if page loading locally is much slower than the deployed versi
 
 ##### Full isolation
 
-`yarn dev` runs the app locally but uses the data from a shared remote database (Supabase) and authentication (
-Firebase).
-If you want to avoid any conflict / break or simply have it run faster, run the app in full isolation locally:
+Running `yarn dev:isolated` spins up a local Supabase and Firebase emulator instead of pointing at the shared remote
+database. This is strongly recommended for day-to-day development:
+
+- **Freedom** — Reset, wipe, and reseed your local database as many times as you want without affecting other
+  contributors.
+- **No conflicts** — Multiple contributors can work simultaneously without stepping on each other's data or schema.
+- **Works offline** — No internet required once services are started locally.
+- **Faster** — No network latency on every database query.
+
+However, running in full isolation requires installing several heavy dependencies:
+
+- **Docker** (~500MB) — runs the Supabase Postgres container
+- **Supabase CLI** — manages the local Supabase stack (10+ Docker containers, ~1-2GB RAM when running)
+- **Java 21+** (~300MB) — required by Firebase emulators
+- **Firebase CLI** — manages the local Firebase emulators
+
+First startup is slow (30-60s) and the stack uses significant memory. If your machine has less than 8GB RAM, you may
+notice slowdowns.
+
+If this feels like too much, you can skip isolation entirely — `yarn dev` works out of the box against the shared remote
+and is perfectly fine for most contributions, especially UI changes, wording fixes, or anything that doesn't touch the
+database or authentication.
+
+###### Setup instructions
+
+As always, don't hesitate to raise an issue if you run into any problems!
+
+Docker
+
+```bash
+# Ubuntu/Debian (native - recommended over snap)
+curl -fsSL https://get.docker.com | sudo sh
+sudo usermod -aG docker $USER
+# Log out and back in for group changes to take effect
+
+# macOS
+brew install --cask docker
+# Or download from https://www.docker.com/products/docker-desktop
+
+# Verify
+docker --version
+```
+
+Supabase CLI
+
+```bash
+npm install -g supabase
+
+# Verify
+supabase --version
+```
+
+Java 21+
+
+```bash
+# Ubuntu/Debian
+sudo apt install openjdk-21-jdk
+
+# macOS
+brew install openjdk@21
+
+# Verify (must be 21+)
+java -version
+```
+
+Firebase CLI
+
+```bash
+npm install -g firebase-tools
+
+# Verify
+firebase --version
+```
+
+Run in isolation
 
 ```bash
 yarn isolated
 ```
 
+Visit `http://localhost:3000` as usual. Your local database comes preloaded with synthetic test profiles so the app
+looks and feels like the real thing.
+
 ### Contributing
 
 Now you can start contributing by making changes and submitting pull requests!

package.json

@@ -14,8 +14,8 @@
     "verify": "yarn --cwd=common verify:dir; yarn --cwd=web verify:dir; yarn --cwd=backend/shared verify:dir",
     "lint": "yarn --cwd=web lint-fix; eslint common --fix ; eslint backend/api --fix ; eslint backend/shared --fix",
     "dev": "./scripts/run_local.sh dev",
+    "dev:isolated": "./scripts/run_local_isolated.sh",
     "prod": "./scripts/run_local.sh prod",
-    "isolated": "./scripts/run_local_isolated.sh",
     "clean-install": "./scripts/install.sh",
     "build-web-view": "./scripts/build_web_view.sh",
     "build-sync-android": "./scripts/build_sync_android.sh",

scripts/e2e-dev.sh

@@ -17,8 +17,7 @@ check_services() {
 
   if ! supabase status --output json | jq -r '.API_URL'; then
     print_error "Supabase is not running. Starting..."
-    supabase start
-    supabase db reset
+    yarn test:db:reset
     missing=1
   fi
 

scripts/e2e.sh

@@ -59,12 +59,8 @@ print_status "Killing any stale processes..."
 supabase stop --no-backup 2>/dev/null || true
 sleep 2  # Give ports time to free up
 
-# Start Supabase (includes Postgres, Auth, Storage, etc.)
-supabase start
-
-# Apply migrations (if using Supabase migrations)
-./scripts/combine-migrations.sh
-supabase db reset
+# Start Supabase (includes Postgres, Auth, Storage, etc.) and Apply migrations
+yarn test:db:reset
 
 # Get connection details
 export NEXT_PUBLIC_SUPABASE_URL=$(supabase status --output json | jq -r '.API_URL')

scripts/run_local_isolated.sh

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+cd "$(dirname "$0")"/..
+
 # Run the web app locally in full isolation (database, storage and authentication all stored locally)
 # What runs on each port?
 # - 4000: Firebase emulator UI
@@ -17,7 +19,7 @@
 
 # Clean ghost processes
 kill_ghosts() {
-  for p in 3000 4000 4400 4500 8088; do
+  for p in 3000 4000 4400 4500 8088 9099 9199; do
     pids=$(lsof -ti :$p 2>/dev/null)
     if [ -n "$pids" ]; then
       kill $pids || true
@@ -30,22 +32,35 @@ set -euo pipefail
 
 # Function to clean up background processes
 cleanup() {
-  echo "Stopping background processes..."
+  print_status "Cleaning up..."
+
+  # Stop Firebase emulators
+  ./scripts/firebase_stop.sh
+
+  # Kill all background processes
   for pid in "${PIDS[@]:-}"; do
     if kill -0 "$pid" 2>/dev/null; then
-      kill "$pid" || true
+      kill "$pid" 2>/dev/null || true
       wait "$pid" 2>/dev/null || true
-      echo "Killed PID $pid"
     fi
   done
+
   kill_ghosts
+
+  # Stop Docker containers
+  if [ "${SKIP_DB_CLEANUP:-}" != "true" ]; then
+    print_status "Stopping test database..."
+    docker compose -f scripts/docker-compose.test.yml down -v
+  fi
+
+  sleep 2
+
+  print_status "Cleanup complete"
 }
 
 # Trap EXIT, INT, TERM to run cleanup automatically
 trap cleanup EXIT INT TERM
 
-cd "$(dirname "$0")"/..
-
 export $(cat .env.test | grep -v '^#' | xargs)
 
 # Ensure Supabase local stack is running; if not, reset/start it