Configuration - Catafract

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

string

required

Google OAuth Client ID from Google Cloud ConsoleHow to get:

Go to Google Cloud Console
Navigate to APIs & Services > Credentials
Create OAuth 2.0 Client ID
Copy the Client ID

string

required

Google OAuth Client Secret from Google Cloud ConsoleHow to get: Available in the same location as Client ID

string

required

The base URL of your applicationDevelopment:

http://localhost:3000

Production:

https://yourdomain.com

string

required

Secret key for encrypting session tokensGenerate with:

openssl rand -base64 32

Example: abc123xyz789...

Azure Storage

string

required

Connection string for Azure Blob StorageFormat:

DefaultEndpointsProtocol=https;AccountName=[account];AccountKey=[key];EndpointSuffix=core.windows.net

How to get:

Go to Azure Portal
Navigate to your Storage Account
Go to Access Keys
Copy Connection String

string

required

Connection string for Azure Cosmos DBFormat:

AccountEndpoint=https://[account].documents.azure.com:443/;AccountKey=[key];

How to get:

Go to Azure Portal
Navigate to your Cosmos DB account
Go to Keys
Copy Primary Connection String

AI Model

string

required

API key for Google Gemini AIHow to get:

Go to Google AI Studio
Create API Key
Copy the key

Note: This is different from Google Cloud API keys

Optional Variables

Payment Processing (Polar)

string

Environment mode for Polar integrationValues:

local - Use sandbox mode
production - Use production mode

Default: production

string

Polar production access tokenHow to get:

Sign up at Polar.sh
Go to Settings > API Keys
Create Production Access Token

string

Polar sandbox access token for testingHow to get: Same as production token, but select Sandbox mode

string

Secret for verifying Polar webhooks (production)How to get:

Go to Polar Settings > Webhooks
Create webhook endpoint
Copy the signing secret

string

Secret for verifying Polar webhooks (sandbox)

string

URL to redirect after successful paymentExample:

http://localhost:3000/projects

string

URL to return from customer portalExample:

http://localhost:3000/projects

Video Processing (Mux)

string

Mux API Token IDHow to get:

Sign up at Mux
Go to Settings > Access Tokens
Create new token
Copy Token ID

string

Mux API Token SecretHow to get: Available when creating the token (copy immediately, not shown again)

Analytics (Mixpanel)

string

Mixpanel project tokenHow to get:

Sign up at Mixpanel
Create a project
Go to Project Settings
Copy Project Token

Note: Must be prefixed with NEXT_PUBLIC_ to be available client-side

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

Storage Account
- Container name: catafract
- Public access level: Blob (anonymous read access)
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

​Environment Variables

​Required Variables

​Authentication

​Azure Storage

​AI Model

​Optional Variables

​Payment Processing (Polar)

​Video Processing (Mux)

​Analytics (Mixpanel)

​Complete Example

​Azure Configuration

​Required Azure Resources

​Creating Azure Resources

​Validation

​Security Best Practices

Environment Variables

Required Variables

Authentication

Azure Storage

AI Model

Optional Variables

Payment Processing (Polar)

Video Processing (Mux)

Analytics (Mixpanel)

Complete Example

Azure Configuration

Required Azure Resources

Creating Azure Resources

Validation

Security Best Practices