Configuration

import { Aside } from ‘@astrojs/starlight/components’;

OpenSNS is configured through environment variables. This guide covers all available options.

Quick Setup

Docker (Recommended)

cp .env.example .env
# Edit .env with your settings

Manual Setup

# Backend
cp backend/.env.example backend/.env

# Frontend
cp frontend/.env.example frontend/.env.local

Required Variables

These must be set before starting OpenSNS:

Variable	Description	How to Generate
`JWT_SECRET_KEY`	Secret for JWT tokens (min 32 chars)	`openssl rand -hex 32`
`API_KEY_ENCRYPTION_KEY`	Key for encrypting stored API keys	`openssl rand -hex 32`

Database

Variable	Description	Default
`DATABASE_URL`	Database connection string	`sqlite:///./opensns.db`

For PostgreSQL (recommended for production):

DATABASE_URL=postgresql://user:password@localhost:5432/opensns

AI Engine API Keys

These can be set globally (in .env) or per-user (in Settings UI):

LLM & Image Engines

Variable	Description
`OPENAI_API_KEY`	OpenAI API key for GPT models
`FAL_KEY`	Fal.ai API key for image/video generation

UGC Video Engines

Variable	Description
`HEYGEN_API_KEY`	HeyGen API key for AI avatar videos
`DID_API_KEY`	D-ID API key for AI avatar videos
`SADTALKER_URL`	Self-hosted SadTalker endpoint URL

Default Engine Selection

Variable	Options	Default
`DEFAULT_LLM_ENGINE`	`openai`, `ollama`, `mock`	`openai`
`DEFAULT_IMAGE_ENGINE`	`fal`, `flux-pro`, `comfyui`	`fal`
`DEFAULT_VIDEO_ENGINE`	`fal-video`, `runway`, `comfyui-video`	`fal-video`
`DEFAULT_UGC_ENGINE`	`heygen`, `d-id`, `sadtalker`	`heygen`

Local/Self-hosted Engine URLs

For self-hosted AI backends:

Variable	Description	Default
`OLLAMA_URL`	Ollama API endpoint	`http://localhost:11434`
`COMFYUI_URL`	ComfyUI WebSocket URL	`http://localhost:8188`
`SADTALKER_URL`	SadTalker API endpoint	(none)

Frontend Configuration

Variable	Description	Default
`NEXT_PUBLIC_API_URL`	Backend API URL	`http://localhost:8000`
`NEXT_PUBLIC_WS_URL`	WebSocket URL for real-time logs	`ws://localhost:8000`

CORS & URLs

Variable	Description	Default
`FRONTEND_URL`	Frontend URL (for email links)	`http://localhost:3000`
`CORS_ORIGINS`	Allowed CORS origins (comma-separated)	`http://localhost:3000`

Billing (Paddle)

Variable	Description
`PADDLE_API_KEY`	Paddle API key
`PADDLE_WEBHOOK_SECRET`	Paddle webhook secret
`PADDLE_ENVIRONMENT`	`sandbox` or `production`
`PADDLE_PRICE_ID_BASIC`	Price ID for Basic plan
`PADDLE_PRICE_ID_PRO`	Price ID for Pro plan
`PADDLE_PRICE_ID_ULTRA`	Price ID for Ultra plan
`PADDLE_PRICE_ID_CREDITS_50`	Price ID for 50 credits pack
`PADDLE_PRICE_ID_CREDITS_150`	Price ID for 150 credits pack
`PADDLE_PRICE_ID_CREDITS_500`	Price ID for 500 credits pack

Email (Resend)

Variable	Description
`RESEND_API_KEY`	Resend API key for transactional emails
`EMAIL_FROM`	Sender email address (e.g., `OpenSNS <noreply@yourdomain.com>`)

OAuth

Google

Variable	Description
`GOOGLE_CLIENT_ID`	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret

Full Example

Docker (.env in project root)

# ===========================================
# REQUIRED
# ===========================================
JWT_SECRET_KEY=your-64-char-hex-key-from-openssl-rand
API_KEY_ENCRYPTION_KEY=your-64-char-hex-key-from-openssl-rand

# ===========================================
# AI ENGINES (optional - users can set in UI)
# ===========================================
OPENAI_API_KEY=sk-...
FAL_KEY=...

# UGC Video
HEYGEN_API_KEY=...
DID_API_KEY=...

# ===========================================
# DEFAULT ENGINES
# ===========================================
DEFAULT_LLM_ENGINE=openai
DEFAULT_IMAGE_ENGINE=fal
DEFAULT_VIDEO_ENGINE=fal-video
DEFAULT_UGC_ENGINE=heygen

# ===========================================
# URLS (change for production)
# ===========================================
FRONTEND_URL=http://localhost:3000
CORS_ORIGINS=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000

Backend (backend/.env)

DATABASE_URL=sqlite:///./opensns.db

JWT_SECRET_KEY=your-secret-key
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=10080

API_KEY_ENCRYPTION_KEY=your-encryption-key

OPENAI_API_KEY=sk-...
FAL_KEY=...

DEFAULT_LLM_ENGINE=openai
DEFAULT_IMAGE_ENGINE=fal
DEFAULT_VIDEO_ENGINE=fal-video
DEFAULT_UGC_ENGINE=heygen

Frontend (frontend/.env.local)

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000

Security Best Practices

Never commit .env files - They’re in .gitignore by default
Use strong random keys - Generate with openssl rand -hex 32
Rotate keys periodically - Especially JWT_SECRET_KEY
Use PostgreSQL in production - SQLite is for development only
Enable HTTPS - Required for secure cookie handling
Restrict CORS origins - Only allow your actual frontend domain

Next Steps

Docker Deployment - Deploy with Docker Compose
Production Deployment - HTTPS, security hardening
Architecture Overview - Understand the system