This source did not publish a separate summary. Review SKILL.md before using the skill.
SKILL.md
Local Dev Setup Skill
Produce a complete local development environment setup guide for a service or project — walking a new engineer from zero (a clean laptop) to a working local environment with passing tests in under 30 minutes. A good setup guide reduces onboarding time, prevents the "it works on my machine" problem, and lets engineers make their first contribution with confidence. Write every step as a concrete command or action — not a description of what needs to happen.
Required Inputs
Ask for these if not already provided:
Service name and what it does
Tech stack — language, framework, database, cache, message queue, and any external services
Dependencies — databases, caches, message queues, and external services (mocked or real)
Test framework — how tests are run and what the test suite covers
CI/CD platform — GitHub Actions, CircleCI, Jenkins, etc. (for context on what "passing CI" means locally)
Output Format
Local Development Setup: [Service Name]
Tech stack: [Language + version] | [Framework] | [Database] | [Cache]
Estimated setup time: [20–30 minutes] on a clean machine
Last verified: [Date] on [macOS Ventura 13.x / Ubuntu 22.04]
Questions? Ask in [Slack: #[team-channel]] or ping [@tech-lead-handle]
First contribution? Complete setup first (this doc), then read [CONTRIBUTING.md] for code standards and PR process.
Prerequisites
Install these tools before starting. The versions listed are the minimum required — newer patch versions are fine, newer major versions may have compatibility issues.
Required Tools
Tool
Required version
Install
[Git]
2.x+
Pre-installed on most systems; or brew install git
GitHub access to [org/repo] — request via [access request process / Slack: #it-help]
[AWS / GCP / Azure] account with [dev environment] access — request via [process]
[Internal tool — e.g. 1Password] for retrieving development secrets — request via [process]
[VPN access] if required to reach internal services — request via [process]
1. Repository Setup
# Clone the repository
git clone [email protected]:[org]/[repo-name].git
cd [repo-name]
# Install git hooks (required — enforces commit message format and runs pre-commit checks)
make install-hooks
# Or manually:
# cp scripts/hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
# Verify your git setup
git config user.name # should be your name
git config user.email # should be your work email
If you see a permission denied error on clone: Your SSH key is not added to GitHub. Follow GitHub's SSH key guide or use HTTPS with a personal access token instead.
2. Environment Variables
The service requires environment variables for configuration. Never commit actual secrets to the repository.
Step 1 — Copy the example file
cp .env.example .env.local
Step 2 — Fill in the values
Open .env.local in your editor. Below is a description of every variable and where to get its value:
Retrieve from [1Password vault: "Dev API Keys"] or ask [name]
—
[EXTERNAL_SERVICE]_BASE_URL
Base URL for [External Service]
Use sandbox URL: https://sandbox.[external-service].com
https://sandbox.stripe.com
LOG_LEVEL
Logging verbosity
Set to debug for local development
debug
[FEATURE_FLAG_SDK_KEY]
Feature flag platform SDK key
Retrieve from [LaunchDarkly/Split dev project]
—
Using direnv (recommended): Rename .env.local to .envrc, add dotenv at the top, and run direnv allow. Variables will load automatically when you cd into the project.
3. Local Service Dependencies
All infrastructure dependencies run in Docker Compose. You do not need to install PostgreSQL, Redis, or Kafka locally.
# Start all dependencies (PostgreSQL, Redis, and any other services)
docker compose up -d
# Verify all containers are healthy
docker compose ps
# Expected output: all services show "healthy" status
# View logs if something is not healthy
docker compose logs [service-name]
What Docker Compose Starts
Service
Port
Purpose
Health check
PostgreSQL [version]
5432
Primary database
pg_isready -U app
Redis [version]
6379
Cache and session store
redis-cli ping
[Kafka + Zookeeper]
9092 / 2181
Message queue
kafka-topics.sh --list
[Mock server — e.g. WireMock]
8089
Mocks for external APIs in tests
curl localhost:8089/__admin
[LocalStack]
4566
AWS service emulation (S3, SQS, etc.)
aws --endpoint-url=http://localhost:4566 s3 ls
If a container exits immediately: See Troubleshooting section — common causes are port conflicts and Docker memory limits.
Stopping Dependencies
# Stop containers (preserves data volumes)
docker compose stop
# Stop and remove containers (clears data — use when you want a fresh start)
docker compose down -v
4. Install Dependencies and Build
# Install language dependencies
# Go:
go mod download
# Node.js:
npm install # or: yarn install / pnpm install
# Python:
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt
# Verify build compiles cleanly
make build
# Expected: no errors; binary or compiled output in [./bin/ or ./dist/]
5. Database Setup and Seeding
# Run database migrations (creates tables and schema)
make db-migrate
# Or directly:
# [Migration command — e.g. "go run ./cmd/migrate up" or "alembic upgrade head" or "npm run db:migrate"]
# Verify migrations applied
# psql $DATABASE_URL -c "\dt" # should list all tables
# Seed the database with development data
make db-seed
# Or directly:
# [Seed command — e.g. "go run ./cmd/seed" or "python scripts/seed.py" or "npm run db:seed"]
# Verify seed data is present
# psql $DATABASE_URL -c "SELECT COUNT(*) FROM [primary-table]"
# Expected: [N] rows
What the seed creates:
[N] test user accounts (credentials in [scripts/seed/README.md or .env.example])
[N] sample [resources] for development and testing
Admin account: [[email protected]] / password: see .env.example for dev password variable
To reset to a clean state:
docker compose down -v # wipe database volume
docker compose up -d # start fresh
make db-migrate
make db-seed
6. Running the Service
# Run the service locally
make run
# Or directly:
# [Run command — e.g. "go run ./cmd/server" or "python app.py" or "npm run dev"]
# Expected output:
# [Example of healthy startup log lines — e.g.:]
# {"level":"info","message":"Database connected","host":"localhost","port":5432}
# {"level":"info","message":"Redis connected","host":"localhost","port":6379}
# {"level":"info","message":"Server listening","port":8080}
Verify It's Working
# Health check
curl http://localhost:8080/health
# Expected: {"status":"ok","version":"[git-sha]"}
# Test a key endpoint (authenticated)
# First, get a dev token:
curl -X POST http://localhost:8080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"[dev-user-from-seed]@example.com","password":"[dev-password-from-env]"}'
# Copy the token from the response, then:
curl http://localhost:8080/api/v1/[resource] \
-H "Authorization: Bearer [token-from-above]"
# Expected: 200 with JSON response
Hot Reload (for Development)
# Run with hot reload — service restarts automatically on file changes
make run-dev
# Or:
# [Hot reload command — e.g. "air" for Go / "uvicorn --reload" for Python / "npm run dev" for Node]
7. Running Tests
# Run the full test suite
make test
# Or:
# [Test command — e.g. "go test ./..." or "pytest" or "npm test"]
# Run tests with coverage report
make test-coverage
# Coverage report: [./coverage.html or stdout]
# Run a specific test file or test case
# Go: go test ./pkg/[package]/... -run TestFunctionName
# Python: pytest tests/test_[module].py::TestClass::test_method -v
# Node: npm test -- --testPathPattern=[filename]
# Run only unit tests (fast — no external dependencies)
make test-unit
# Run only integration tests (requires Docker Compose dependencies running)
make test-integration
Expected test results:
Unit tests: [N] tests, all pass, [<30] seconds
Integration tests: [N] tests, all pass, [<2] minutes
Coverage: [≥80]% (enforced in CI — tests fail below this threshold)
Before pushing a PR, always run:
make lint # code linting — must pass
make test # full test suite — must pass
make build # verify compilation — must pass
8. IDE Setup
VS Code (Recommended)
Install the recommended extensions (VS Code will prompt you automatically):
// .vscode/extensions.json — already in the repository
{
"recommendations": [
"[language-extension — e.g. golang.go]",
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"ms-azuretools.vscode-docker",
"eamodio.gitlens"
]
}
Workspace settings are in .vscode/settings.json — format on save is enabled, linter is configured automatically.
[Language]-specific setup:
[e.g. Go: The gopls language server is installed automatically by the Go extension.
Run "Go: Install/Update Tools" from the command palette after installing the extension.]
[Language SDK]: set to [version] — File → Project Structure → SDKs
Run configurations are checked into .idea/runConfigurations/ — they appear automatically
Enable "Run formatters on save" in Settings → Tools → Actions on Save
9. Common Gotchas and Troubleshooting
Docker container exits immediately on startup
Symptom:docker compose ps shows a container as Exited (1) seconds after starting.
# Check the container logs for the error
docker compose logs [container-name]
# Common causes:
# 1. Port already in use — find and kill the conflicting process:
lsof -ti tcp:[port] | xargs kill -9
# 2. Docker doesn't have enough memory — allocate at least 4GB in Docker Desktop:
# Docker Desktop → Settings → Resources → Memory → 4GB
# 3. M1/M2 Mac architecture mismatch — add platform directive to docker-compose.yml:
# platform: linux/amd64
Database connection refused
Symptom: Service fails to start with "connection refused" or "dial tcp localhost:5432: connect: connection refused"
# Is PostgreSQL actually running?
docker compose ps postgres
# If not running: docker compose up -d postgres
# Is it on the right port?
lsof -i :5432
# Can you connect manually?
psql postgres://app:password@localhost:5432/[service]_dev -c "SELECT 1"
# If using a custom DATABASE_URL, verify it matches the docker-compose.yml settings exactly
Migrations fail with "relation already exists"
Symptom:make db-migrate errors with "ERROR: relation [table] already exists"
# Check current migration state
[migration status command — e.g. "go run ./cmd/migrate status" or "alembic current"]
# The database may be in a partial state — reset it:
docker compose down -v
docker compose up -d
make db-migrate # should now succeed on a clean database
Tests fail with "connection refused" or dependency errors
Symptom: Integration tests fail because they cannot connect to PostgreSQL or Redis.
# Integration tests need Docker Compose running
docker compose up -d
# Verify all containers are healthy before running tests
docker compose ps # all should show "healthy"
# If containers are running but tests still fail, check environment variables:
make test-integration # should pick up .env.local automatically
# If not: source .env.local && make test-integration
make lint fails on a fresh checkout
Symptom: Lint errors on files you have not modified.
