Zero-to-Running Developer Environment

Automate the creation of production-grade local development environments that start with a single command. This skill handles multi-service application stacks including frontend, backend, databases, caches, and orchestration.

Core Workflows

1. Initial Setup Script Generation

Generate the main setup script that orchestrates the entire environment:

bash

# Target: make dev (or ./scripts/dev-up.sh)
# Requirements:
# - Check prerequisites (Docker, kubectl, etc.)
# - Load configuration
# - Start services in dependency order
# - Run health checks
# - Display status and access URLs

Key considerations:

Validate all prerequisites before starting
Provide clear, actionable error messages
Show progress indicators during setup
Handle port conflicts gracefully
Support both docker-compose and Kubernetes

2. Configuration File Creation

Generate externalized configuration (.env.example or config/dev.yml):

yaml

# Service ports
FRONTEND_PORT=3000
API_PORT=8000
POSTGRES_PORT=5432
REDIS_PORT=6379

# Database credentials (mock/dev only)
DB_NAME=dev_db
DB_USER=dev_user
DB_PASSWORD=dev_password_change_in_production

# Feature flags
ENABLE_HOT_RELOAD=true
ENABLE_DEBUG_MODE=true
LOG_LEVEL=debug

Patterns:

Separate dev/prod concerns clearly
Comment all configuration options
Use secure defaults
Document credential management pattern

3. Service Orchestration Files

Docker Compose (Simpler Option)

Generate docker-compose.yml for local development:

yaml

version: '3.8'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    ports:
      - "${POSTGRES_PORT}:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "${REDIS_PORT}:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s

  api:
    build:
      context: ./backend
      dockerfile: Dockerfile.dev
    ports:
      - "${API_PORT}:8000"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
      REDIS_URL: redis://redis:6379
    volumes:
      - ./backend:/app
      - /app/node_modules

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile.dev
    ports:
      - "${FRONTEND_PORT}:3000"
    depends_on:
      - api
    environment:
      VITE_API_URL: http://localhost:${API_PORT}
    volumes:
      - ./frontend:/app
      - /app/node_modules

Kubernetes (Production-Like Option)

Generate k8s manifests in k8s/dev/:

postgres-deployment.yaml - Database with persistent volume
redis-deployment.yaml - Cache service
api-deployment.yaml - Backend with readiness probes
frontend-deployment.yaml - Frontend with service
configmap.yaml - Configuration
secrets.yaml - Mock secrets with warning comments

Key patterns:

Use ConfigMaps for configuration
Include health/readiness probes
Set appropriate resource limits
Use local storage classes for PVs

4. Health Check Implementation

Create health check scripts that verify all services:

bash

#!/bin/bash
# scripts/health-check.sh

echo "🔍 Checking service health..."

# Check PostgreSQL
if pg_isready -h localhost -p $POSTGRES_PORT -U $DB_USER > /dev/null 2>&1; then
  echo "✅ PostgreSQL is ready"
else
  echo "❌ PostgreSQL is not responding"
  exit 1
fi

# Check Redis
if redis-cli -h localhost -p $REDIS_PORT ping > /dev/null 2>&1; then
  echo "✅ Redis is ready"
else
  echo "❌ Redis is not responding"
  exit 1
fi

# Check API
if curl -f -s http://localhost:$API_PORT/health > /dev/null; then
  echo "✅ API is ready"
else
  echo "❌ API is not responding"
  exit 1
fi

# Check Frontend
if curl -f -s http://localhost:$FRONTEND_PORT > /dev/null; then
  echo "✅ Frontend is ready"
else
  echo "❌ Frontend is not responding"
  exit 1
fi

echo "🎉 All services are healthy!"

5. Teardown Script

Generate cleanup script (make dev-down or ./scripts/dev-down.sh):

bash

#!/bin/bash
# Gracefully stop all services and clean up resources

echo "🛑 Stopping development environment..."

# Docker Compose variant
docker-compose down -v  # -v removes volumes

# Kubernetes variant
kubectl delete namespace dev-env --wait=true

echo "✅ Environment cleaned up"

6. Documentation Generation

Create comprehensive DEVELOPER_SETUP.md:

markdown

# Developer Setup Guide

## Prerequisites
- Docker Desktop 24+ or Docker Engine + Docker Compose
- kubectl (if using Kubernetes)
- Git
- Node.js 20+ (for local development)

## Quick Start
1. Clone repository: `git clone <repo-url>`
2. Copy configuration: `cp .env.example .env`
3. Start environment: `make dev`
4. Access services:
   - Frontend: http://localhost:3000
   - API: http://localhost:8000
   - API Docs: http://localhost:8000/docs

## Teardown
```bash
make dev-down

Troubleshooting

Port conflicts: Edit .env to change ports
Services won't start: Run docker-compose logs <service>
Database issues: Remove volumes with docker-compose down -v


### 7. Makefile Integration

Generate `Makefile` for developer convenience:

```makefile
.PHONY: dev dev-down dev-reset health logs test

dev:
	@echo "🚀 Starting development environment..."
	@./scripts/dev-up.sh

dev-down:
	@echo "🛑 Stopping development environment..."
	@./scripts/dev-down.sh

dev-reset: dev-down dev
	@echo "🔄 Environment reset complete"

health:
	@./scripts/health-check.sh

logs:
	docker-compose logs -f

test:
	@echo "🧪 Running tests..."
	docker-compose exec api npm test

Common Patterns

Dependency Ordering

Ensure services start in correct order:

Infrastructure (Postgres, Redis)
Backend API (after DB is ready)
Frontend (after API is ready)

Secret Management

Pattern for handling secrets:

bash

# .env.example (committed)
DB_PASSWORD=dev_password_change_in_production

# .env (gitignored)
DB_PASSWORD=actual_dev_password

# Production
DB_PASSWORD_SECRET=arn:aws:secretsmanager:...

Hot Reload Configuration

Enable development-friendly features:

Volume mounts for live code changes
Debug ports exposed (Node: 9229, Python: 5678)
Source maps enabled
File watchers configured

Error Handling

Scripts should:

Exit on first error (set -e)
Provide clear error messages
Suggest fixes for common problems
Log errors to file for debugging

Best Practices

Make it fast: Use caching, parallel starts where safe
Make it clear: Show progress, log to console and file
Make it safe: Never commit real secrets, validate inputs
Make it flexible: Support configuration overrides
Make it reproducible: Pin all versions (images, packages)
Make it documented: Include inline comments and README

Troubleshooting Guide

Common Issues

Port already in use:

bash

# Find process using port
lsof -i :3000
# Kill process or change port in .env

Docker daemon not running:

bash

# macOS/Windows: Start Docker Desktop
# Linux: sudo systemctl start docker

Database won't connect:

bash

# Check if container is running
docker ps | grep postgres
# Check logs
docker logs <container-id>
# Reset database
docker-compose down -v && docker-compose up -d

Out of date images:

bash

# Pull latest images
docker-compose pull
# Rebuild with no cache
docker-compose build --no-cache

Performance Optimizations

Parallel service startup: Start independent services simultaneously
Image layer caching: Structure Dockerfiles for optimal caching
Volume optimization: Use named volumes instead of bind mounts for node_modules
Network configuration: Use custom networks for better isolation
Resource limits: Set appropriate CPU/memory limits to prevent resource exhaustion

Skill Integrations

This skill works seamlessly with companion skills:

database-seeding: Automatically seed databases with realistic test data
git-hooks: Set up pre-commit linting and pre-push testing
local-ssl: Enable HTTPS for local development with trusted certificates
env-manager: Switch between dev/test/staging environments easily

When multiple skills are available, reference them in the setup documentation and scripts.

Search AI Tools

zero-to-running

Install this agent skill to your Project

SKILL.md

Zero-to-Running Developer Environment

Core Workflows

1. Initial Setup Script Generation

2. Configuration File Creation

3. Service Orchestration Files

Docker Compose (Simpler Option)

Kubernetes (Production-Like Option)

4. Health Check Implementation

5. Teardown Script

6. Documentation Generation

Troubleshooting

Common Patterns

Dependency Ordering

Secret Management

Hot Reload Configuration

Error Handling

Best Practices

Troubleshooting Guide

Common Issues

Performance Optimizations

Skill Integrations