Skip to content
AnglinAI Docs

Local Dev Env — Resume Notes (2026-06-10)

Pick-up-where-we-left-off doc. Companion to the snapshot in local-dev-status-2026-06-09.md and the comprehensive reference in local-dev.md.

TL;DR

  • Local stack works. ./scripts/setup-local.sh boots cleanly; 22 services healthy; SQS round-trip verified.
  • PR #1019 on branch fix/local-dev-env-bootstrap carries the fixes + status doc. Awaiting review / merge.
  • AWS deploy workflow also tightened (collapsed jobs, BuildKit GHA cache, scoped path filter). Cache benefit kicks in on the second post-merge deploy.

Where to start when you come back

1. Resume the PR

2. Verify the stack still boots

Terminal window
git checkout fix/local-dev-env-bootstrap   # or main if PR merged
docker compose --profile local up -d
./scripts/local-healthcheck.sh             # expect 17/2/0

If anything breaks at this point, treat as a fresh debug session — image tags drift fast (especially supabase/studio which republishes daily).

3. Tackle the highest-impact gap

Three known gaps, ranked by inner-loop payoff:

A. Round-trip a real PDF through the local API (highest payoff)

  • Currently we only proved SQS + sidecar wiring. Haven’t yet POSTed a PDF and watched it become an accessible HTML/PDF download.
  • Path: either (i) hit gotrue admin endpoint (/auth/v1/admin/users with service-role JWT) to create a test user, get a JWT, POST the file, poll, download; or (ii) generate a service-role JWT signed with the local super-secret-jwt-token-with-at-least-32-characters-long and bypass user auth.
  • Bake it into scripts/test-pipeline-local.sh so npm run test:local is one command.
  • The existing scripts/test-convert.sh is hardcoded to api.test.lan / supabase.test.lan (the broken staging server) — use it as a starting point, parameterize the host.

B. Fix batch-worker app_logs writer

  • Worker boot logs: SupabaseLogger not initialized: SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY missing.
  • Compose DOES set both vars on the batch-worker service (docker-compose.yml around lines 543-544). The worker code is reading different env var names than what compose exports.
  • Grep workers/batch/src for the SupabaseLogger init to find which names it expects, then either rename in compose or alias.
  • Once fixed, executor logs will reach the local app_logs table → the admin log viewer becomes useful locally.

C. Trivial polish

  • markitdown health probe in local-healthcheck.sh is wrong — container reports healthy but the script’s probe path returns 000. Find the right path and fix the script (or remove the check — markitdown is legacy).
  • setup-local.sh wait window for Supabase Auth is too short. It gives up before auth comes healthy, which leaves kong and studio in Created state until you re-run docker compose up -d. Extend the wait or make the script auto-retry.
  • Cosmetic warns in healthcheck (Supabase API 401, Studio 307) — both mean “service works” but the assertion in the script is wrong. Update the expected codes.

Environment quirk to investigate

git reflog shows the local shell is auto-running pull origin main and bouncing HEAD back to main every few seconds. This caused me to accidentally commit to main mid-session (commit 7aa2e3b5, reverted by 3cc483b5). Likely culprits:

  • A shell hook in .zshrc / .zprofile
  • An IDE auto-pull setting
  • A wrapper script around cd / git
  • A Claude Code hook in ~/.claude/settings.json

When you find it, either disable it on this repo or make it skip branches that don’t match main. Until then, double-check git branch --show-current before every commit in this repo.

Files changed in this session (all on PR #1019)

FileWhy
docker-compose.ymlImage tag bumps (Studio, Inbucket); LocalStack pin to 3.8.1 (last free CE); course-map-api → opt-in profile; batch-worker SQS URL → localstack hostname
infra/supabase/init-db.shWait for supabase_auth_admin before ALTER USER; create schema before table; tolerate INSERT failures
.github/workflows/deploy-aws.ymlMerged test+deploy jobs; Docker BuildKit GHA cache; tightened path filter to only Lambda-importing packages
docs/admin/local-dev-status-2026-06-09.mdStatus snapshot
docs/admin/local-dev-resume-2026-06-10.mdThis doc

Files NOT touched in this session

Pre-existing worktree state, left alone:

  • apps/vpat/src/components/ScoreDashboard.tsx (modified before session)
  • apps/course-map/CLAUDE.md (untracked)
  • apps/course-map/UTA-BSEE-Interactive-Degree-Plan.pdf (untracked)
  • apps/course-map/UTA-BSEE-Semester-Plan.pdf (untracked)
  • apps/course-map/UTResourceList-accessible (2).pdf (untracked)

Decide separately whether any of these should be committed.

Key paths reference

.github/workflows/deploy-aws.yml          # AWS deploy (now ~5min vs ~8min)
docker-compose.yml                        # 25+ service stack definition
infra/supabase/init-db.sh                 # migrate + role-password align
infra/localstack/init-aws.sh              # SQS/S3 bucket bootstrap
scripts/setup-local.sh                    # one-shot bootstrap
scripts/local-healthcheck.sh              # 17-check verification
scripts/seed-local.sh                     # seed data (not yet used)
scripts/test-convert.sh                   # e2e against staging (NEEDS LOCAL PORT)
workers/batch/src/sqs-consumer.ts         # message types + dispatch
workers/batch/src/log.ts                  # SupabaseLogger init (env mismatch)
.env.node-server                          # API + worker env (gitignored)
.env.local.example                        # template