docs(deployment): align deployment specs to two-path model (compose + gitops) - #1426
Merged
cyberantonz merged 2 commits intoJun 22, 2026
Merged
Conversation
… gitops) Retire the legacy dev-up.sh Kubernetes-on-Kind developer path from the docs and realign to the two officially-supported paths: - Docker Compose (`./dev-compose.sh up`) for day-to-day laptop dev - Kubernetes via gitops (`cd deploy/gitops && make deploy ENV=<env>`, locally `ENV=local`) for Airbyte/Argo work and the real cluster shape The umbrella chart's consumers become gitops (production + local) and external Helm consumers; the `<svc>.deploy: true` fat install is reattributed to external single-namespace consumers. The Docker Compose stack does not consume the chart. Touches README, CONTRIBUTING-aligned canon, the deployment PRD/DESIGN (full rewrite of the dev-wrapper requirements, actors, C4 diagrams, sequences — traceability IDs preserved), the gitops SPEC, and the ingestion/identity/connector/bronze-to-api domain docs. The helmfile EXPERIMENTAL block and the install.sh installer narrative are removed. dev-up.sh mentions in ADRs are left as historical record. Part of constructorfabric#1414. Closes constructorfabric#1416. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Anton Zelenov <antonz@constructor.tech>
📝 WalkthroughWalkthroughDocumentation across the repository is updated to replace the legacy ChangesDocumentation migration:
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
ktursunov
approved these changes
Jun 22, 2026
cyberantonz
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/domain/ingestion/specs/DESIGN.md (1)
751-757: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick winInconsistent working directory context in the setup steps.
Lines 753 and 755 mix two different command patterns: line 753 uses
./src/ingestion/run-init.sh(assuming repo root), while line 755 usescd src/ingestion && ./sync-all.sh(explicitcd). For clarity, both should follow the same style.♻️ Proposed fix for consistency
**First-time setup**: 1. Copy connector secret examples → fill credentials (`src/ingestion/secrets/connectors/`) 2. `cd deploy/gitops && make deploy ENV=local` — full stack deployment (answer the wizard prompts on first run) -3. `./src/ingestion/run-init.sh` — databases, connectors, connections +3. `cd src/ingestion && ./run-init.sh` — databases, connectors, connections 4. `cd src/ingestion && ./sync-all.sh` — trigger first Airbyte sync for all connectionsAlternatively, use the full path style from repo root for both:
**First-time setup**: 1. Copy connector secret examples → fill credentials (`src/ingestion/secrets/connectors/`) 2. `cd deploy/gitops && make deploy ENV=local` — full stack deployment (answer the wizard prompts on first run) 3. `./src/ingestion/run-init.sh` — databases, connectors, connections -4. `cd src/ingestion && ./sync-all.sh` — trigger first Airbyte sync for all connections +4. `./src/ingestion/sync-all.sh` — trigger first Airbyte sync for all connections🤖 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 `@docs/domain/ingestion/specs/DESIGN.md` around lines 751 - 757, The setup instructions use inconsistent working directory patterns between line 753 and line 755. Line 753 uses a relative path from repo root (./src/ingestion/run-init.sh), while line 755 uses an explicit directory change (cd src/ingestion && ./sync-all.sh). Update the sync-all.sh command on line 755 to match the style of run-init.sh by using the full relative path from repo root (./src/ingestion/sync-all.sh) instead of the cd pattern, ensuring both commands follow the same consistent style.
🤖 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.
Nitpick comments:
In `@docs/domain/ingestion/specs/DESIGN.md`:
- Around line 751-757: The setup instructions use inconsistent working directory
patterns between line 753 and line 755. Line 753 uses a relative path from repo
root (./src/ingestion/run-init.sh), while line 755 uses an explicit directory
change (cd src/ingestion && ./sync-all.sh). Update the sync-all.sh command on
line 755 to match the style of run-init.sh by using the full relative path from
repo root (./src/ingestion/sync-all.sh) instead of the cd pattern, ensuring both
commands follow the same consistent style.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 825b49c1-50aa-4f48-8cf4-30f7072144cf
📒 Files selected for processing (12)
README.mddocker-compose.ymldocs/components/backend/identity-resolution/identity/README.mddocs/components/deployment/gitops/README.mddocs/components/deployment/specs/DESIGN.mddocs/components/deployment/specs/PRD.mddocs/domain/bronze-to-api-e2e/specs/PRD.mddocs/domain/connector/specs/PRD.mddocs/domain/identity-resolution/specs/DESIGN.mddocs/domain/ingestion/README.mddocs/domain/ingestion/specs/DECOMPOSITION.mddocs/domain/ingestion/specs/DESIGN.md
8 tasks
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Phase 1 of the
dev-up.shretirement EPIC: realign the deployment docs to the two officially-supported paths, ahead of the code deletions in later phases../dev-compose.sh up) — day-to-day laptop dev. Does not ship Airbyte/Argo and does not consume the umbrella chart.cd deploy/gitops && make deploy ENV=<env>; locallyENV=localon Kind/OrbStack) — Airbyte/Argo work and the real cluster shape.The umbrella chart's consumers become gitops (production + local) and external Helm consumers. The
<svc>.deploy: truesingle-namespace fat install is reattributed fromdev-up.shto "external consumers who want one namespace."CONTRIBUTING.mdremains the canon.Files touched
README.md— Quick Start, root-scripts tree, services/ports, image config → two-path.docs/components/deployment/specs/PRD.md+DESIGN.md— full two-path rewrite: dev-wrapper requirements, actors, glossary, C4/ASCII/mermaid diagrams, sequences, use cases, acceptance criteria. Traceability IDs (cpt-insightspec-fr-dep-dev-wrapper,-dev-namespace-param,-dev-overlay-isolation,-component-dep-dev-wrapper,-interface-dep-dev-wrapper-env) are preserved; only their bodies changed. The helmfile EXPERIMENTAL block and thedeploy/scripts/install.shinstaller narrative are removed.docs/components/deployment/gitops/README.md— dual-purpose toggle table + namespace notes.docs/domain/{ingestion,identity-resolution}/specs/DESIGN.md,docs/domain/ingestion/README.md,docs/domain/ingestion/specs/DECOMPOSITION.md,docs/domain/connector/specs/PRD.md,docs/domain/bronze-to-api-e2e/specs/PRD.md,docs/components/backend/identity-resolution/identity/README.md—dev-up.sh/installer references swapped to the two-path canon (needed to satisfy the repo-wide acceptance grep).docker-compose.yml— header comment.Acceptance
grep -rn "dev-up\.sh|deploy/scripts/install|helmfile\.yaml" README.md CONTRIBUTING.md docs/returns only two hits, both indocs/components/airbyte-toolkit/specs/ADR/0014-*.md— intentional historical mentions in an ADR, which the issue's "Done when" clause explicitly permits.Scope notes / follow-ups
helmfile/charts/clickhousesubchart references are intentionally retained (they are removed in Phase 2, Phase 2 — Drop L2 subchart bundling from charts/insight (BREAKING — 0.2.0) #1417).docs/domain/ingestion/specs/DESIGN.md§4.1 still describes a single-namespace "Production" model that predates the gitops L2/L3 split. My §4.2 edit defers cluster topology to the gitops SPEC rather than re-architecting §4.1 inside adev-up.sh-retirement PR — worth a separate pass.Part of #1414.
Closes #1416.