stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Repair scratch setup preflight for repo-local host processes

Browse Source
This commit is contained in:
master
2026-03-11 21:19:25 +02:00
parent 4a84f901ab
commit 08006100a5
7 changed files with 221 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/INSTALL_GUIDE.md
View File

@@ -55,7 +55,7 @@ The scripts will:
3. Copy `env/stellaops.env.example` to `.env` if needed (works out of the box)
4. Start infrastructure and wait for healthy containers
5. Create or reuse the external frontdoor Docker network from `.env` (`FRONTDOOR_NETWORK`, default `stellaops_frontdoor`)
6. Build repo-owned .NET solutions, then publish backend services locally into small Docker contexts before building hardened runtime images (vendored dependency trees such as `node_modules` are excluded)
6. Stop repo-local host-run Stella services that would lock build outputs, then build repo-owned .NET solutions and publish backend services locally into small Docker contexts before building hardened runtime images (vendored dependency trees such as `node_modules` are excluded)
7. Launch the full platform with health checks
Open **https://stella-ops.local** when setup completes.

5
docs/dev/DEV_ENVIRONMENT_SETUP.md
View File

@@ -29,7 +29,7 @@ Setup scripts validate prerequisites, build solutions and Docker images, and lau
./scripts/setup.sh --images-only # only build Docker images
```
The scripts will check for required tools (dotnet 10.x, node 20+, npm 10+, docker, git), warn about missing hosts file entries, and copy `.env` from the example if needed. See the manual steps below for details on each stage.
The scripts will check for required tools (dotnet 10.x, node 20+, npm 10+, docker, git), warn about missing hosts file entries, copy `.env` from the example if needed, and stop repo-local host-run Stella services before the solution build so scratch bootstraps do not fail on locked `bin/Debug` outputs. See the manual steps below for details on each stage.
On Windows and Linux, the backend image builder now publishes each selected .NET service locally and builds the hardened runtime image from a small temporary context. That avoids repeatedly streaming the whole monorepo into Docker during scratch setup.
@@ -195,6 +195,9 @@ dotnet test src\Scanner\StellaOps.Scanner.sln
# Windows (PowerShell 7)
.\scripts\build-all-solutions.ps1
# Stop repo-local host-run Stella services first if a prior debug session left binaries locked
.\scripts\build-all-solutions.ps1 -StopRepoHostProcesses
# With tests
.\scripts\build-all-solutions.ps1 -Test

71
docs/implplan/SPRINT_20260311_010_Platform_scratch_setup_revalidation.md Normal file
View File

@@ -0,0 +1,71 @@
# Sprint 20260311_010 - Platform Scratch Setup Revalidation
## Topic & Scope
- Validate the documented Stella Ops scratch setup path against a fully wiped local Docker state.
- Remove Stella-only containers, images, volumes, and networks, then rerun the repo setup path as a first-time operator would.
- If bootstrap defects surface, triage root cause and fix them cleanly before declaring the setup path healthy.
- Working directory: `.`.
- Expected evidence: scoped Docker wipe, setup-script execution evidence, root-cause notes for any bootstrap failures, and a local commit if code/docs change.
## Dependencies & Concurrency
- Depends on no other agent actively using the local Stella Docker stack.
- Safe parallelism: none during the wipe/rebuild itself because the environment reset is global.
## Documentation Prerequisites
- `AGENTS.md`
- `docs/dev/DEV_ENVIRONMENT_SETUP.md`
- `docs/INSTALL_GUIDE.md`
- `docs/implplan/SPRINT_20260309_001_Platform_scratch_setup_bootstrap_restore.md`
## Delivery Tracker
### PLATFORM-SCRATCH-001 - Wipe Stella Docker state only
Status: DONE
Dependency: none
Owners: QA, 3rd line support
Task description:
- Tear down the Stella compose stack and remove Stella-specific images, volumes, and networks without touching unrelated Docker assets on the machine.
Completion criteria:
- [x] Stella compose services are stopped.
- [x] Stella-specific images, volumes, and networks are removed.
### PLATFORM-SCRATCH-002 - Re-run documented setup from zero state
Status: DONE
Dependency: PLATFORM-SCRATCH-001
Owners: QA
Task description:
- Run the repo setup path from the documented entrypoint and capture the first blocking failure or a successful end-to-end bootstrap.
Completion criteria:
- [x] The documented setup command is executed from wiped state.
- [x] The first-run result is captured with concrete evidence.
### PLATFORM-SCRATCH-003 - Repair any bootstrap regression cleanly
Status: DONE
Dependency: PLATFORM-SCRATCH-002
Owners: Product Manager, Architect, Developer
Task description:
- If the scratch setup exposes a real bootstrap defect, fix the root cause in scripts/docs/code, then rerun the setup path until the documented flow converges again.
Completion criteria:
- [x] Any exposed setup regression has a root-cause fix.
- [x] Docs/sprint notes reflect the repaired bootstrap path.
- [x] The repair is committed locally if code/docs changed.
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-11 | Sprint created to revalidate the Stella scratch setup path after the latest runtime/action sweeps on the warm stack came back clean. | QA |
| 2026-03-11 | Completed a Stella-only Docker wipe and reran `scripts/setup.ps1` from zero state. The first real blocker was not Docker or compose; three leaked repo-local `StellaOps.Graph.Api.exe` processes from earlier host debugging locked `src/Graph/StellaOps.Graph.Api/bin/Debug/net10.0/*` and caused the Graph solution build to fail inside the documented setup path. | QA |
| 2026-03-11 | Root cause classified as a bootstrap-preflight gap, not a Graph runtime defect: the documented setup/build path did nothing to clear repo-local host-run Stella services before rebuilding all module solutions. Added repo-scoped host-process cleanup to the setup/build preflight and aligned the bash path with the same behavior. | Developer |
| 2026-03-11 | Revalidated the repaired bootstrap path on the rebuilt local stack and continued the live route/action sweeps from that clean baseline; the setup contract now converges without manual PID cleanup. | QA |
## Decisions & Risks
- Decision: keep the wipe scoped to Stella-labeled compose resources and `stellaops/*` images so unrelated local Docker work is not disturbed.
- Risk: scratch rebuilds are long-running by nature; if a bootstrap failure appears, capture the first blocker and fix it before attempting to optimize further.
- Decision: scratch setup now stops only repo-local host-run Stella processes before the solution build, because lingering debug services invalidate the documented bootstrap contract but should not require the operator to hunt PIDs manually.
- Risk: forcibly terminating repo-local host services during setup would be surprising if applied to arbitrary processes, so the cleanup is scoped to commands or executables rooted under this repository and containing `StellaOps.`.
## Next Checkpoints
- Archived by the follow-on local commit once the scoped setup repair is recorded.