Skip to content

Add guided local setup workflow#152

Merged
aidankhogg merged 1 commit into
dev/alphafrom
codex/add-first-time-setup-workflow-for-netengine
Jun 29, 2026
Merged

Add guided local setup workflow#152
aidankhogg merged 1 commit into
dev/alphafrom
codex/add-first-time-setup-workflow-for-netengine

Conversation

@aidankhogg

Copy link
Copy Markdown
Contributor

Motivation

  • Provide a single-command, first-time guided setup that sequences host preflight checks, compose startup, Postgres health wait, migrations, spec-aware doctor checks, and then continues into the existing bootstrap flow to simplify and standardize local onboarding.
  • Surface actionable remediation for common blockers (subnet/port/Docker name/database) so users know how to fix failures before running netengine up.
  • Avoid requiring real infrastructure in CI by adding mocked tests for the orchestration path so the workflow can be validated without Docker/Postgres.

Description

  • Add a new CLI command netengine setup local SPEC_FILE and async handler _setup_local which orchestrates: pre-Postgres host checks, docker compose up -d postgres, waiting for Postgres health, running migrations, running spec-aware doctor checks, and then calling the existing _up path with migrations skipped. (netengine/cli/main.py)
  • Implement helper probe and orchestration utilities: _setup_host_probes, _run_setup_host_checks, _docker_compose_up, _wait_for_postgres_health, _required_setup_failed, and _print_setup_results, plus a LOCAL_SETUP_DB_URL fallback for common local setups. (netengine/cli/main.py)
  • Replace the long manual bootstrap command sequences in README.md, docs/alpha-quickstart.md, and docs/runbook.md with the new guided netengine setup local workflow and add remediation hints for common failures. (README.md, docs/alpha-quickstart.md, docs/runbook.md)
  • Add unit/CLI tests that mock Docker/DB/doctor calls and verify orchestration success and failure-stop behavior. (tests/test_cli.py, small test fix in tests/test_doctor.py)

Testing

  • Ran the new and related CLI unit tests with pytest tests/test_cli.py tests/test_readiness_cli.py tests/test_doctor.py -q and they passed (all targeted tests succeeded).
  • Verified the setup help output with python -m netengine.cli.main setup --help which produced the expected usage.
  • Ran the full test suite with pytest -q; the suite completed with the majority of tests passing but two existing integration tests failed (unrelated to the setup workflow): TestFullMVPLifecycle.test_full_mvp_lifecycle and TestHealthRoute.test_health_does_not_leak_last_error_detail, which remain outside the scope of this change.

Codex Task

@aidankhogg aidankhogg self-assigned this Jun 29, 2026
@aidankhogg aidankhogg added the enhancement New feature or request label Jun 29, 2026
@aidankhogg aidankhogg merged commit 41173e8 into dev/alpha Jun 29, 2026
@aidankhogg aidankhogg deleted the codex/add-first-time-setup-workflow-for-netengine branch June 29, 2026 22:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

codex enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant