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

Optional but Recommended

Required Accounts and Access

Before starting, make sure you have:

• 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 git@github.com:[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:

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

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: [admin@example.com] / password: see .env.example for dev password variable