# Local Setup

Native installation for active development with hot reload and debugging.

## Prerequisites

Complete [Prerequisites](1-prerequisites.md) first.

## Step 1: Clone Repository

```bash
git clone https://git.mosaicstack.dev/mosaic/stack mosaic-stack
cd mosaic-stack
```

## Step 2: Install Dependencies

```bash
pnpm install
```

This installs dependencies for:

- Root workspace
- `apps/api` (NestJS backend)
- `apps/web` (Next.js frontend - when implemented)
- `packages/shared` (Shared types and utilities)

## Step 3: Configure Environment

```bash
# Copy environment template
cp .env.example .env

# Edit configuration
nano .env  # or use your preferred editor
```

**Minimum required configuration:**

```bash
# Database
DATABASE_URL=postgresql://mosaic:mosaic@localhost:5432/mosaic

# JWT Session
JWT_SECRET=$(openssl rand -base64 32)
JWT_EXPIRATION=24h

# Application
NEXT_PUBLIC_APP_URL=http://localhost:3000
```

See [Configuration → Environment](../3-configuration/1-environment.md) for complete reference.

## Step 4: Setup PostgreSQL Database

### Create Database and User

```bash
sudo -u postgres psql <<EOF
CREATE USER mosaic WITH PASSWORD 'mosaic';
CREATE DATABASE mosaic OWNER mosaic;
\c mosaic
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
GRANT ALL PRIVILEGES ON DATABASE mosaic TO mosaic;
EOF
```

### Or Use Docker PostgreSQL

```bash
# Start only PostgreSQL
docker compose up -d postgres

# Wait for it to be ready
sleep 5
```

## Step 5: Run Database Migrations

```bash
# Generate Prisma client
pnpm prisma:generate

# Run migrations
cd apps/api
pnpm prisma migrate deploy

# Seed development data (optional)
pnpm prisma:seed

# Return to project root
cd ../..
```

## Step 6: Start Development Servers

```bash
# Start all services
pnpm dev

# This starts:
# - API on http://localhost:3001
# - Web on http://localhost:3000 (when implemented)
```

**Or start individually:**

```bash
# API only
pnpm dev:api

# Web only (when implemented)
pnpm dev:web
```

## Step 7: Verify Installation

### Check API Health

```bash
curl http://localhost:3001/health
```

**Expected response:**

```json
{
  "status": "ok",
  "timestamp": "2026-01-28T...",
  "uptime": 1234
}
```

### Run Tests

```bash
pnpm test
```

**Expected output:**

```
Test Files  5 passed (5)
     Tests  26 passed (26)
```

### Open Prisma Studio

```bash
cd apps/api
pnpm prisma:studio

# Opens at http://localhost:5555
```

## Development Workflow

### File Watching

The development servers automatically reload when you make changes:

```bash
# API watches src/**/*.ts
pnpm dev:api

# Changes trigger automatic restart
```

### Running Specific Tests

```bash
# All tests
pnpm test

# Watch mode (re-runs on file changes)
pnpm test:watch

# Specific test file
pnpm test apps/api/src/auth/auth.service.spec.ts

# Coverage report
pnpm test:coverage
```

### Database Management

```bash
cd apps/api

# Open Prisma Studio GUI
pnpm prisma:studio

# Create migration after schema changes
pnpm prisma migrate dev --name your_migration_name

# Reset database (WARNING: deletes data)
pnpm prisma migrate reset
```

## Troubleshooting

### Port Already in Use

```bash
# Find process using port
lsof -i :3001

# Kill process
kill -9 <PID>

# Or use different port
PORT=3002 pnpm dev:api
```

### PostgreSQL Connection Failed

```bash
# Check if PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -U mosaic -d mosaic -h localhost -W
# Password: mosaic

# Check DATABASE_URL in .env
cat .env | grep DATABASE_URL
```

### Prisma Client Not Generated

```bash
cd apps/api
pnpm prisma:generate

# If still failing, clean and reinstall
rm -rf node_modules
cd ../..
pnpm install
pnpm prisma:generate
```

### Build Errors

```bash
# Clean build cache
rm -rf apps/*/dist packages/*/dist

# Rebuild
pnpm build

# Type check
pnpm typecheck
```

## Next Steps

1. **Configure Authentication** — [Authentik Setup](../3-configuration/2-authentik.md)
2. **Learn the Workflow** — [Development → Workflow](../../2-development/1-workflow/1-branching.md)
3. **Explore the Database** — [Development → Database](../../2-development/2-database/1-schema.md)
4. **Review API Docs** — [API → Conventions](../../4-api/1-conventions/1-endpoints.md)