Create Getting-Started wiki page for fractafrag

Getting-Started.-.md

@@ -0,0 +1,152 @@
+# Getting Started
+
+| Meta | Value |
+|------|-------|
+| **Repo** | `xpltdco/fractafrag` |
+| **Page** | `Getting-Started` |
+| **Audience** | developers, newcomers |
+| **Last Updated** | 2026-04-04 |
+| **Status** | current |
+
+## Prerequisites
+
+| Requirement | Version | Purpose |
+|-------------|---------|---------|
+| **Docker** | >= 24.0 | Container runtime |
+| **Docker Compose** | >= 2.20 | Multi-service orchestration |
+| **Git** | Any | Clone repository |
+
+> Everything runs in Docker — no local Python, Node.js, or PostgreSQL needed.
+
+### Optional (for local development outside Docker)
+
+| Requirement | Version | Purpose |
+|-------------|---------|---------|
+| **Python** | >= 3.12 | API development |
+| **Node.js** | >= 20 | Frontend development |
+| **PostgreSQL** | 16 | Database (or use docker-compose.dev.yml) |
+| **Redis** | 7 | Cache/queue (or use docker-compose.dev.yml) |
+
+## Quick Start (Docker)
+
+### 1. Clone the repository
+
+```bash
+git clone https://git.xpltd.co/xpltdco/fractafrag.git
+cd fractafrag
+```
+
+### 2. Create environment file
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and set at minimum:
+- `DB_PASS` — PostgreSQL password (choose any secure password)
+- `JWT_SECRET` — 64 hex characters for JWT signing (generate with `openssl rand -hex 32`)
+
+### 3. Start all services
+
+```bash
+make up
+# or: docker compose up -d
+```
+
+This builds and starts all 8 services. First build takes a few minutes (Chromium install in renderer).
+
+### 4. Access the application
+
+| Service | URL |
+|---------|-----|
+| **Frontend** | http://localhost |
+| **API Docs (Swagger)** | http://localhost/api/docs |
+| **API Docs (ReDoc)** | http://localhost/api/redoc |
+| **Health Check** | http://localhost/health |
+
+The database schema is automatically created from `db/init.sql` on first startup.
+
+## Development Setup (Hot Reload)
+
+The `docker-compose.override.yml` file is automatically picked up and enables:
+- **API:** Volume mount + `--reload` flag (changes to `services/api/` auto-restart)
+- **Frontend:** Vite dev server with HMR (instant browser refresh)
+- **MCP:** Volume mount for live changes
+- **All services:** Exposed ports for direct access
+
+```bash
+# Start with dev overrides (automatic)
+docker compose up -d
+
+# Or start only data stores and run API/frontend locally
+docker compose -f docker-compose.dev.yml up -d
+cd services/api && pip install -e ".[dev]" && uvicorn app.main:app --reload
+cd services/frontend && npm install && npm run dev
+```
+
+## Environment Variables
+
+See the full [Configuration](Configuration) page. The essentials:
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `DB_PASS` | Yes | PostgreSQL password |
+| `JWT_SECRET` | Yes | JWT signing key (64 hex chars) |
+| `TURNSTILE_SITE_KEY` | For CAPTCHA | Cloudflare Turnstile public key |
+| `TURNSTILE_SECRET` | For CAPTCHA | Cloudflare Turnstile server key |
+| `STRIPE_SECRET_KEY` | For payments | Stripe API key |
+| `ANTHROPIC_API_KEY` | For AI gen | Claude API key |
+| `OPENAI_API_KEY` | For AI gen | GPT API key |
+
+## Common Commands (Makefile)
+
+| Command | Purpose |
+|---------|---------|
+| `make up` | Start all services |
+| `make down` | Stop all services |
+| `make build` | Rebuild all Docker images |
+| `make logs` | Stream all service logs |
+| `make test` | Run API test suite |
+| `make api-shell` | Bash shell inside API container |
+| `make worker-shell` | Bash shell inside worker container |
+| `make db-shell` | PostgreSQL shell (`psql -U fracta -d fractafrag`) |
+
+## Service Ports (Development)
+
+| Service | Port | Direct URL |
+|---------|------|-----------|
+| nginx | 80 | http://localhost |
+| api | 8000 | http://localhost:8000 |
+| frontend | 5173 | http://localhost:5173 |
+| mcp | 3200 | http://localhost:3200 |
+| renderer | 3100 | http://localhost:3100 |
+| postgres | 5432 | `psql -h localhost -U fracta -d fractafrag` |
+| redis | 6379 | `redis-cli -h localhost` |
+
+## Troubleshooting
+
+### Renderer fails to start / Chromium crashes
+- Ensure `shm_size: '512mb'` is set in docker-compose.yml for the renderer service
+- Check renderer logs: `docker compose logs renderer`
+- The renderer needs software GL (SwiftShader) — hardware GPU passthrough is not required
+
+### Database connection errors
+- Wait for PostgreSQL to be healthy: `docker compose ps` should show `healthy` for postgres
+- The API depends on postgres being healthy before starting
+- Check postgres logs: `docker compose logs postgres`
+
+### Port conflicts
+- The default setup uses port 80 (nginx). If something else uses port 80, edit `docker-compose.yml` to change the nginx port mapping (e.g., `8080:80`)
+
+### Redis memory warnings
+- Redis is configured with 256MB max and LRU eviction. This is sufficient for development.
+- If you see memory warnings in production, increase `--maxmemory` in the redis command
+
+### CAPTCHA not working in development
+- Turnstile verification is skipped if `TURNSTILE_SECRET` is not set in `.env`
+- For local dev, you can leave it blank
+
+### Frontend blank page
+- Check that nginx is routing correctly: `docker compose logs nginx`
+- In dev mode, the frontend runs on Vite's dev server (port 5173)
+- Make sure `VITE_API_URL` is set correctly (default: `http://localhost/api`)