Create Configuration wiki page for fractafrag
parent
972797dcfc
commit
2e616d25c9
1 changed files with 163 additions and 0 deletions
163
Configuration.md
Normal file
163
Configuration.md
Normal file
|
|
@ -0,0 +1,163 @@
|
|||
# Configuration
|
||||
|
||||
| Meta | Value |
|
||||
|------|-------|
|
||||
| **Repo** | `xpltdco/fractafrag` |
|
||||
| **Page** | `Configuration` |
|
||||
| **Audience** | developers, agents |
|
||||
| **Last Updated** | 2026-04-04 |
|
||||
| **Status** | current |
|
||||
|
||||
## Overview
|
||||
|
||||
Configuration is managed through environment variables defined in `.env` (loaded by Docker Compose). The API service parses settings via Pydantic Settings in `services/api/app/config.py`. The frontend uses Vite environment variables prefixed with `VITE_`.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Database
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `DB_PASS` | Yes | — | PostgreSQL password |
|
||||
| `POSTGRES_USER` | No | `fracta` | PostgreSQL username |
|
||||
| `POSTGRES_DB` | No | `fractafrag` | PostgreSQL database name |
|
||||
| `DATABASE_URL` | Auto | (constructed) | Full connection string: `postgresql+asyncpg://{user}:{pass}@postgres:5432/{db}` |
|
||||
|
||||
### Authentication (JWT)
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `JWT_SECRET` | Yes | — | HMAC signing key (must be 64 hex characters) |
|
||||
| `JWT_ALGORITHM` | No | `HS256` | JWT signing algorithm |
|
||||
| `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` | No | `15` | Access token TTL in minutes |
|
||||
| `JWT_REFRESH_TOKEN_EXPIRE_DAYS` | No | `30` | Refresh token TTL in days |
|
||||
|
||||
### Cloudflare Turnstile (CAPTCHA)
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `TURNSTILE_SITE_KEY` | No | — | Frontend widget key (skipped if not set) |
|
||||
| `TURNSTILE_SECRET` | No | — | Server-side verification key |
|
||||
|
||||
### Stripe (Payments)
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `STRIPE_SECRET_KEY` | For M4 | — | Stripe API secret key |
|
||||
| `STRIPE_PUBLISHABLE_KEY` | For M4 | — | Stripe public key (frontend) |
|
||||
| `STRIPE_WEBHOOK_SECRET` | For M4 | — | Webhook signature verification |
|
||||
|
||||
### AI Providers
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `ANTHROPIC_API_KEY` | For AI gen | — | Claude API key (platform default) |
|
||||
| `OPENAI_API_KEY` | For AI gen | — | GPT API key (platform default) |
|
||||
| `BYOK_MASTER_KEY` | For BYOK | — | Encryption key for user-provided AI keys (32 hex chars) |
|
||||
|
||||
### MCP Server
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `MCP_API_KEY_SALT` | No | — | HMAC salt for MCP client key authentication |
|
||||
|
||||
### Renderer
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `MAX_RENDER_DURATION` | No | `8` | Max seconds to render a shader |
|
||||
| `RENDER_OUTPUT_DIR` | No | `/renders` | Volume mount path for render output |
|
||||
| `RENDERER_URL` | No | `http://renderer:3100` | Renderer service endpoint (used by worker) |
|
||||
|
||||
### Redis
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `REDIS_URL` | No | `redis://redis:6379/0` | Redis connection string |
|
||||
|
||||
### Frontend (Vite)
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `VITE_API_URL` | No | `http://localhost/api` | API endpoint for frontend |
|
||||
| `VITE_MCP_URL` | No | `http://localhost/mcp` | MCP server endpoint |
|
||||
|
||||
### Celery Worker
|
||||
|
||||
| Variable | Set In | Default | Description |
|
||||
|----------|--------|---------|-------------|
|
||||
| `CELERY_TASK_TIME_LIMIT` | docker-compose | `120` | Hard kill after N seconds |
|
||||
| `CELERY_TASK_SOFT_TIME_LIMIT` | docker-compose | `90` | Soft warning at N seconds |
|
||||
| `CELERY_WORKER_PREFETCH_MULTIPLIER` | docker-compose | `1` | Tasks fetched per worker |
|
||||
| `CELERY_WORKER_MAX_TASKS_PER_CHILD` | docker-compose | `100` | Worker recycling threshold |
|
||||
|
||||
## PostgreSQL Extensions
|
||||
|
||||
Enabled in `db/init.sql`:
|
||||
|
||||
| Extension | Purpose |
|
||||
|-----------|---------|
|
||||
| `uuid-ossp` | UUID generation (`gen_random_uuid()`) |
|
||||
| `vector` | pgvector for similarity search (512-dim) |
|
||||
| `pg_trgm` | Trigram text search on titles and prompts |
|
||||
|
||||
## Redis Configuration
|
||||
|
||||
Set via Docker Compose command:
|
||||
|
||||
| Setting | Value | Purpose |
|
||||
|---------|-------|---------|
|
||||
| `appendonly` | `yes` | AOF persistence enabled |
|
||||
| `maxmemory` | `256mb` | Memory cap |
|
||||
| `maxmemory-policy` | `allkeys-lru` | Evict least-recently-used keys |
|
||||
|
||||
## Subscription Tiers
|
||||
|
||||
Configured in the application (not environment):
|
||||
|
||||
| Tier | Shader Limit | Desires | AI Gen | API Keys | BYOK |
|
||||
|------|-------------|---------|--------|----------|------|
|
||||
| `free` | 5/month | Read only | No | No | No |
|
||||
| `pro` | Unlimited | Create + tip | Yes (credits) | Yes | Yes |
|
||||
| `studio` | Unlimited | Create + tip | Yes (unlimited) | Yes | Yes |
|
||||
|
||||
## Example .env File
|
||||
|
||||
```env
|
||||
# Database
|
||||
DB_PASS=your-secure-database-password
|
||||
POSTGRES_USER=fracta
|
||||
POSTGRES_DB=fractafrag
|
||||
|
||||
# JWT (generate with: openssl rand -hex 32)
|
||||
JWT_SECRET=your-64-hex-character-jwt-secret-key-here-must-be-exactly-64chars
|
||||
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=15
|
||||
JWT_REFRESH_TOKEN_EXPIRE_DAYS=30
|
||||
|
||||
# Cloudflare Turnstile (optional in dev)
|
||||
# TURNSTILE_SITE_KEY=your-site-key
|
||||
# TURNSTILE_SECRET=your-secret-key
|
||||
|
||||
# Stripe (optional until M4)
|
||||
# STRIPE_SECRET_KEY=sk_test_...
|
||||
# STRIPE_PUBLISHABLE_KEY=pk_test_...
|
||||
# STRIPE_WEBHOOK_SECRET=whsec_...
|
||||
|
||||
# AI Providers (optional until M5)
|
||||
# ANTHROPIC_API_KEY=sk-ant-...
|
||||
# OPENAI_API_KEY=sk-...
|
||||
# BYOK_MASTER_KEY=your-32-hex-char-master-key
|
||||
|
||||
# MCP
|
||||
# MCP_API_KEY_SALT=your-hmac-salt
|
||||
|
||||
# Renderer
|
||||
MAX_RENDER_DURATION=8
|
||||
|
||||
# Redis
|
||||
REDIS_URL=redis://redis:6379/0
|
||||
|
||||
# Frontend
|
||||
VITE_API_URL=http://localhost/api
|
||||
VITE_MCP_URL=http://localhost/mcp
|
||||
```
|
||||
Loading…
Add table
Reference in a new issue