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

Software	Required Version	macOS	Linux	Windows (WSL2)
{{RUNTIME}}	{{VERSION}}	brew install {{RUNTIME}}	apt install {{RUNTIME}}	Via WSL2
Docker Desktop	{{DOCKER_VERSION}}+	docker.com	docs	docs
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)

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

---

3. Detailed Setup

3.1 Runtime Version Manager

Tool: {{VERSION_MANAGER}}

# 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

# 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

Option A: Docker (recommended)

# 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

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

{{DB_VERIFY_CMD}}
# Should output: {{DB_VERIFY_EXPECTED}}

3.4 Environment Variables

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

# 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

# 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	[email protected]	{{SEED_PWD}}	Full access
User	[email protected]	{{SEED_PWD}}	Standard user

---

4. Running the Application

Development Server

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

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

What starts: {{DEV_WHAT_STARTS}}

Watch Mode / Hot Reload

Hot reload is enabled by default in development. When you save a file:

• Backend: {{BACKEND_RELOAD}}
• Frontend: {{FRONTEND_RELOAD}}

Debug Mode

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

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

# Android Emulator
{{ANDROID_CMD}}

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

---

5. Running Tests

Unit Tests

# 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

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

# Run integration tests
{{INT_CMD}}

E2E Tests

# 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

{{COV_CMD}}

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

---

6. Common Issues & Solutions

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

7.1 docker-compose.yml Reference

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

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

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "{{FORMATTER_ID}}",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

---

Related Documents

• Developer Onboarding Guide
• Coding Standards
• Environment Configuration

---

Approval

Role	Name	Date	Signature
Author
Reviewer
Approver