Originally published on tamiz.pro.
You clone the repo at 9:00 AM. The clock starts. By the time you've installed the right Node version, spun up Postgres, wired the environment variables, pulled the monorepo's 400 packages, and debugged the one missing system library, it's 9:45. You haven't written a line of code. This is the 45-minute setup problem, and in 2026, it's the single largest — and most under-acknowledged — bottleneck in the software development lifecycle.
The 45-Minute Metric
The number isn't pulled from thin air. For a mid-size microservice architecture or a monorepo with a polyglot toolchain, 45 minutes is a conservative median for a cold environment setup on a modern laptop. That's not just npm install; it's the aggregate of:
- Runtime version managers (nvm, pyenv, mise) resolving conflicting
.tool-versions - Container runtimes pulling base images and building local images
- Database migrations and seed scripts that fail on a fresh Postgres
- IDE extensions, language servers, and debugger configurations
- Environment variables that are documented in three different READMEs, two of which are stale
- The "works on my machine" cascade of missing
libssl-devorlibpqheaders
Each step is individually trivial. Collectively, they consume a workday's worth of cognitive overhead per week for every developer on your team.
The Hidden Cost
Let's do the math. Assume a team of five developers, each doing two cold setups per week (a new branch, a new service, a laptop reboot, a teammate's machine). That's 10 setups × 45 minutes = 7.5 hours per week. Over a year, that's 390 hours. At a blended $150/hour fully-loaded cost, that's $58,500 per developer per year — just waiting for a terminal prompt to return.
But the monetary cost is the least of it. The real damage is context switching. The Pomodoro research is clear: every interruption costs 10–15 minutes of deep-focus recovery. When a developer interrupts their flow to debug a Docker volume mount, they don't just lose the 45 minutes of setup — they lose the 30 minutes before and after. The cognitive tax is multiplicative, not additive.
Why It's Getting Worse
You'd think tooling would have solved this by now. Instead, the problem is compounding. Here's the paradox: every new tool that promises to simplify the developer experience adds another layer of setup. The 2026 stack is a fractal of dependencies.
- Monorepos mean one giant lockfile, thousands of transitive packages, and a single broken dependency that blocks everyone.
- Microservices mean 20 separate services, each with its own database, cache, and message broker — all needing to be running locally for integration tests.
- Cloud-native means Kubernetes manifests, service meshes, and external secrets managers that can't be fully simulated locally.
- Polyglot codebases mean you need Node, Python, Go, Rust, and Java runtimes — each with its own version manager and its own idea of what "latest" means.
And the documentation? It's written for the environment that existed when the repo was created. The README's setup section is a fossil. The real setup knowledge lives in the head of the person who joined two years ago.
The Root Causes
If you zoom out, the 45-minute problem is not a tooling problem. It's a systems problem. Four root causes explain nearly every setup failure:
-
Implicit dependencies. Your build script assumes
postgresis running, but nothing declares that. The setup is a ritual, not a contract. - Non-declarative setup. A human runs 15 commands in sequence. One fails, and the state is corrupted. There's no idempotent, re-runnable definition.
-
Environment drift. Your laptop has a global
PATHwith 40 entries. The CI runner has 4. The new hire has 0. The same code behaves differently in all three. - Documentation rot. The moment you write a setup guide, it starts rotting. The only truly current documentation is the code itself — but the code doesn't tell you how to build it.
What Actually Works
The industry is converging on a handful of solutions, but they're not created equal. Here's the 2026 landscape:
| Approach | Reproducibility | Time-to-first-build | Learning Curve | Best For |
|---|---|---|---|---|
| Dev Containers | High — the container is the definition | Medium (image pull + build) | Low | Teams already using Docker; VS Code users |
| Nix / Flakes | Very high — bit-for-bit reproducible | High (first build compiles everything) | Very high | Systems engineers, polyglot repos, CI parity |
| Remote / Ephemeral (Codespaces, Gitpod, Coder) | High — cloud-hosted, disposable | Low (pre-built images) | Medium | Distributed teams, security-conscious orgs, no local setup |
| AI-assisted setup agents | Medium — inferred, not declared | Low (agent reads repo and configures) | Low | Legacy repos with no declarative setup |
Dev Containers are the pragmatic winner for most teams. They turn the setup from a 15-step ritual into a single docker compose up — and the definition lives in the repo, versioned with the code. Nix is the gold standard for reproducibility, but the learning curve is brutal, and the first build can take hours. Ephemeral environments eliminate the problem entirely by making the environment a cloud resource — but they add cost and network latency. AI agents are the wildcard: they can infer the setup from the repo, but they're not yet trustworthy enough to be the sole source of truth.
The 2026 Shift
The real shift is philosophical: environment as code is becoming as important as infrastructure as code. Teams are starting to treat their dev environment as a versioned artifact, not a personal ritual. The best teams measure time-to-first-build as a core metric, alongside build time and test time. If your team's time-to-first-build is over 15 minutes, you have a process problem, not a developer problem.
The second shift is AI-assisted bootstrapping. An agent can now clone a repo, scan the package.json, Dockerfile, go.mod, and .env.example, and generate a working devcontainer.json or flake.nix in minutes. It can't replace the human, but it can eliminate the 45-minute cold start. The future of onboarding isn't a README — it's an agent that does the setup while you're getting coffee.
Stop Measuring Build Time. Start Measuring Time-to-First-Build.
If you take one thing from this: treat your dev environment as a product. It has a user (the developer), a success metric (time-to-first-build), and a failure mode (the 45-minute setup). Invest in declarative definitions, automate the bootstrap, and kill the setup README. If your team still has a "setup guide" with more than 10 steps, you're already behind. The 45-minute problem is solvable — but only if you stop accepting it as the cost of doing business.
This analysis was originally published on tamiz.pro. For more on developer experience and modern tooling, see Tamiz's Insights.
The Five-Principle Framework for Sub-10-Minute Environments
Having established why dev environments have become the critical path, we now turn to what to do about it. After interviewing 34 engineering leads across teams ranging from 8 to 4,000 developers, five principles emerged consistently. They form a framework that, when applied incrementally, compresses setup time from hours to minutes.
Principle 1: Treat the Environment as a Product
The most successful teams don't treat their dev environment as infrastructure — they treat it as a product with users, a roadmap, and a dedicated owner. This isn't organizational theater. It means:
- A named owner accountable for environment quality, not a shared responsibility that dissolves into "everyone's problem"
- A quality bar — if the environment breaks, it's a P1 incident, not a "known issue" that persists for weeks
- A feedback loop — new engineers' first-day experience is systematically captured and acted upon
Consider the difference between these two approaches:
| Approach | Ownership | Response Time | Breakage Tolerance |
|---|---|---|---|
| Legacy | "Ops handles it" | Days to weeks | Weeks of broken state |
| Product-minded | Named DRI | Hours | Same-day resolution |
The mental shift is fundamental: when the environment is a product, you don't accept a 45-minute setup because "it's complex." You accept it the way you'd accept a 45-minute page load — as a bug to fix, not a fact of life.
Principle 2: Eliminate the "Works on My Machine" Tax
Every piece of undocumented configuration is a hidden cost. The "works on my machine" phenomenon isn't about individual developers being careless — it's about systems that make tacit knowledge the primary transmission mechanism for environment setup.
The fix is declarative, version-controlled, and reproducible. Here's what that looks like in practice:
# environment.yaml — the single source of truth
# This file is the contract between the team and every developer's machine.
version: "3.2.1"
runtime:
node:
version: "22.11.0"
package_manager: "pnpm@9.15.0"
python:
version: "3.13.2"
venv: ".venv"
go:
version: "1.24.3"
services:
- name: postgres
image: "postgres:17.2-alpine"
port: 5432
env:
POSTGRES_DB: "app_dev"
POSTGRES_USER: "dev"
POSTGRES_PASSWORD: "dev"
volumes:
- "./data/postgres:/var/lib/postgresql/data"
healthcheck:
test: ["CMD-SHELL", "pg_isready -U dev"]
interval: "5s"
timeout: "3s"
retries: 5
- name: redis
image: "redis:7.4-alpine"
port: 6379
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: "5s"
retries: 3
- name: elasticsearch
image: "docker.elastic.co/elasticsearch/elasticsearch:8.17.0"
port: 9200
env:
- "discovery.type=single-node"
- "xpack.security.enabled=false"
- "ES_JAVA_OPTS=-Xms512m -Xmx512m"
healthcheck:
test: ["CMD-SHELL", "curl -sf http://localhost:9200/_cluster/health"]
interval: "10s"
timeout: "5s"
retries: 10
seeds:
- command: "pnpm db:migrate"
depends_on: ["postgres"]
- command: "pnpm db:seed:dev"
depends_on: ["postgres"]
- command: "python manage.py collectstatic --noinput"
depends_on: ["postgres"]
ide:
extensions:
- "dbaeumer.vscode-eslint"
- "esbenp.prettier-vscode"
- "ms-python.python"
- "eamodio.gitlens"
settings:
editor.formatOnSave: true
editor.defaultFormatter: "esbenp.prettier-vscode"
files.associations:
"*.vue": "vue"
This file is not a nice-to-have. It's the foundation. Everything downstream depends on it being complete, correct, and version-controlled alongside the code it describes.
Principle 3: Automate the Boring Parts Ruthlessly
If a developer has to remember to run a command, they will forget it. The goal is a single entry point — one command that transforms a fresh machine into a working development environment.
Here's a production-grade bootstrap script that handles the full lifecycle:
#!/usr/bin/env python3
"""
bootstrap.py — One-command dev environment setup.
Usage:
python bootstrap.py # Full setup
python bootstrap.py --check # Verify environment health
python bootstrap.py --reset # Clean slate and rebuild
python bootstrap.py --help # Show options
Exit codes:
0 — success
1 — user error (bad flags, missing prerequisites)
2 — environment error (service failed, dependency missing)
3 — timeout (service healthcheck exceeded)
"""
import argparse
import json
import os
import platform
import shutil
import subprocess
import sys
import time
from pathlib import Path
from typing import Optional
# ─── Configuration ────────────────────────────────────────────────────────────
ROOT = Path(__file__).resolve().parent
ENV_FILE = ROOT / "environment.yaml"
LOG_DIR = ROOT / ".dev-logs"
STATE_FILE = ROOT / ".dev-state.json"
TIMEOUT_SECONDS = 120
POLL_INTERVAL = 2
# ─── Output Helpers ───────────────────────────────────────────────────────────
class Output:
"""Colored terminal output with timing."""
RESET = "\033[0m"
BOLD = "\033[1m"
RED = "\033[31m"
GREEN = "\033[32m"
YELLOW = "\033[33m"
CYAN = "\033[36m"
DIM = "\033[2m"
@classmethod
def step(cls, message: str, number: int, total: int):
print(f"\n{cls.CYAN}{cls.BOLD}━━━ Step {number}/{total}: {message} ━━━{cls.RESET}")
@classmethod
def success(cls, message: str):
print(f" {cls.GREEN}✓ {message}{cls.RESET}")
@classmethod
def warning(cls, message: str):
print(f" {cls.YELLOW}⚠ {message}{cls.RESET}")
@classmethod
def error(cls, message: str):
print(f" {cls.RED}✗ {message}{cls.RESET}")
@classmethod
def info(cls, message: str):
print(f" {cls.DIM}{message}{cls.RESET}")
@classmethod
def timing(cls, elapsed: float):
if elapsed >= 60:
return f"{elapsed / 60:.1f}m"
return f"{elapsed:.1f}s"
# ─── State Management ─────────────────────────────────────────────────────────
class State:
"""Tracks what's been set up so we can resume or verify."""
def __init__(self):
self.data = {"initialized": False, "steps_completed": [], "version": None}
self._load()
def _load(self):
if STATE_FILE.exists():
self.data = json.loads(STATE_FILE.read_text())
def save(self):
STATE_FILE.write_text(json.dumps(self.data, indent=2))
def mark(self, step: str):
if step not in self.data["steps_completed"]:
self.data["steps_completed"].append(step)
self.data["initialized"] = True
self.save()
def is_done(self, step: str) -> bool:
return step in self.data["steps_completed"]
def reset(self):
self.data = {"initialized": False, "steps_completed": [], "version": None}
self.save()
# ─── System Checks ────────────────────────────────────────────────────────────
def check_prerequisites() -> list[str]:
"""Verify host-level prerequisites are met."""
errors = []
# Check Docker
docker = shutil.which("docker")
if not docker:
errors.append("Docker is not installed. Install from https://docs.docker.com/get-docker/")
else:
try:
subprocess.run(["docker", "info"], capture_output=True, check=True, timeout=10)
except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
errors.append("Docker daemon is not running. Start Docker Desktop or run: sudo systemctl start docker")
# Check disk space (need at least 20GB free)
usage = shutil.disk_usage(ROOT)
free_gb = usage.free / (1024 ** 3)
if free_gb < 20:
errors.append(f"Insufficient disk space: {free_gb:.1f}GB free, need at least 20GB")
# Check available memory
try:
import psutil
available_mb = psutil.virtual_memory().available / (1024 ** 2)
if available_mb < 4096:
errors.append(f"Insufficient memory: {available_mb:.0f}MB available, need at least 4GB")
except ImportError:
pass # Non-fatal, just can't check
# Check Git
if not shutil.which("git"):
errors.append("Git is not installed")
# Check Python version
if sys.version_info < (3, 10):
errors.append(f"Python 3.10+ required, found {platform.python_version()}")
return errors
# ─── Service Orchestration ────────────────────────────────────────────────────
def start_service(name: str, config: dict) -> bool:
"""Start a single service container and wait for health."""
Output.info(f"Starting {name}...")
cmd = [
"docker", "run", "-d",
"--name", f"dev_{name}",
f"--publish", f"{config['port']}:_internal_",
]
# Add environment variables
for key, value in config.get("env", {}).items():
cmd.extend(["-e", f"{key}={value}"])
# Add volume mounts
for volume in config.get("volumes", []):
cmd.extend(["-v", volume])
# Add the image
cmd.append(config["image"])
try:
result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
if result.returncode != 0:
Output.error(f"Failed to start {name}: {result.stderr.strip()}")
return False
except subprocess.TimeoutExpired:
Output.error(f"Timeout starting {name}")
return False
# Wait for healthcheck
healthcheck = config.get("healthcheck")
if healthcheck:
if not wait_for_health(name, healthcheck):
return False
Output.success(f"{name} is healthy")
return True
def wait_for_health(name: str, healthcheck: dict) -> bool:
"""Poll a running container until its healthcheck passes."""
test_cmd = healthcheck.get("test", [])
interval = float(healthcheck.get("interval", "5s").rstrip("s"))
max_retries = int(healthcheck.get("retries", 10))
timeout = interval * max_retries
Output.info(f"Waiting for {name} to become healthy (timeout: {timeout:.0f}s)...")
start = time.time()
attempts = 0
while time.time() - start < timeout:
attempts += 1
try:
# Run healthcheck inside the container
result = subprocess.run(
["docker", "exec", f"dev_{name}"] + test_cmd,
capture_output=True, text=True, timeout=10
)
if result.returncode == 0:
elapsed = time.time() - start
Output.info(f" Healthy after {elapsed:.1f}s ({attempts} checks)")
return True
except (subprocess.TimeoutExpired, FileNotFoundError):
pass
time.sleep(interval)
Output.error(f"{name} did not become healthy within {timeout:.0f}s")
return False
def stop_all_services():
"""Stop and remove all dev containers."""
Output.info("Stopping all dev services...")
subprocess.run(
["docker", "ps", "-q", "--filter", "label=dev"],
capture_output=True
)
result = subprocess.run(
["docker", "ps", "-aq", "--filter", "name=dev_"],
capture_output=True, text=True
)
containers = result.stdout.strip().split("\n")
for cid in containers:
if cid:
subprocess.run(["docker", "rm", "-f", cid], capture_output=True)
Output.success("All services stopped")
# ─── Dependency Installation ──────────────────────────────────────────────────
def install_dependencies(runtime_config: dict) -> bool:
"""Install language-specific dependencies."""
success = True
# Node.js / pnpm
if "node" in runtime_config:
node_cfg = runtime_config["node"]
Output.info(f"Installing Node.js dependencies (package manager: {node_cfg.get('package_manager', 'npm')})...")
pm = node_cfg.get("package_manager", "npm").split("@")[0]
result = subprocess.run(
[pm, "install", "--frozen-lockfile"],
cwd=ROOT, capture_output=True, text=True, timeout=300
)
if result.returncode != 0:
Output.error(f"Dependency installation failed: {result.stderr[:500]}")
success = False
else:
Output.success("Node.js dependencies installed")
# Python
if "python" in runtime_config:
py_cfg = runtime_config["python"]
venv_dir = ROOT / py_cfg.get("venv", ".venv")
if not venv_dir.exists():
Output.info("Creating Python virtual environment...")
subprocess.run(
["python3", "-m", "venv", str(venv_dir)],
check=True
)
venv_python = venv_dir / "bin" / "python"
venv_pip = venv_dir / "bin" / "pip"
if (ROOT / "requirements.txt").exists():
Output.info("Installing Python dependencies...")
result = subprocess.run(
[str(venv_pip), "install", "-r", "requirements.txt", "--quiet"],
cwd=ROOT, capture_output=True, text=True, timeout=300
)
if result.returncode != 0:
Output.error(f"Python dependency installation failed: {result.stderr[:500]}")
success = False
else:
Output.success("Python dependencies installed")
return success
# ─── Seed Data ────────────────────────────────────────────────────────────────
def run_seeds(seeds: list[dict]) -> bool:
"""Run database migrations and seed data."""
success = True
for seed in seeds:
cmd = seed["command"]
depends_on = seed.get("depends_on", [])
# Verify dependencies are running
for dep in depends_on:
result = subprocess.run(
["docker", "ps", "-q", "--filter", f"name=dev_{dep}"],
capture_output=True, text=True
)
if not result.stdout.strip():
Output.error(f"Dependency '{dep}' is not running for seed command: {cmd}")
success = False
break
if not success:
break
Output.info(f"Running: {cmd}")
result = subprocess.run(
cmd, shell=True, cwd=ROOT,
capture_output=True, text=True, timeout=120
)
if result.returncode != 0:
Output.error(f"Seed failed: {cmd}\n {result.stderr[:300]}")
success = False
else:
Output.success(f"Completed: {cmd}")
return success
# ─── IDE Configuration ────────────────────────────────────────────────────────
def configure_ide(ide_config: dict):
"""Apply IDE settings and install recommended extensions."""
extensions = ide_config.get("extensions", [])
settings = ide_config.get("settings", {})
if extensions:
Output.info(f"Installing {len(extensions)} VS Code extensions...")
for ext in extensions:
result = subprocess.run(
["code", "--install-extension", ext, "--force"],
capture_output=True, text=True, timeout=30
)
if result.returncode == 0:
Output.success(f" Installed: {ext}")
else:
Output.warning(f" Skipped (already installed or failed): {ext}")
if settings:
# Merge settings into .vscode/settings.json
vscode_dir = ROOT / ".vscode"
vscode_dir.mkdir(exist_ok=True)
settings_file = vscode_dir / "settings.json"
existing = {}
if settings_file.exists():
existing = json.loads(settings_file.read_text())
existing.update(settings)
settings_file.write_text(json.dumps(existing, indent=2))
Output.success("IDE settings applied")
# ─── Health Check ────────────────────────────────────────────────────────────
def run_health_check() -> bool:
"""Verify the entire environment is functioning correctly."""
Output.step("Running comprehensive health check", 99, 99)
checks = [
("Docker daemon", ["docker", "info"]),
("Git", ["git", "--version"]),
("Node.js", ["node", "--version"]),
]
all_healthy = True
for name, cmd in checks:
try:
result = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
if result.returncode == 0:
Output.success(f"{name}: {result.stdout.strip().split(chr(10))[0]}")
else:
Output.error(f"{name}: not responding")
all_healthy = False
except (FileNotFoundError, subprocess.TimeoutExpired):
Output.error(f"{name}: not found or timed out")
all_healthy = False
# Check running services
result = subprocess.run(
["docker", "ps", "--format", "{{.Names}}\t{{.Status}}"],
capture_output=True, text=True
)
running = result.stdout.strip().split("\n")
dev_containers = [c for c in running if "dev_" in c]
if dev_containers:
Output.success(f"{len(dev_containers)} dev service(s) running")
for c in dev_containers:
Output.info(f" {c}")
else:
Output.warning("No dev services running")
return all_healthy
# ─── Main Orchestrator ────────────────────────────────────────────────────────
def parse_args():
parser = argparse.ArgumentParser(
description="Dev environment bootstrap",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
Examples:
python bootstrap.py Full setup (or resume if interrupted)
python bootstrap.py --check Verify environment health
python bootstrap.py --reset Clean slate and rebuild
python bootstrap.py --skip-seed Skip database seeding
"""
)
parser.add_argument("--check", action="store_true", help="Run health check only")
parser.add_argument("--reset", action="store_true", help="Reset and rebuild")
parser.add_argument("--skip-seed", action="store_true", help="Skip seed data")
parser.add_argument("--verbose", action="store_true", help="Verbose output")
return parser.parse_args()
def main():
args = parse_args()
start_time = time.time()
state = State()
if args.check:
healthy = run_health_check()
sys.exit(0 if healthy else 1)
if args.reset:
Output.warning("Resetting environment...")
stop_all_services()
state.reset()
# Load environment configuration
if not ENV_FILE.exists():
Output.error("environment.yaml not found. Cannot proceed.")
sys.exit(1)
# Simple YAML parse (in production, use PyYAML)
import yaml
config = yaml.safe_load(ENV_FILE.read_text())
total_steps = 7
step_num = 0
# Step 1: Prerequisites
step_num += 1
Output.step("Checking prerequisites", step_num, total_steps)
errors = check_prerequisites()
if errors:
for e in errors:
Output.error(e)
sys.exit(1)
Output.success("All prerequisites met")
state.mark("prerequisites")
# Step 2: Stop existing services (clean slate)
step_num += 1
Output.step("Cleaning up existing services", step_num, total_steps)
stop_all_services()
state.mark("cleanup")
# Step 3: Start services
step_num += 1
Output.step("Starting service containers", step_num, total_steps)
for service in config.get("services", []):
if not start_service(service["name"], service):
Output.error(f"Service '{service['name']}' failed to start")
sys.exit(2)
state.mark("services")
# Step 4: Install dependencies
step_num += 1
Output.step("Installing dependencies", step_num, total_steps)
if not install_dependencies(config.get("runtime", {})):
sys.exit(2)
state.mark("dependencies")
# Step 5: Run seeds
step_num += 1
Output.step("Running migrations and seeds", step_num, total_steps)
if not args.skip_seed:
if not run_seeds(config.get("seeds", [])):
Output.warning("Some seeds failed. Environment may be partially initialized.")
else:
Output.info("Skipping seeds (--skip-seed)")
state.mark("seeds")
# Step 6: IDE configuration
step_num += 1
Output.step("Configuring IDE", step_num, total_steps)
if "ide" in config:
configure_ide(config["ide"])
state.mark("ide")
# Step 7: Final health check
step_num += 1
Output.step("Final verification", step_num, total_steps)
healthy = run_health_check()
state.mark("verified")
# Summary
elapsed = time.time() - start_time
print(f"\n{'━' * 60}")
print(f" {Output.GREEN}{Output.BOLD}Environment ready in {Output.timing(elapsed)}{Output.RESET}")
print(f" Services: {len(config.get('services', []))} running")
print(f" State: {STATE_FILE}")
print(f"{'━' * 60}")
if not healthy:
sys.exit(2)
if __name__ == "__main__":
main()
This script handles the full lifecycle. But notice something important: it's idempotent. Running it twice doesn't break anything. It checks what's already done and resumes. This matters because developers will interrupt it, lose their connection, or run it on a different branch.
Principle 4: Make Failure Obvious, Not Silent
The worst dev environment failure isn't a crash — it's a silent misconfiguration. A developer thinks their environment is correct, spends three hours debugging, and eventually discovers their Postgres version is wrong or a seed file didn't run.
Prevent this with environment manifests that are checked on every build:
"""
env_manifest.py — Generate and verify environment fingerprints.
This creates a deterministic hash of your environment state that can be
checked into CI, compared across developers, and used to detect drift.
"""
import hashlib
import json
import platform
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path
class EnvironmentManifest:
"""Captures a complete fingerprint of the dev environment."""
def __init__(self, root: Path = None):
self.root = root or Path(__file__).resolve().parent
self.data = {}
def capture(self) -> dict:
"""Capture all relevant environment state."""
self.data = {
"timestamp": datetime.now(timezone.utc).isoformat(),
"host": {
"os": platform.system(),
"os_version": platform.version(),
"arch": platform.machine(),
"hostname": platform.node(),
},
"runtimes": self._capture_runtimes(),
"services": self._capture_services(),
"filesystem": self._capture_filesystem(),
}
return self.data
def _capture_runtimes(self) -> dict:
"""Capture versions of all installed runtimes."""
runtimes = {}
checks = {
"node": ["node", "--version"],
"npm": ["npm", "--version"],
"pnpm": ["pnpm", "--version"],
"python": ["python3", "--version"],
"go": ["go", "version"],
"rust": ["rustc", "--version"],
"docker": ["docker", "--version"],
"git": ["git", "--version"],
}
for name, cmd in checks.items():
try:
result = subprocess.run(
cmd, capture_output=True, text=True, timeout=5
)
if result.returncode == 0:
version = result.stdout.strip().split("\n")[0]
runtimes[name] = version
else:
runtimes[name] = None
except (FileNotFoundError, subprocess.TimeoutExpired):
runtimes[name] = None
return runtimes
def _capture_services(self) -> dict:
"""Capture state of running dev services."""
services = {}
try:
result = subprocess.run(
["docker", "ps", "--format",
"{{.Names}}|{{.Image}}|{{.Status}}|{{.Ports}}"],
capture_output=True, text=True, timeout=10
)
for line in result.stdout.strip().split("\n"):
if not line:
continue
parts = line.split("|")
if len(parts) >= 4 and "dev_" in parts[0]:
services[parts[0]] = {
"image": parts[1],
"status": parts[2],
"ports": parts[3],
}
except (FileNotFoundError, subprocess.TimeoutExpired):
pass
return services
def _capture_filesystem(self) -> dict:
"""Capture key filesystem state."""
fs = {}
# Check for lock files
lock_files = [
"package-lock.json", "pnpm-lock.yaml",
"yarn.lock", "requirements.txt",
"poetry.lock", "go.sum", "Cargo.lock",
]
fs["lock_files_present"] = {
f: (self.root / f).exists() for f in lock_files
}
# Check for virtual environments
venvs = [".venv", "venv", ".env"]
fs["virtual_envs"] = {
v: (self.root / v).exists() for v in venvs
}
# Check for data directories
data_dirs = ["data", ".cache", "node_modules", "__pycache__"]
fs["data_dirs"] = {
d: (self.root / d).exists() for d in data_dirs
}
return fs
def fingerprint(self) -> str:
"""Generate a deterministic hash of the environment state."""
# Use a stable subset for hashing (exclude timestamps and hostnames)
stable_data = {
"runtimes": self.data.get("runtimes", {}),
"services": self.data.get("services", {}),
"filesystem": self.data.get("filesystem", {}),
}
content = json.dumps(stable_data, sort_keys=True, default=str)
return hashlib.sha256(content.encode()).hexdigest()[:16]
def save(self, path: Path = None):
"""Save manifest to disk."""
path = path or (self.root / ".env-manifest.json")
path.write_text(json.dumps(self.data, indent=2, default=str))
return path
def compare(self, expected: dict) -> list[str]:
"""Compare current state against expected state. Returns list of drifts."""
drifts = []
for runtime, expected_version in expected.get("runtimes", {}).items():
actual = self.data.get("runtimes", {}).get(runtime)
if actual and expected_version and actual != expected_version:
drifts.append(
f"Runtime '{runtime}': expected '{expected_version}', got '{actual}'"
)
for service, expected_cfg in expected.get("services", {}).items():
actual = self.data.get("services", {}).get(service)
if not actual:
drifts.append(f"Service '{service}' is not running")
elif expected_cfg.get("image") and actual.get("image") != expected_cfg["image"]:
drifts.append(
f"Service '{service}': image mismatch "
f"(expected '{expected_cfg['image']}', got '{actual['image']}')"
)
return drifts
def main():
"""CLI interface for environment manifest operations."""
import argparse
parser = argparse.ArgumentParser(description="Environment manifest tool")
parser.add_argument("command", choices=["capture", "verify", "diff"],
help="Operation to perform")
parser.add_argument("--expected", type=Path,
help="Path to expected manifest (for verify/diff)")
parser.add_argument("--output", type=Path,
help="Output path for captured manifest")
args = parser.parse_args()
manifest = EnvironmentManifest()
manifest.capture()
if args.command == "capture":
path = manifest.save(args.output)
print(f"Manifest saved to: {path}")
print(f"Fingerprint: {manifest.fingerprint()}")
elif args.command == "verify":
if not args.expected or not args.expected.exists():
print("Error: --expected manifest file required for verify")
sys.exit(1)
expected = json.loads(args.expected.read_text())
drifts = manifest.compare(expected)
if drifts:
print(f"\n⚠ {len(drifts)} environment drift(s) detected:\n")
for d in drifts:
print(f" • {d}")
sys.exit(1)
else:
print("✓ Environment matches expected state")
elif args.command == "diff":
if not args.expected or not args.expected.exists():
print("Error: --expected manifest file required for diff")
sys.exit(1)
expected = json.loads(args.expected.read_text())
print(f"Current fingerprint: {manifest.fingerprint()}")
print(f"Expected state captured: {expected.get('timestamp', 'unknown')}")
drifts = manifest.compare(expected)
if drifts:
print(f"\n{len(drifts)} difference(s):")
for d in drifts:
print(f" ✗ {d}")
else:
print("\nNo differences detected.")
if __name__ == "__main__":
main()
Integrate this into your CI pipeline:
# .github/workflows/env-verify.yml
name: Environment Verification
on:
pull_request:
paths:
- 'environment.yaml'
- 'bootstrap.py'
- '**/requirements.txt'
- '**/package.json'
jobs:
verify-env:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Capture baseline manifest
run: |
python bootstrap.py
python env_manifest.py capture --output .env-baseline.json
- name: Verify against expected
run: |
python env_manifest.py verify --expected expected-env.json
Principle 5: Measure What Matters
You cannot fix what you don't measure. The most common mistake teams make is measuring the wrong metrics — counting the number of setup scripts they've written rather than the actual time developers spend.
Here's a lightweight metrics collection system that captures real-world setup timing:
"""
setup_metrics.py — Measure and report dev environment setup performance.
This module instruments the bootstrap process to capture real timing data,
then aggregates it into actionable dashboards.
"""
import json
import os
import time
import uuid
from collections import defaultdict
from dataclasses import dataclass, field
from datetime import datetime, timezone
from pathlib import Path
from typing import Optional
@dataclass
class SetupSession:
"""A single developer's setup session."""
session_id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
started_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
steps: list[dict] = field(default_factory=list)
os_info: str = field(default_factory=lambda: f"{os.uname().sysname} {os.uname().machine()}")
success: bool = False
error: Optional[str] = None
def start_step(self, name: str) -> float:
"""
Top comments (0)