# Local Development Setup

# Local Development Setup

> **Project:** {{PROJECT_NAME}}
> **Version:** {{VERSION}}
> **Date:** {{DATE}}
> **Author:** {{AUTHOR}}
> **Status:** Draft | In Review | Approved
> **Reviewers:** {{REVIEWERS}}

## Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1     | {{DATE}} | {{AUTHOR}} | Initial draft |

---

## 1. System Requirements

<!-- GUIDANCE: Hard requirements (must have) vs soft requirements (nice to have). -->

| Software | Required Version | macOS | Linux | Windows (WSL2) |
|----------|-----------------|-------|-------|----------------|
| {{RUNTIME}} | `{{VERSION}}` | `brew install {{RUNTIME}}` | `apt install {{RUNTIME}}` | Via WSL2 |
| Docker Desktop | `{{DOCKER_VERSION}}+` | [docker.com](https://docker.com/get-docker) | [docs](https://docs.docker.com/engine/install/) | [docs](https://docs.docker.com/desktop/install/windows-install/) |
| Git | `2.30+` | Pre-installed | `apt install git` | Via WSL2 |
| {{OTHER_TOOL}} | `{{VERSION}}` | `brew install {{OTHER_TOOL}}` | `{{LINUX_INSTALL}}` | {{WINDOWS_INSTALL}} |

**Hardware minimum:** {{MIN_RAM}}GB RAM, {{MIN_DISK}}GB free disk space
**Recommended:** {{REC_RAM}}GB RAM, SSD

**Not supported:** Windows without WSL2

---

## 2. Quick Start (5 Steps)

<!-- GUIDANCE: The fast path for experienced developers. Full detail in Section 3. -->

```bash
# 1. Clone
git clone {{REPO_URL}} && cd {{REPO_NAME}}

# 2. Install dependencies
{{INSTALL_CMD}}

# 3. Configure
cp .env.example .env
# Edit .env — see Section 5 for required values

# 4. Run (with Docker for dependencies)
{{START_CMD}}

# 5. Verify
open http://localhost:{{PORT}}
# Should see: {{EXPECTED_LANDING}}
```

**Total time (fast path):** ~{{QUICKSTART_TIME}} minutes

If anything fails, read the full setup in Section 3 or check [Common Issues](#9-common-issues--solutions).

---

## 3. Detailed Setup

### 3.1 Runtime Version Manager

<!-- GUIDANCE: Use a version manager to avoid conflicts between projects. -->

**Tool:** {{VERSION_MANAGER}} <!-- nvm (Node) / pyenv (Python) / rbenv (Ruby) / asdf (multi-language) -->

```bash
# Install version manager
{{VM_INSTALL_CMD}}

# Install required runtime version
{{VM_USE_CMD}} {{RUNTIME_VERSION}}

# Set as default
{{VM_DEFAULT_CMD}} {{RUNTIME_VERSION}}

# Verify
{{RUNTIME}} --version  # Should output: {{RUNTIME_VERSION}}
```

**Auto-switching:** The project root contains `.{{VERSION_FILE}}` (e.g., `.nvmrc`, `.python-version`). If your shell is configured, it switches automatically on `cd` into the project.

### 3.2 Package Manager Setup

```bash
# The project uses {{PKG_MANAGER}}
# Install it if not available:
{{PKG_MANAGER_INSTALL}}

# Install project dependencies
cd {{REPO_NAME}}
{{INSTALL_CMD}}

# Verify installation
{{INSTALL_VERIFY_CMD}}
```

**Lockfile:** `{{LOCKFILE}}` — committed to git. Do NOT delete it. Run `{{INSTALL_CMD}}` (not `{{FORCE_INSTALL_CMD}}`) to respect lockfile.

### 3.3 Database Setup

<!-- GUIDANCE: Option A: Docker (recommended, easiest). Option B: Local install. -->

**Option A: Docker (recommended)**

```bash
# Start database container
docker-compose up -d db

# Verify database is running
{{DB_CHECK_CMD}}

# Run migrations
{{MIGRATE_CMD}}

# Seed development data
{{SEED_CMD}}
```

**Option B: Local database install**

```bash
# Install PostgreSQL (example)
brew install postgresql@{{PG_VERSION}}  # macOS
# or: sudo apt install postgresql-{{PG_VERSION}}  # Linux

# Start database
{{DB_START_LOCAL_CMD}}

# Create database
createdb {{DB_NAME}}_dev

# Run migrations
{{MIGRATE_CMD}}

# Seed development data
{{SEED_CMD}}
```

**Verify database is set up:**
```bash
{{DB_VERIFY_CMD}}
# Should output: {{DB_VERIFY_EXPECTED}}
```

### 3.4 Environment Variables

```bash
# Copy the example file
cp .env.example .env
```

**Edit `.env` with your local values:**

| Variable | Value for Local | Notes |
|----------|----------------|-------|
| `DATABASE_URL` | `{{LOCAL_DB_URL}}` | Update with your local DB creds |
| `REDIS_URL` | `redis://localhost:6379` | Default if using Docker |
| `PORT` | `{{PORT}}` | |
| `NODE_ENV` | `development` | |
| `{{SECRET_VAR}}` | — | Ask your onboarding buddy |

**Never commit `.env`:** It's in `.gitignore`. Use `.env.example` for sharing template values.

### 3.5 SSL Certificates (If Needed Locally)

<!-- GUIDANCE: Only include this section if the project requires HTTPS locally. -->

```bash
# Install mkcert
brew install mkcert    # macOS
# or: apt install mkcert  # Linux

# Install local CA
mkcert -install

# Generate cert for localhost
mkcert localhost 127.0.0.1 ::1

# Move certs to project (check .env for expected paths)
mv localhost+2.pem {{CERT_PATH}}
mv localhost+2-key.pem {{KEY_PATH}}
```

### 3.6 Seed Data Loading

```bash
# Load fixture data (fast, for unit/integration tests)
{{FIXTURE_CMD}}

# Load realistic development data (slower, ~{{SEED_SIZE}} records)
{{DEV_SEED_CMD}}

# Reset to clean state
{{RESET_CMD}}
```

**Seeded accounts after running seed:**

| Role | Email | Password | Notes |
|------|-------|----------|-------|
| Admin | `admin@dev.local` | `{{SEED_PWD}}` | Full access |
| User | `user@dev.local` | `{{SEED_PWD}}` | Standard user |

---

## 4. Running the Application

### Development Server

```bash
# Start development server (with hot reload)
{{DEV_CMD}}

# Application available at:
http://localhost:{{PORT}}
```

**What starts:** {{DEV_WHAT_STARTS}}
<!-- e.g., "API server on :3000, background workers, file watcher" -->

### Watch Mode / Hot Reload

Hot reload is enabled by default in development. When you save a file:
- **Backend:** {{BACKEND_RELOAD}} <!-- Server restarts / Module hot-swapped -->
- **Frontend:** {{FRONTEND_RELOAD}} <!-- Page reloads / Fast refresh (state preserved) -->

### Debug Mode

```bash
# Start with Node.js debugger
{{DEBUG_CMD}}

# Then attach your IDE debugger to port {{DEBUG_PORT}}
```

**VS Code launch config:** `.vscode/launch.json` — includes pre-configured debug targets.

### Mobile Development (If Applicable)

```bash
# iOS Simulator (macOS only)
{{IOS_CMD}}

# Android Emulator
{{ANDROID_CMD}}
```

**Requires:** Xcode (iOS), Android Studio (Android)

---

## 5. Running Tests

### Unit Tests

```bash
# Run all unit tests
{{UNIT_CMD}}

# Run tests in watch mode (re-runs on file save)
{{UNIT_WATCH_CMD}}

# Run specific test file
{{UNIT_CMD}} {{TEST_FILE_PATH}}

# Run tests matching pattern
{{UNIT_CMD}} --grep "{{PATTERN}}"
```

### Integration Tests

```bash
# Requires database and Redis running (use Docker)
docker-compose up -d db redis

# Run integration tests
{{INT_CMD}}
```

### E2E Tests

```bash
# Requires full application stack running
{{DEV_CMD}} &  # Or start in separate terminal

# Run E2E tests (headless)
{{E2E_CMD}}

# Run E2E with browser visible (debugging)
{{E2E_HEADED_CMD}}

# Run specific E2E test
{{E2E_CMD}} --grep "{{PATTERN}}"
```

### Test Coverage Report

```bash
{{COV_CMD}}

# Report generated at: {{COV_REPORT_PATH}}
# Open in browser:
open {{COV_REPORT_PATH}}/index.html
```

---

## 6. Common Issues & Solutions

<!-- GUIDANCE: Document every issue the team has encountered during setup. Keep this up to date. -->

| Problem | Likely Cause | Solution |
|---------|-------------|----------|
| `Module not found` | Dependencies not installed | Run `{{INSTALL_CMD}}` |
| `Database connection refused` | DB not running | Run `docker-compose up -d db` |
| `Port {{PORT}} already in use` | Another process using the port | `lsof -ti:{{PORT}} \| xargs kill` |
| `Permission denied: .env` | File permission issue | `chmod 600 .env` |
| `Node version mismatch` | Wrong Node version active | `{{VERSION_MANAGER}} use {{NODE_VERSION}}` |
| Slow performance on Docker (macOS) | Docker Desktop volume mounts | Enable VirtioFS in Docker Desktop settings |
| `EACCES: permission denied, mkdir node_modules` | npm global prefix issue | See [npm fix](https://docs.npmjs.com/resolving-eacces-permissions-errors) |
| Tests failing with timeout | Integration test DB not running | `docker-compose up -d` |
| `SSL: certificate verify failed` | Missing cert or mkcert not installed | Re-run mkcert setup (Section 3.5) |
| `Migration already applied` | Stale migration state | `{{MIGRATION_ROLLBACK_CMD}}` then re-run |

**Still stuck?** Ask in `#{{DEV_CHANNEL}}` or ping your onboarding buddy.

---

## 7. Docker Setup (Alternative)

<!-- GUIDANCE: For developers who prefer Docker-based development or when native setup is problematic. -->

### 7.1 docker-compose.yml Reference

```bash
# Start all services
docker-compose up

# Start only backend services (db, redis, etc.)
docker-compose up db redis

# Rebuild after Dockerfile changes
docker-compose up --build

# Stop and remove containers
docker-compose down

# Stop and remove containers + volumes (reset state)
docker-compose down -v
```

**Services defined in `docker-compose.yml`:**

| Service | Port | Description |
|---------|------|-------------|
| `app` | `{{PORT}}` | Main application |
| `db` | `{{DB_PORT}}` | PostgreSQL database |
| `redis` | `6379` | Redis cache |
| `{{OTHER}}` | `{{PORT}}` | {{DESCRIPTION}} |

### 7.2 Volume Mounts

| Local Path | Container Path | Purpose |
|------------|---------------|---------|
| `.` | `/app` | Source code (hot reload) |
| `db-data` | `/var/lib/postgresql/data` | Database persistence |
| `node_modules` | `/app/node_modules` | Isolated from host |

### 7.3 Port Mappings

| Host Port | Container Port | Service |
|-----------|---------------|---------|
| `{{PORT}}` | `{{PORT}}` | Application |
| `{{DB_PORT}}` | `5432` | PostgreSQL |
| `6379` | `6379` | Redis |

---

## 8. IDE Configuration

### 8.1 Recommended Extensions (VS Code)

```bash
# Install all at once
cat .vscode/extensions.json | jq '.recommendations[]' | xargs -I{} code --install-extension {}
```

| Extension | ID | Purpose |
|-----------|-----|---------|
| {{EXT_1}} | `{{ID}}` | {{PURPOSE}} |
| {{EXT_2}} | `{{ID}}` | {{PURPOSE}} |
| {{EXT_3}} | `{{ID}}` | {{PURPOSE}} |
| ESLint | `dbaeumer.vscode-eslint` | Inline linting |
| Prettier | `esbenp.prettier-vscode` | Format on save |

### 8.2 Debug Configurations

The project includes `.vscode/launch.json` with these pre-built debug targets:

| Configuration | What it does |
|---------------|-------------|
| `Debug: API Server` | Starts API with debugger attached on port {{DEBUG_PORT}} |
| `Debug: Tests` | Runs test suite with breakpoints supported |
| `Attach to Process` | Attach debugger to running process |

### 8.3 Workspace Settings

`.vscode/settings.json` (committed to repo):
```json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "{{FORMATTER_ID}}",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}
```

---

## Related Documents

- [Developer Onboarding Guide](./developer-onboarding-guide.md)
- [Coding Standards](./coding-standards.md)
- [Environment Configuration](../INFRASTRUCTURE/environment-configuration.md)

---

## Approval
| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | | | |
| Reviewer | | | |
| Approver | | | |