phase 5
This commit is contained in:
Danilo Reyes
509
docs/getting-started.md
Normal file
509
docs/getting-started.md
Normal file
@@ -0,0 +1,509 @@
|
||||
# Quickstart Guide: Reference Board Viewer
|
||||
|
||||
**Last Updated:** 2025-11-02
|
||||
**For:** Developers starting implementation
|
||||
**Prerequisites:** Nix installed, basic Git knowledge
|
||||
|
||||
## Overview
|
||||
|
||||
This guide will get you from zero to a running development environment for the Reference Board Viewer in under 10 minutes.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Clone and Enter Development Environment
|
||||
|
||||
```bash
|
||||
# Clone repository (if not already)
|
||||
cd /home/jawz/Development/Projects/personal/webref
|
||||
|
||||
# Enter Nix development shell (from flake.nix)
|
||||
nix develop
|
||||
|
||||
# Verify tools are available
|
||||
python --version # Python 3.12
|
||||
node --version # Node.js 20+
|
||||
psql --version # PostgreSQL client
|
||||
ruff --version # Python linter
|
||||
```
|
||||
|
||||
**What this does:** `flake.nix` provides all dependencies (Python, Node.js, PostgreSQL, MinIO, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Start Development Services
|
||||
|
||||
```bash
|
||||
# Start PostgreSQL and MinIO (managed by Nix)
|
||||
./scripts/dev-services.sh start
|
||||
|
||||
# This will:
|
||||
# - Initialize PostgreSQL database (first time)
|
||||
# - Start PostgreSQL on localhost:5432
|
||||
# - Start MinIO on localhost:9000
|
||||
# - Create the webref bucket
|
||||
# - Set up environment variables
|
||||
|
||||
# Verify services are running
|
||||
./scripts/dev-services.sh status
|
||||
|
||||
# Run migrations
|
||||
cd backend
|
||||
alembic upgrade head
|
||||
cd ..
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Set Up Backend (FastAPI)
|
||||
|
||||
```bash
|
||||
# Create backend directory
|
||||
mkdir -p backend
|
||||
cd backend
|
||||
|
||||
# Initialize uv project
|
||||
uv init
|
||||
|
||||
# Install dependencies (all verified in nixpkgs)
|
||||
uv add fastapi uvicorn sqlalchemy alembic pydantic \
|
||||
python-jose passlib pillow boto3 python-multipart \
|
||||
httpx pytest pytest-cov pytest-asyncio
|
||||
|
||||
# Create basic structure
|
||||
mkdir -p app/{auth,boards,images,database,api,core} tests
|
||||
|
||||
# Create main.py
|
||||
cat > app/main.py << 'EOF'
|
||||
from fastapi import FastAPI
|
||||
from fastapi.middleware.cors import CORSMiddleware
|
||||
|
||||
app = FastAPI(title="Reference Board Viewer API")
|
||||
|
||||
app.add_middleware(
|
||||
CORSMiddleware,
|
||||
allow_origins=["http://localhost:5173"], # Vite dev server
|
||||
allow_credentials=True,
|
||||
allow_methods=["*"],
|
||||
allow_headers=["*"],
|
||||
)
|
||||
|
||||
@app.get("/")
|
||||
async def root():
|
||||
return {"message": "Reference Board Viewer API", "version": "1.0.0"}
|
||||
|
||||
@app.get("/health")
|
||||
async def health():
|
||||
return {"status": "healthy"}
|
||||
EOF
|
||||
|
||||
# Run development server
|
||||
uvicorn app.main:app --reload --port 8000
|
||||
|
||||
# Test: curl http://localhost:8000/
|
||||
```
|
||||
|
||||
**Verify:** Navigate to http://localhost:8000/docs to see auto-generated OpenAPI documentation.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Set Up Frontend (Svelte + Konva)
|
||||
|
||||
```bash
|
||||
# Create frontend directory (in new terminal)
|
||||
cd /home/jawz/Development/Projects/personal/webref
|
||||
mkdir -p frontend
|
||||
cd frontend
|
||||
|
||||
# Initialize SvelteKit project
|
||||
npm create svelte@latest .
|
||||
# Choose: Skeleton project, Yes to TypeScript, Yes to ESLint, Yes to Prettier
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
npm install konva
|
||||
|
||||
# Create basic canvas component
|
||||
mkdir -p src/lib/canvas
|
||||
cat > src/lib/canvas/Board.svelte << 'EOF'
|
||||
<script lang="ts">
|
||||
import { onMount } from 'svelte';
|
||||
import Konva from 'konva';
|
||||
|
||||
let container: HTMLDivElement;
|
||||
let stage: Konva.Stage;
|
||||
|
||||
onMount(() => {
|
||||
stage = new Konva.Stage({
|
||||
container: container,
|
||||
width: window.innerWidth,
|
||||
height: window.innerHeight
|
||||
});
|
||||
|
||||
const layer = new Konva.Layer();
|
||||
stage.add(layer);
|
||||
|
||||
const text = new Konva.Text({
|
||||
text: 'Reference Board Canvas',
|
||||
fontSize: 24,
|
||||
fill: 'black',
|
||||
x: 50,
|
||||
y: 50
|
||||
});
|
||||
|
||||
layer.add(text);
|
||||
layer.draw();
|
||||
});
|
||||
</script>
|
||||
|
||||
<div bind:this={container} class="canvas-container"></div>
|
||||
|
||||
<style>
|
||||
.canvas-container {
|
||||
width: 100%;
|
||||
height: 100vh;
|
||||
background: #f0f0f0;
|
||||
}
|
||||
</style>
|
||||
EOF
|
||||
|
||||
# Update home page
|
||||
cat > src/routes/+page.svelte << 'EOF'
|
||||
<script>
|
||||
import Board from '$lib/canvas/Board.svelte';
|
||||
</script>
|
||||
|
||||
<Board />
|
||||
EOF
|
||||
|
||||
# Run development server
|
||||
npm run dev -- --open
|
||||
|
||||
# Verify: Browser opens to http://localhost:5173
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Start MinIO (Image Storage)
|
||||
|
||||
```bash
|
||||
# In new terminal
|
||||
mkdir -p ~/minio-data
|
||||
|
||||
# Start MinIO
|
||||
minio server ~/minio-data --console-address :9001
|
||||
|
||||
# Access console: http://localhost:9001
|
||||
# Default credentials: minioadmin / minioadmin
|
||||
|
||||
# Create bucket
|
||||
mc alias set local http://localhost:9000 minioadmin minioadmin
|
||||
mc mb local/webref
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Structure After Setup
|
||||
|
||||
```
|
||||
webref/
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ │ ├── main.py ✅ Created
|
||||
│ │ ├── auth/
|
||||
│ │ ├── boards/
|
||||
│ │ ├── images/
|
||||
│ │ ├── database/
|
||||
│ │ └── core/
|
||||
│ ├── tests/
|
||||
│ ├── pyproject.toml ✅ Created by uv
|
||||
│ └── alembic.ini
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── lib/
|
||||
│ │ │ └── canvas/
|
||||
│ │ │ └── Board.svelte ✅ Created
|
||||
│ │ └── routes/
|
||||
│ │ └── +page.svelte ✅ Created
|
||||
│ ├── package.json ✅ Created
|
||||
│ └── vite.config.js
|
||||
├── specs/
|
||||
│ └── 001-reference-board-viewer/
|
||||
│ ├── spec.md ✅ Complete
|
||||
│ ├── plan.md ✅ Complete
|
||||
│ ├── data-model.md ✅ Complete
|
||||
│ ├── tech-research.md ✅ Complete
|
||||
│ └── contracts/
|
||||
│ └── api.yaml ✅ Complete
|
||||
├── shell.nix ✅ Update needed
|
||||
└── flake.nix (To be created)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Commands Reference
|
||||
|
||||
### Backend
|
||||
```bash
|
||||
# All commands run inside nix develop shell
|
||||
|
||||
# Run API server
|
||||
cd backend && uvicorn app.main:app --reload
|
||||
|
||||
# Run tests
|
||||
cd backend && pytest
|
||||
|
||||
# Run with coverage
|
||||
cd backend && pytest --cov=app --cov-report=html
|
||||
|
||||
# Check linting
|
||||
cd backend && ruff check app/
|
||||
|
||||
# Format code
|
||||
cd backend && ruff format app/
|
||||
|
||||
# Run migrations
|
||||
cd backend && alembic upgrade head
|
||||
|
||||
# Create migration
|
||||
cd backend && alembic revision --autogenerate -m "description"
|
||||
```
|
||||
|
||||
### NixOS VM Integration Tests
|
||||
```bash
|
||||
# Run all tests (backend, full-stack, performance, security)
|
||||
nix flake check
|
||||
|
||||
# Run specific test
|
||||
nix build .#checks.x86_64-linux.backend-integration -L
|
||||
nix build .#checks.x86_64-linux.full-stack -L
|
||||
|
||||
# Interactive debugging
|
||||
nix build .#checks.x86_64-linux.backend-integration.driverInteractive
|
||||
./result/bin/nixos-test-driver
|
||||
```
|
||||
|
||||
### Frontend
|
||||
```bash
|
||||
# Run dev server
|
||||
npm run dev
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
|
||||
# Check types
|
||||
npm run check
|
||||
|
||||
# Lint
|
||||
npm run lint
|
||||
|
||||
# Build for production
|
||||
npm run build
|
||||
|
||||
# Preview production build
|
||||
npm run preview
|
||||
```
|
||||
|
||||
### Database
|
||||
```bash
|
||||
# Connect to database
|
||||
psql webref
|
||||
|
||||
# Backup database
|
||||
pg_dump webref > backup.sql
|
||||
|
||||
# Restore database
|
||||
psql webref < backup.sql
|
||||
|
||||
# Reset database
|
||||
dropdb webref && createdb webref
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
### MinIO
|
||||
```bash
|
||||
# List buckets
|
||||
mc ls local/
|
||||
|
||||
# List files in bucket
|
||||
mc ls local/webref/
|
||||
|
||||
# Copy file to bucket
|
||||
mc cp file.jpg local/webref/originals/
|
||||
|
||||
# Remove file
|
||||
mc rm local/webref/originals/file.jpg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Create `.env` file in backend/:
|
||||
|
||||
```bash
|
||||
# Database
|
||||
DATABASE_URL=postgresql://localhost/webref
|
||||
|
||||
# JWT Secret (generate with: openssl rand -hex 32)
|
||||
SECRET_KEY=your-secret-key-here
|
||||
ALGORITHM=HS256
|
||||
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
||||
|
||||
# MinIO
|
||||
MINIO_ENDPOINT=localhost:9000
|
||||
MINIO_ACCESS_KEY=minioadmin
|
||||
MINIO_SECRET_KEY=minioadmin
|
||||
MINIO_BUCKET=webref
|
||||
MINIO_SECURE=false
|
||||
|
||||
# CORS
|
||||
CORS_ORIGINS=["http://localhost:5173"]
|
||||
|
||||
# File Upload
|
||||
MAX_FILE_SIZE=52428800 # 50MB
|
||||
MAX_BATCH_SIZE=524288000 # 500MB
|
||||
ALLOWED_MIME_TYPES=["image/jpeg","image/png","image/gif","image/webp","image/svg+xml"]
|
||||
```
|
||||
|
||||
Create `.env` in frontend/:
|
||||
|
||||
```bash
|
||||
# API endpoint
|
||||
VITE_API_URL=http://localhost:8000/api/v1
|
||||
|
||||
# Feature flags
|
||||
VITE_ENABLE_COMMENTS=true
|
||||
VITE_ENABLE_SLIDESHOW=true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing the Setup
|
||||
|
||||
### 1. Backend Health Check
|
||||
```bash
|
||||
curl http://localhost:8000/health
|
||||
# Expected: {"status":"healthy"}
|
||||
```
|
||||
|
||||
### 2. API Documentation
|
||||
Navigate to: http://localhost:8000/docs
|
||||
|
||||
### 3. Frontend Canvas
|
||||
Navigate to: http://localhost:5173
|
||||
Should see: "Reference Board Canvas" text on grey background
|
||||
|
||||
### 4. Database Connection
|
||||
```bash
|
||||
psql webref -c "SELECT 1;"
|
||||
# Expected: (1 row)
|
||||
```
|
||||
|
||||
### 5. MinIO Console
|
||||
Navigate to: http://localhost:9001
|
||||
Login with: minioadmin / minioadmin
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Nix command not found"
|
||||
```bash
|
||||
# Install Nix
|
||||
curl -L https://nixos.org/nix/install | sh
|
||||
```
|
||||
|
||||
### "Port 8000 already in use"
|
||||
```bash
|
||||
# Find and kill process
|
||||
lsof -i :8000
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
### "PostgreSQL connection refused"
|
||||
```bash
|
||||
# Start PostgreSQL
|
||||
sudo systemctl start postgresql
|
||||
# Or using Nix:
|
||||
pg_ctl -D ./pgdata start
|
||||
```
|
||||
|
||||
### "npm install fails"
|
||||
```bash
|
||||
# Clear npm cache
|
||||
npm cache clean --force
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
### "Python module not found"
|
||||
```bash
|
||||
# Reinstall with uv
|
||||
uv sync
|
||||
# Or exit and re-enter nix shell
|
||||
exit
|
||||
nix develop
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Follow the plan:** See [plan.md](./plan.md) for 16-week implementation timeline
|
||||
2. **Implement authentication:** Week 2 tasks in plan
|
||||
3. **Set up database schema:** Use [data-model.md](./data-model.md) and Alembic
|
||||
4. **Implement API endpoints:** Use [contracts/api.yaml](./contracts/api.yaml) as reference
|
||||
5. **Build canvas components:** Follow Week 5-8 tasks
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Daily workflow:
|
||||
```bash
|
||||
# Morning
|
||||
cd webref
|
||||
nix develop
|
||||
cd backend && uvicorn app.main:app --reload &
|
||||
cd frontend && npm run dev &
|
||||
|
||||
# Work on features...
|
||||
|
||||
# Before commit
|
||||
cd backend && pytest && ruff check app/
|
||||
cd frontend && npm run check && npm run lint
|
||||
|
||||
# Commit
|
||||
git add .
|
||||
git commit -m "feat: description"
|
||||
```
|
||||
|
||||
### Weekly workflow:
|
||||
- Review plan.md progress
|
||||
- Update tests for new features
|
||||
- Check coverage: `pytest --cov`
|
||||
- Update documentation
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- **API Spec:** [contracts/api.yaml](./contracts/api.yaml)
|
||||
- **Data Model:** [data-model.md](./data-model.md)
|
||||
- **Tech Stack:** [tech-research.md](./tech-research.md)
|
||||
- **Nix Verification:** [VERIFICATION-COMPLETE.md](./VERIFICATION-COMPLETE.md)
|
||||
- **Full Plan:** [plan.md](./plan.md)
|
||||
|
||||
**External Docs:**
|
||||
- FastAPI: https://fastapi.tiangolo.com/
|
||||
- Svelte: https://svelte.dev/docs
|
||||
- Konva: https://konvajs.org/docs/
|
||||
- Alembic: https://alembic.sqlalchemy.org/
|
||||
- MinIO: https://min.io/docs/minio/linux/index.html
|
||||
|
||||
---
|
||||
|
||||
**Questions?** Check the specification in [spec.md](./spec.md) or plan in [plan.md](./plan.md).
|
||||
|
||||
**Ready to start?** Begin with Week 1 tasks in the implementation plan!
|
||||
|
||||
Reference in New Issue
Block a user