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