Simplify dev setup: one-command start with self-healing admin key

[simantak-dabhade]

Summary

• Eliminates the two-pass start. No more manually generating the Convex admin key, copy-pasting it into .env, and restarting. make dev handles everything in a single run.
• Self-healing admin key. Validates existing keys on every run — if volumes were wiped and the key is stale, it detects the mismatch and regenerates automatically.
• Shows all missing keys at once. Instead of failing on the first missing env var, prints every missing key with where to get it (URLs included).

What changed

File	Change
makefiles/Makefile	Two-phase Docker start, ensure-admin-key target, install-deps target, batch env validation with instructions, make clean clears admin key
.env.example	Reordered (required keys first), clearer comments, admin key marked as auto-generated
README.md	Removed manual key generation steps, added "How make dev Works" section with commands table and troubleshooting
CLAUDE.md	Simplified setup to 4 steps

How it works

make dev now runs in phases:

1. Validate env → install deps → start db + convex → wait for health
2. Generate or validate admin key → push Convex config + schema
3. Start remaining services (frontend, backend, mastra)

Test plan

• Fresh clone: cp .env.example .env, fill in keys, make dev → auto-generates admin key, starts everything
• Idempotent: run make dev again → detects valid key, skips generation
• Recovery: make clean then make dev → regenerates admin key from scratch
• Stale key: manually set a bad admin key, make dev → detects stale key, regenerates
• Missing keys: remove a key from .env, make dev → shows all missing keys with URLs
• No .env: delete .env, make dev → clear error with instructions

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 40e1b5a2-263a-4877-ad7c-c968b9096eab

📥 Commits

Reviewing files that changed from the base of the PR and between 1c5a096 and 8d47db9.

📒 Files selected for processing (1)

• makefiles/Makefile

🚧 Files skipped from review as they are similar to previous changes (1)

• makefiles/Makefile

---

📝 Walkthrough

Walkthrough

This PR modernizes local development setup: it reorganizes .env.example (groups required keys and marks CONVEX_SELF_HOSTED_ADMIN_KEY as auto-generated), updates CLAUDE.md and README.md to document that make dev now starts Docker, pushes Convex schema, and auto-generates the Convex admin key on first run, and reworks Makefile targets by adding install-deps and ensure-admin-key, making dev orchestrate env validation, dependency install, Convex readiness polling, conditional admin-key generation/persistence, convex config push, and final service startup. validate-dev-env now aggregates missing vars; clean clears the admin key from .env.

Sequence Diagram

sequenceDiagram
  participant User
  participant MakeDev as "make dev"
  participant Validate as "validate-dev-env"
  participant InstallDeps as "install-deps"
  participant Docker as "Docker Compose (core services)"
  participant Convex as "Convex service"
  participant EnsureKey as "ensure-admin-key"
  participant ConvexPush as "convex-push/convex-env"
  
  User->>MakeDev: run make dev
  MakeDev->>Validate: run validate-dev-env
  Validate->>User: report aggregated missing/placeholders
  MakeDev->>InstallDeps: run npm installs
  MakeDev->>Docker: start core services
  Docker->>Convex: wait /version readiness
  MakeDev->>EnsureKey: validate CONVEX_SELF_HOSTED_ADMIN_KEY
  EnsureKey->>Convex: query with current key
  alt key missing or invalid
    EnsureKey->>Convex: generate new admin key
    EnsureKey->>MakeDev: persist key into root .env
  end
  MakeDev->>ConvexPush: run convex-env and convex-push
  MakeDev->>Docker: start remaining services
  MakeDev->>User: stream logs

Loading

Possibly related PRs

• tinyfish-io/bigset#19: Modifies Makefile dev workflow and convex targets; related to changes around env/convex/ensure-admin-key orchestration.

Suggested reviewers

• manav-tf
• hwennnn
• pranavjana

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: eliminating the two-pass setup and introducing a one-command dev start with automatic admin key management.
Description check	✅ Passed	The description is directly related to the changeset, providing a clear summary of improvements, detailed change breakdown, workflow phases, and test plan.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch simplify-dev-setup

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@makefiles/Makefile`:
- Line 105: The Makefile uses a non-portable in-place sed invocation (sed -i '')
when updating CONVEX_SELF_HOSTED_ADMIN_KEY which fails on GNU sed; change the
replacement to a portable approach by using sed -i.bak
"s#^CONVEX_SELF_HOSTED_ADMIN_KEY=.*`#CONVEX_SELF_HOSTED_ADMIN_KEY`=$$generated#"
.env && rm -f .env.bak or implement an OS branch (detect via uname) to use sed
-i '' on macOS and sed -i on Linux; update both occurrences around the
CONVEX_SELF_HOSTED_ADMIN_KEY update to use the portable pattern or branching
logic so the Makefile works on both BSD/macOS and GNU/linux.
- Around line 32-39: The Makefile uses Bash-specific syntax (e.g., the check_env
function and validate-dev-env target using [[ ... ]]) but doesn't set the recipe
shell; either set SHELL := /bin/bash at the top of the Makefile to pin recipes
to Bash, or rewrite the Bashisms in the check_env function and all targets that
use [[ ... ]] (e.g., validate-dev-env and the checks at the occurrences you
noted) to POSIX-compatible constructs (use [ ... ] or test, parameter
expansions, and case) so the recipes run on /bin/sh; update references to the
check_env function name in those targets accordingly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3daaf980-fc2b-4e25-87b6-5d6bc1d915c2

📥 Commits

Reviewing files that changed from the base of the PR and between 49a7fa4 and 1c5a096.

⛔ Files ignored due to path filters (1)

• backend/package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (4)

• .env.example
• CLAUDE.md
• README.md
• makefiles/Makefile