dd5b3117a7
- Organized docs into numbered shelf/book/chapter/page structure - Created comprehensive README.md with project overview - Added Getting Started book (quick start, installation, configuration) - Added Development book (workflow, testing, type sharing) - Added Architecture book (design principles, PDA-friendly patterns) - Added API Reference book (conventions, authentication) - Moved TYPE-SHARING.md to proper location - Updated all cross-references in main README - Created docs/README.md as master index - Removed old QA automation reports - Removed deprecated SETUP.md (content split into new structure) Documentation structure follows Bookstack best practices: - Numbered books: 1-getting-started, 2-development, 3-architecture, 4-api - Numbered chapters and pages for ordering - Clear hierarchy and navigation - Cross-referenced throughout Complete documentation available at: docs/README.md Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
260 lines
4.2 KiB
Markdown
260 lines
4.2 KiB
Markdown
# 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)
|