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

git clone https://git.xpltd.co/xpltdco/fractafrag.git
cd fractafrag

2. Create environment file

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

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

# 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 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)