local-dev-setup

# 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` |
| [Language runtime — e.g. Go] | [1.22+] | [https://go.dev/dl/ or `brew install go`] |
| [Docker] | 24.x+ | [https://docs.docker.com/get-docker/] |
| [Docker Compose] | 2.x+ | Included with Docker Desktop; or `brew install docker-compose` |
| [Make] | Any | Pre-installed on macOS/Linux |
| [Tool — e.g. Node.js] | [20.x+] | [`brew install node` or https://nodejs.org] |
| [Tool — e.g. psql client] | [15+] | `brew install postgresql@15` (client only) |

### Optional but Recommended

| Tool | Purpose | Install |
|---|---|---|
| [direnv] | Auto-load `.envrc` environment variables | `brew install direnv` + [setup instructions](https://direnv.net) |
| [jq] | Pretty-print JSON in terminal | `brew install jq` |
| [k9s] | Kubernetes cluster UI (if using K8s locally) | `brew install k9s` |
| [mkcert] | Local HTTPS certificates | `brew install mkcert` |

### 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

```bash
# 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](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) 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

```bash
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:

| Variable | Description | Where to get it | Example (not real) |
|---|---|---|---|
| `APP_ENV` | Environment name | Set to `development` | `development` |
| `APP_PORT` | Port the service listens on | Set to `8080` for local | `8080` |
| `DATABASE_URL` | PostgreSQL connection string | Use value from Docker Compose (Section 3) | `postgres://app:password@localhost:5432/[service]_dev` |
| `REDIS_URL` | Redis connection string | Use value from Docker Compose | `redis://localhost:6379` |
| `SECRET_KEY` | Application secret key | Generate with: `openssl rand -hex 32` | `[random 64-char hex]` |
| `[EXTERNAL_SERVICE]_API_KEY` | API key for [External Service] | 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.

```bash
# 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` |
| R