Skip to main content

​
Environment Variables

Catafract requires several environment variables to be configured. Create a .env.local file in the project root with the following variables.

​
Required Variables

​
Authentication

​
GOOGLE_CLIENT_ID
string
required
Google OAuth Client ID from Google Cloud ConsoleHow to get:
  1. Go to Google Cloud Console
  2. Navigate to APIs & Services > Credentials
  3. Create OAuth 2.0 Client ID
  4. Copy the Client ID
​
GOOGLE_CLIENT_SECRET
string
required
Google OAuth Client Secret from Google Cloud ConsoleHow to get: Available in the same location as Client ID
​
NEXTAUTH_URL
string
required
The base URL of your applicationDevelopment:
http://localhost:3000
Production:
https://yourdomain.com
​
NEXTAUTH_SECRET
string
required
Secret key for encrypting session tokensGenerate with:
openssl rand -base64 32
Example: abc123xyz789...

​
Azure Storage

​
AZURE_STORAGE_CONNECTION_STRING
string
required
Connection string for Azure Blob StorageFormat:
DefaultEndpointsProtocol=https;AccountName=[account];AccountKey=[key];EndpointSuffix=core.windows.net
How to get:
  1. Go to Azure Portal
  2. Navigate to your Storage Account
  3. Go to Access Keys
  4. Copy Connection String
​
AZURE_COSMOS_CONNECTION_STRING
string
required
Connection string for Azure Cosmos DBFormat:
AccountEndpoint=https://[account].documents.azure.com:443/;AccountKey=[key];
How to get:
  1. Go to Azure Portal
  2. Navigate to your Cosmos DB account
  3. Go to Keys
  4. Copy Primary Connection String

​
AI Model

​
GEMINI_API_KEY
string
required
API key for Google Gemini AIHow to get:
  1. Go to Google AI Studio
  2. Create API Key
  3. Copy the key
Note: This is different from Google Cloud API keys

​
Optional Variables

​
Payment Processing (Polar)

​
NEXT_PUBLIC_SETUP
string
Environment mode for Polar integrationValues:
  • local - Use sandbox mode
  • production - Use production mode
Default: production
​
POLAR_ACCESS_TOKEN
string
Polar production access tokenHow to get:
  1. Sign up at Polar.sh
  2. Go to Settings > API Keys
  3. Create Production Access Token
​
POLAR_SANDBOX_ACCESS_TOKEN
string
Polar sandbox access token for testingHow to get: Same as production token, but select Sandbox mode
​
POLAR_WEBHOOK_SECRET
string
Secret for verifying Polar webhooks (production)How to get:
  1. Go to Polar Settings > Webhooks
  2. Create webhook endpoint
  3. Copy the signing secret
​
POLAR_SANDBOX_WEBHOOK_SECRET
string
Secret for verifying Polar webhooks (sandbox)
​
POLAR_SUCCESS_URL
string
URL to redirect after successful paymentExample:
http://localhost:3000/projects
​
POLAR_RETURN_URL
string
URL to return from customer portalExample:
http://localhost:3000/projects

​
Video Processing (Mux)

​
MUX_TOKEN_ID
string
Mux API Token IDHow to get:
  1. Sign up at Mux
  2. Go to Settings > Access Tokens
  3. Create new token
  4. Copy Token ID
​
MUX_TOKEN_SECRET
string
Mux API Token SecretHow to get: Available when creating the token (copy immediately, not shown again)

​
Analytics (Mixpanel)

​
NEXT_PUBLIC_MIXPANEL_TOKEN
string
Mixpanel project tokenHow to get:
  1. Sign up at Mixpanel
  2. Create a project
  3. Go to Project Settings
  4. Copy Project Token
Note: Must be prefixed with NEXT_PUBLIC_ to be available client-side
​
NEXT_PUBLIC_PROXY_MIXPANEL_API
string
Custom proxy URL for Mixpanel API (optional)Use case: Bypass ad blockers or implement custom trackingDefault: Mixpanel’s default API endpoint

​
Complete Example

# Authentication (Required)
GOOGLE_CLIENT_ID=123456789.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-abc123xyz
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=generatedSecretKey123

# Azure Storage (Required)
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=abc123==;EndpointSuffix=core.windows.net
AZURE_COSMOS_CONNECTION_STRING=AccountEndpoint=https://myaccount.documents.azure.com:443/;AccountKey=xyz789==;

# Google Gemini AI (Required)
GEMINI_API_KEY=AIzaSyAbc123XYZ

# Polar Payment (Optional)
NEXT_PUBLIC_SETUP=local
POLAR_ACCESS_TOKEN=polar_at_prod_abc123
POLAR_SANDBOX_ACCESS_TOKEN=polar_at_sandbox_xyz789
POLAR_WEBHOOK_SECRET=whsec_abc123
POLAR_SANDBOX_WEBHOOK_SECRET=whsec_sandbox_xyz789
POLAR_SUCCESS_URL=http://localhost:3000/projects
POLAR_RETURN_URL=http://localhost:3000/projects

# Mux Video (Optional)
MUX_TOKEN_ID=abc123-token-id
MUX_TOKEN_SECRET=xyz789TokenSecret

# Mixpanel Analytics (Optional)
NEXT_PUBLIC_MIXPANEL_TOKEN=abc123mixpaneltoken
NEXT_PUBLIC_PROXY_MIXPANEL_API=https://api.mixpanel.com

​
Azure Configuration

​
Required Azure Resources

  1. Storage Account
    • Container name: catafract
    • Public access level: Blob (anonymous read access)
  2. Cosmos DB Account
    • API: Core (SQL)
    • Database name: catafract
    • Containers:
      • users (partition key: /email)
      • projects (partition key: /userId)
      • canvas (partition key: /projectId)
      • generations (partition key: /userId)

​
Creating Azure Resources

# Create resource group
az group create --name catafract-rg --location eastus

# Create storage account
az storage account create \
  --name catafractstorage \
  --resource-group catafract-rg \
  --location eastus \
  --sku Standard_LRS

# Create container
az storage container create \
  --name catafract \
  --account-name catafractstorage \
  --public-access blob

# Create Cosmos DB account
az cosmosdb create \
  --name catafract-cosmos \
  --resource-group catafract-rg \
  --locations regionName=eastus

# Create database
az cosmosdb sql database create \
  --account-name catafract-cosmos \
  --resource-group catafract-rg \
  --name catafract

# Create containers
az cosmosdb sql container create \
  --account-name catafract-cosmos \
  --database-name catafract \
  --name users \
  --partition-key-path /email

az cosmosdb sql container create \
  --account-name catafract-cosmos \
  --database-name catafract \
  --name projects \
  --partition-key-path /userId

az cosmosdb sql container create \
  --account-name catafract-cosmos \
  --database-name catafract \
  --name canvas \
  --partition-key-path /projectId

az cosmosdb sql container create \
  --account-name catafract-cosmos \
  --database-name catafract \
  --name generations \
  --partition-key-path /userId

​
Validation

To validate your configuration, run: 
bun run dev
Check the console for any missing environment variable errors. The application will log warnings for optional variables that are not set.

​
Security Best Practices

  • Never commit .env.local to version control
  • Add .env.local to .gitignore
  • Use different credentials for development and production
  • Rotate secrets regularly
  • Use Azure Key Vault for production secrets
  • Enable Azure Storage firewall rules
  • Implement IP restrictions on Cosmos DB
  • Monitor API usage and set up alerts