feat(compose): improve local development workflow

[aleksdotbar]

Summary

• add generic --watch=<service> execution for Compose-managed Rust services, initially supporting analytics
• persist Cargo caches and skip release builds for watched services
• rename the local login identity setting to DEV_USER_EMAIL and remove obsolete frontend impersonation wiring
• support first-run --no-frontend setup and correct host-side ClickHouse probing
• recover invalid binary bind-mount paths before startup
• rebuild the fakeidp image through Docker cache to prevent stale token contracts

Validation

• bash -n dev-compose.sh deploy/compose/insight-init.sh
• docker compose config --quiet for the generated watch override
• cold analytics debug build and incremental source-triggered rebuild
• external ClickHouse SELECT 1 probe on host.docker.internal:8124 via host localhost
• host Vite BFF login through fakeidp using http://localhost:5173/auth/callback
• authenticated analytics requests against the configured external ClickHouse dataset

[coderabbitai]

📝 Walkthrough

Walkthrough

The compose development flow renames VITE_DEV_USER_EMAIL to DEV_USER_EMAIL, adds --no-frontend support, introduces optional cargo-watch Rust services, updates Rust build handling, and synchronizes compose, seeding, FakeIdP, Keycloak, and contributor documentation.

Changes

Compose development flow

Layer / File(s)	Summary
Local identity variable wiring .env.compose.example, deploy/seed/*, docker-compose.yml, src/backend/services/fakeidp/*, deploy/compose/keycloak/*, CONTRIBUTING.md	Renames the development identity variable to DEV_USER_EMAIL across configuration, seeding, authentication, and documentation.
Compose initialization and frontend selection deploy/compose/insight-init.sh, dev-compose.sh	Adds --no-frontend, validates its compose-only usage, updates ClickHouse probing, and writes the renamed identity variable.
Rust service watch runtime dev-compose.sh, deploy/compose/rust-watch.Dockerfile, docker-compose.yml	Adds --watch, cargo-watch image support, Rust cache volumes, watch overrides, service validation, and guarded binary installation.
Updated development guidance CONTRIBUTING.md, deploy/compose/keycloak/README.md	Documents the renamed identity variable and cargo-watch workflow constraints.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Developer
  participant dev-compose.sh
  participant insight-init.sh
  participant DockerCompose
  participant cargo-watch
  participant Analytics
  Developer->>dev-compose.sh: run compose development flow
  dev-compose.sh->>insight-init.sh: pass --no-frontend when requested
  insight-init.sh->>DockerCompose: generate compose environment
  Developer->>dev-compose.sh: run up --watch=analytics
  dev-compose.sh->>DockerCompose: generate analytics watch override
  DockerCompose->>cargo-watch: start watched Rust container
  cargo-watch->>Analytics: rebuild and restart service

Loading

Possibly related PRs

• constructorfabric/insight#1301: Updates the compose local-login identity environment variable documentation.
• constructorfabric/insight#1750: Modifies the .env.compose.example dev impersonation configuration.
• constructorfabric/insight#1821: Changes the compose development authentication identity flow.

Suggested reviewers: cyberantonz

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is broadly aligned with the PR, which improves the Compose-based local development workflow.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/dev-compose-watch-services

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

dev-compose.sh (1)

473-477: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Fail instead of launching Keycloak with an unreachable issuer.

When host-IP detection fails, this sets the issuer to localhost even though the adjacent warning confirms the authenticator cannot reach it. The stack starts, but all Keycloak login attempts fail. Return an error here and tell the developer to configure a reachable issuer.

Proposed fix

-    if [[ -z "$kc_ip" ]]; then
-      echo "WARN: no host IP detected — Keycloak issuer stays localhost (browser-only; the authenticator can't reach it)." >&2
-      kc_ip="localhost"
-    fi
+    if [[ -z "$kc_ip" ]]; then
+      echo "ERROR: no host IP detected; cannot configure a Keycloak issuer reachable by both browser and authenticator." >&2
+      return 1
+    fi

🤖 Prompt for 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.

In `@dev-compose.sh` around lines 473 - 477, Update the host-IP fallback in the
Keycloak startup flow around kc_ip and detect_host_ip to fail immediately when
no reachable host IP is detected, rather than assigning localhost. Emit an
actionable error directing the developer to configure a reachable issuer, and
prevent the stack from launching in this invalid state.

🤖 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.

Outside diff comments:
In `@dev-compose.sh`:
- Around line 473-477: Update the host-IP fallback in the Keycloak startup flow
around kc_ip and detect_host_ip to fail immediately when no reachable host IP is
detected, rather than assigning localhost. Emit an actionable error directing
the developer to configure a reachable issuer, and prevent the stack from
launching in this invalid state.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 04621be4-bd84-4a35-b7bf-409d7f97c734

📥 Commits

Reviewing files that changed from the base of the PR and between 4959e09 and 1548685.

📒 Files selected for processing (12)

• .env.compose.example
• CONTRIBUTING.md
• deploy/compose/insight-init.sh
• deploy/compose/keycloak/README.md
• deploy/compose/keycloak/gen-realm.py
• deploy/compose/rust-watch.Dockerfile
• deploy/seed/profiles.py
• dev-compose.sh
• docker-compose.yml
• src/backend/services/fakeidp/README.md
• src/backend/services/fakeidp/src/lib.rs
• src/backend/services/fakeidp/users.yaml