stack/docs/1-getting-started/2-installation/2-local-setup.md

Local Setup

Native installation for active development with hot reload and debugging.

Prerequisites

Complete Prerequisites first.

Step 1: Clone Repository

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

Step 2: Install Dependencies

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

# Copy environment template
cp .env.example .env

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

Minimum required configuration:

# 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 for complete reference.

Step 4: Setup PostgreSQL Database

Create Database and User

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

# Start only PostgreSQL
docker compose up -d postgres

# Wait for it to be ready
sleep 5

Step 5: Run Database Migrations

# 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

# Start all services
pnpm dev

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

Or start individually:

# API only
pnpm dev:api

# Web only (when implemented)
pnpm dev:web

Step 7: Verify Installation

Check API Health

curl http://localhost:3001/health

Expected response:

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

Run Tests

pnpm test

Expected output:

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

Open Prisma Studio

cd apps/api
pnpm prisma:studio

# Opens at http://localhost:5555

Development Workflow

File Watching

The development servers automatically reload when you make changes:

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

# Changes trigger automatic restart

Running Specific Tests

# 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

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

# Find process using port
lsof -i :3001

# Kill process
kill -9 <PID>

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

PostgreSQL Connection Failed

# 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

cd apps/api
pnpm prisma:generate

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

Build Errors

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

# Rebuild
pnpm build

# Type check
pnpm typecheck

Next Steps

1. Configure Authentication — Authentik Setup
2. Learn the Workflow — Development → Workflow
3. Explore the Database — Development → Database
4. Review API Docs — API → Conventions