One-Command Local Environment

Running the platform locally meant two Docker Compose stacks that must start in a strict order, a backend service that has to be built, tested, and migrated, and then a .NET BFF host and an Angular dev server for every app you want to work on. Done by hand it was slow, easy to misorder, and hardest on new teammates — and the failures rarely pointed at their cause. A port held by IIS, a service starting before service discovery was ready, an untrusted dev certificate, or a database behind on migrations all showed up as an unrelated error deep in a log.

I built a PowerShell toolkit, around a thousand lines in its main orchestrator, that runs the whole sequence as six numbered phases. It checks prerequisites up front and reports every problem at once with its fix; starts each Docker stack and waits on real readiness — the network exists, the gating containers are healthy, the ports answer — rather than on exit codes; builds and migrates the backend only when a selected app actually calls the local instance; and gives each app its own ports through a generated override file, so several apps run side by side without touching any repository's config.

The design rule was that the tool must be safe to trust and safe to re-run. It never switches git branches, only fast-forwards a clean working tree, never deletes database volumes, and leaves product repositories untouched except behind an explicit flag. Every launched service is health-checked after it starts, so a terminal tab that opened is never mistaken for a service that is up, and re-running the script stops the previous instance of an app cleanly instead of leaving orphaned processes holding ports.

When a step does fail, the script captures the phase, command, exit code, and last fifty lines of output into a single error file. An optional companion script hands that file to Claude Code with a structured prompt — error, root cause, ranked options, recommendation — choosing a model to match the kind of failure, and Claude is not allowed to change anything until I approve it.

• Reduced local setup of a multi-repo microservice environment to one command: two Docker Compose stacks, a backend service, and up to eight .NET BFF + Angular apps.
• Cut time to a running app from 30–60 minutes of manual steps — longer when an error was hard to diagnose — to about 10 minutes, most of it waiting on containers.
• Turned fourteen recurring, unobvious local-development failures into automated checks, self-healing steps, or fail-fast messages with the exact fix.
• Gated startup on real readiness — Docker network, container health, and TCP probes — instead of trusting compose exit codes.
• Detected IIS/http.sys port conflicts by resolving the process that owns each port, and assigned per-app ports through generated override files so multiple apps run at once.
• Applied pending EF Core migrations automatically and built the local backend only when a selected app depends on it, saving minutes per run.
• Made the tool idempotent and non-destructive: safe re-runs, per-app stop and swap, no branch switching, and no volume deletion.
• Added AI-assisted failure diagnosis via Claude Code, with structured error capture, model selection by error type, and human approval before any change.
• Kept it config-driven and portable: adding an app is one line, and launch steps are read from each app's own VS Code launch configuration.