Mapping microservice dependencies for local dev

When onboarding new engineers or provisioning isolated sandboxes, connection refused errors and silent DNS resolution failures are the primary blockers to productive development. This guide delivers a deterministic workflow for mapping microservice dependencies for local dev, enabling platform teams to auto-discover, validate, and containerize inter-service routing without environment drift. By standardizing practices around Developer Onboarding Architecture & Friction Mapping, engineering leaders can eliminate bootstrap friction and reduce time-to-first-commit across distributed teams.

Symptom/Error: Connection Refused and DNS Resolution Failures on Boot

When a local stack boots but services immediately fail to communicate, begin with rapid triage. Run the diagnostic triad to surface unhealthy containers, closed ports, and failing health endpoints:

docker compose ps -a | grep 'unhealthy' && nc -zv localhost 5432 6379 8080 && curl -s -o /dev/null -w '%{http_code}' http://localhost:8080/health

Expected failure signature:

  • nc returns Connection refused or timed out
  • curl outputs 000 or 502/503
  • docker compose ps flags containers as unhealthy or exited

Isolate the failing service and inspect connection timeouts:

docker logs <service> | grep -iE "timeout|refused|dns"

Cross-reference expected ports against actual exposed bindings:

docker inspect <container> | jq '.[0].NetworkSettings.Ports'

If Docker's embedded DNS resolver isn't propagating service names, validate resolution directly against the internal resolver:

dig @127.0.0.11 <service-name>

A SERVFAIL or empty ANSWER SECTION confirms network isolation or missing compose network declarations. Document initial bootstrap failures and map onboarding friction points using established Developer Onboarding Architecture & Friction Mapping methodologies to standardize environment validation across teams.

Prevention: Implement startup healthcheck probes with interval: 10s, timeout: 5s, and retries: 5 in your Compose definitions. This surfaces dependency gaps deterministically before the developer IDE attaches.

Root Cause: Hardcoded Endpoints and Missing Local Service Registry

Hardcoded localhost references, static IPs, and absent local service registries break container isolation. Audit the codebase for static endpoint leaks across primary runtimes:

grep -rn 'localhost\|127\.0\.0\.1' src/ --include='*.go' --include='*.py' --include='*.ts' && yq eval '.services[].depends_on' docker-compose.yml

Map implicit dependencies by parsing dependency manifests (package.json, go.mod, requirements.txt) against running containers. Generate a directed acyclic graph (DAG) of required upstream services via Dependency Tree Visualization to identify missing depends_on conditions and circular references. Verify that all services explicitly declare networks: [default] (or a custom bridge network) to prevent cross-project network isolation.

Prevention: Enforce service discovery via environment variable injection (SERVICE_HOST, SERVICE_PORT) and reject hardcoded URLs using static analysis rules in CI linting pipelines.

Step-by-Step Fix: Dynamic Dependency Injection and Compose Orchestration

Replace static routing with dynamic, environment-driven injection. Follow this deterministic sequence to guarantee reproducible local stacks:

  1. Template Generation: Create a base docker-compose.yml using placeholder variables for all dependency endpoints (e.g., ${DB_HOST}, ${CACHE_HOST}).
  2. Environment Mapping: Create a .env.local file at the project root:
DB_HOST=postgres
CACHE_HOST=redis
AUTH_HOST=auth-service
  1. Topology Validation: Interpolate and validate the configuration before boot:
docker compose config --services && envsubst < compose.template.yml > docker-compose.local.yml && docker compose -f docker-compose.local.yml up -d --wait
  1. Blocking Startup: The --wait flag halts execution until all defined healthcheck endpoints return HTTP 200.
  2. Route Verification: Confirm inter-service routing from within the container network:
docker exec -it <frontend> curl -v http://<backend>:<port>/ping

Rollback Procedure: If orchestration fails mid-boot or introduces network corruption, immediately tear down and prune dangling artifacts:

docker compose -f docker-compose.local.yml down --remove-orphans --volumes
docker network prune -f
docker volume prune -f

Prevention: Automate dependency resolution via a pre-commit hook that executes docker compose config --quiet and fails the commit on unresolved variable substitution or malformed YAML.

Prevention/Parity Check: Runtime Validation and Local Mock Fallbacks

Guarantee environment parity before merging feature branches. Execute the validation harness to confirm dependency health:

make validate-deps || (docker compose run --rm dep-check && curl -f http://localhost:${PORT}/health)

Deploy lightweight mock servers (e.g., mockoon, wiremock) for non-critical upstream dependencies that are expensive or unavailable locally. Run a parity validation script that diffs local docker compose ps output against production service registry manifests, flagging version drift or missing replicas. Configure fallback routing in local API gateways to return 200 OK with stubbed payloads when primary dependencies are intentionally offline. Document the expected startup sequence, required environment variables, and known mock endpoints in a LOCAL_DEV.md alongside the repository root.

Prevention: Integrate dependency tree validation into the CI pipeline. Block pull requests that introduce unregistered service calls, missing compose network declarations, or bypassed healthcheck configurations. This enforces strict parity between local development and production topology, ensuring Developer Onboarding & Local Environment Automation remains deterministic and frictionless.