Environment Variables

Overview

Quail BI uses environment variables for configuration. All variables should be defined in a .env.local file in the project root.

Never commit .env.local to version control. Use .env.example as a template.

Required Variables

These variables must be configured for Quail to function:

Encryption Key

.env.local

NEXT_PUBLIC_ENCRYPTION_KEY=your-32-character-base64-encoded-key

Purpose: Encrypts database connection strings using AES-256-GCM before storing them.

Generate a secure key:

openssl rand -base64 32

The key must be exactly 32 bytes (256 bits) when decoded from base64. If the application throws an encryption error on startup, regenerate the key.

Supabase Configuration

.env.local

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-public-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-secret-key

SUPABASE_URL

Your Supabase project URL from the dashboard

ANON_KEY

Public anonymous key for client-side auth

SERVICE_ROLE_KEY

Secret key for server-side operations

Where to find these:

Open Supabase Dashboard

Navigate to your project at app.supabase.com

Go to Settings

Click Settings in the sidebar, then API

Copy Keys

Copy the Project URL, anon public key, and service_role secret key

MongoDB Configuration

.env.local

MONGODB_URI=mongodb+srv://username:[email protected]/database_name

Purpose: Stores user accounts, database connections (encrypted), dashboards, and chat history.

Connection string format:

MongoDB Atlas
Local MongoDB
Docker MongoDB
With Authentication

mongodb+srv://username:[email protected]/database_name?retryWrites=true&w=majority

mongodb://localhost:27017/quail

mongodb://mongodb:27017/quail

mongodb://username:password@localhost:27017/quail?authSource=admin

Optional Variables

Default Database Connection

.env.local

NEXT_PUBLIC_DEFAULT_DB_CONNECTION_STRING=

Purpose: Optional demo/test database connection string shown to users.

Leave empty in production or provide a read-only demo database.

Azure AI Configuration

.env.local

NEXT_PUBLIC_AZURE_RESOURCE_NAME=your-resource-name
NEXT_PUBLIC_AZURE_API_KEY=your-api-key
NEXT_PUBLIC_AZURE_FUNCTION_ENDPOINT=https://your-function.azurewebsites.net

Purpose: Enables AI-powered features like natural language to SQL, chart generation, and query explanations.

RESOURCE_NAME

Your Azure OpenAI resource name (not the full endpoint URL)

API_KEY

API key from Azure OpenAI resource

FUNCTION_ENDPOINT

Azure Function endpoint for AI processing (optional)

Create Azure OpenAI Resource

In Azure Portal, create an Azure OpenAI resource

Get Resource Name

Copy the resource name (e.g., quail-openai from quail-openai.openai.azure.com)

Get API Key

Copy the API key from Keys and Endpoint in the Azure Portal

Configure Function Endpoint (Optional)

If using Azure Functions for AI processing, set the function app URL

If you don’t configure Azure AI, you can still use Quail, but AI-powered features will be disabled.

Stripe Configuration

.env.local

NEXT_PUBLIC_STRIPE_PK=pk_test_...
STRIPE_SK=sk_test_...
STRIPE_ENDPOINT_SECRET=whsec_...

Purpose: Enables subscription billing and payment processing for Free and Pro tiers.

STRIPE_PK

Publishable key for client-side Stripe integration

STRIPE_SK

Secret key for server-side payment processing

ENDPOINT_SECRET

Webhook secret for validating Stripe events

Quail has two pricing tiers: Free (limited monthly usage) and Pro (unlimited). Stripe integration is required for Pro subscriptions.

Application URL

.env.local

NEXT_PUBLIC_APP_URL=http://localhost:3000

Purpose: Base URL for the application, used for redirects and webhooks.

Change this to your production domain:

NEXT_PUBLIC_APP_URL=https://quail.yourdomain.com

Environment Variable Reference

Complete `.env.local` Template

.env.local

# ========================================
# REQUIRED VARIABLES
# ========================================

# Encryption Key (REQUIRED)
# Generate with: openssl rand -base64 32
NEXT_PUBLIC_ENCRYPTION_KEY=

# Supabase Configuration (REQUIRED)
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
SUPABASE_ADMIN=

# MongoDB Configuration (REQUIRED)
MONGODB_URI=
MONGODB_DB_NAME=quail

# ========================================
# OPTIONAL VARIABLES
# ========================================

# Default Database Connection (optional)
NEXT_PUBLIC_DEFAULT_DB_CONNECTION_STRING=

# Azure AI Configuration (optional)
NEXT_PUBLIC_AZURE_RESOURCE_NAME=
NEXT_PUBLIC_AZURE_API_KEY=
NEXT_PUBLIC_AZURE_FUNCTION_ENDPOINT=

# Stripe Configuration (optional for Free tier, required for Pro)
NEXT_PUBLIC_STRIPE_PK=
STRIPE_SK=
STRIPE_ENDPOINT_SECRET=

# Usage Limits
FREE_TIER_MONTHLY_LIMIT=100

# Application Settings (optional)
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_BASE_URL=http://localhost:3000

Platform-Specific Configuration

Vercel

Add environment variables in the Vercel dashboard:

Open Project Settings

Navigate to your project, then Settings → Environment Variables

Add Each Variable

Add all required variables from your .env.local

Select Environments

Choose Production, Preview, and/or Development

Redeploy

Trigger a new deployment for changes to take effect

Use different values for Production and Preview environments (e.g., separate Supabase projects for staging).

Docker

Pass environment variables to Docker:

.env file
Individual -e flags
Docker Compose

docker run -p 3000:3000 --env-file .env.local quail-bi

docker run -p 3000:3000 \
  -e NEXT_PUBLIC_ENCRYPTION_KEY=your-key \
  -e NEXT_PUBLIC_SUPABASE_URL=https://... \
  -e MONGODB_URI=mongodb+srv://... \
  quail-bi

docker-compose.yml

version: '3.8'
services:
  quail:
    image: quail-bi
    ports:
      - '3000:3000'
    env_file:
      - .env.local

Kubernetes

Use ConfigMaps and Secrets:

kubernetes/secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: quail-secrets
type: Opaque
stringData:
  NEXT_PUBLIC_ENCRYPTION_KEY: your-key
  SUPABASE_SERVICE_ROLE_KEY: your-service-role-key
  MONGODB_URI: mongodb+srv://...
  AZURE_OPENAI_API_KEY: your-api-key
  STRIPE_SECRET_KEY: sk_...
  STRIPE_WEBHOOK_SECRET: whsec_...

kubernetes/configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: quail-config
data:
  NEXT_PUBLIC_SUPABASE_URL: https://your-project.supabase.co
  NEXT_PUBLIC_APP_URL: https://quail.yourdomain.com
  AZURE_OPENAI_ENDPOINT: https://your-resource.openai.azure.com/
  AZURE_OPENAI_DEPLOYMENT_NAME: gpt-4o

kubernetes/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: quail
spec:
  template:
    spec:
      containers:
      - name: quail
        image: quail-bi:latest
        envFrom:
        - configMapRef:
            name: quail-config
        - secretRef:
            name: quail-secrets

AWS, Azure, GCP

AWS
Azure
GCP

Use AWS Systems Manager Parameter Store or Secrets Manager:

# Store secrets
aws secretsmanager create-secret \
  --name quail/encryption-key \
  --secret-string "your-key"

# Reference in application
const key = await getSecretValue('quail/encryption-key');

Use Azure Key Vault:

# Store secrets
az keyvault secret set \
  --vault-name quail-vault \
  --name encryption-key \
  --value "your-key"

# Reference in App Service
@Microsoft.KeyVault(SecretUri=https://quail-vault.vault.azure.net/secrets/encryption-key/)

Use Secret Manager:

# Store secrets
echo -n "your-key" | gcloud secrets create encryption-key \
  --data-file=-

# Grant access
gcloud secrets add-iam-policy-binding encryption-key \
  --member="serviceAccount:[email protected]" \
  --role="roles/secretmanager.secretAccessor"

Security Best Practices

Never expose secret environment variables to the client. Only variables prefixed with NEXT_PUBLIC_ are exposed to the browser.

Use Secret Management

Store secrets in platform-specific secret managers, not in environment files

Rotate Keys Regularly

Change encryption keys and API keys periodically

Use Different Keys per Environment

Never reuse production keys in development or staging

Restrict Access

Limit who can view or modify environment variables

Troubleshooting

Application fails with 'NEXT_PUBLIC_ENCRYPTION_KEY is not defined'

The encryption key is missing or not set correctly:

Verify .env.local exists in the project root
Check the variable name matches exactly: NEXT_PUBLIC_ENCRYPTION_KEY
Ensure there are no spaces around the = sign
Restart the development server after changes

# Generate a new key
openssl rand -base64 32

# Add to .env.local
echo "NEXT_PUBLIC_ENCRYPTION_KEY=$(openssl rand -base64 32)" >> .env.local

Encryption fails with 'Invalid key length'

The encryption key must be exactly 32 bytes when decoded:

# Test key length
echo "your-key" | base64 -d | wc -c
# Should output: 32

# If not 32, regenerate:
openssl rand -base64 32

Environment variables not loading in production

Platform-specific issues:

Vercel: Ensure variables are added in dashboard and deployment is triggered
Docker: Verify --env-file path or -e flags are correct
Kubernetes: Check ConfigMap and Secret are applied and referenced
Others: Ensure environment variables are set before running node server.js

Next Steps

Database Setup

Configure MongoDB and Supabase

Configuration

Advanced configuration options

Security

Secure your environment variables

Troubleshooting

Fix common environment issues

Self-Hosting

Operations

​Overview

​Required Variables

​Encryption Key

​Supabase Configuration

SUPABASE_URL

ANON_KEY

SERVICE_ROLE_KEY

​MongoDB Configuration

​Optional Variables

​Default Database Connection

​Azure AI Configuration

RESOURCE_NAME

API_KEY

FUNCTION_ENDPOINT

​Stripe Configuration

STRIPE_PK

STRIPE_SK

ENDPOINT_SECRET

​Application URL

​Environment Variable Reference

​Complete .env.local Template

​Platform-Specific Configuration

​Vercel

​Docker

​Kubernetes

​AWS, Azure, GCP

​Security Best Practices

Use Secret Management

Rotate Keys Regularly

Use Different Keys per Environment

Restrict Access

​Troubleshooting

​Next Steps

Database Setup

Configuration

Security

Troubleshooting

Build docs developers (and LLMs) love

Overview

Required Variables

Encryption Key

Supabase Configuration

MongoDB Configuration

Optional Variables

Default Database Connection

Azure AI Configuration

Stripe Configuration

Application URL

Environment Variable Reference

Complete `.env.local` Template

Platform-Specific Configuration

Vercel

Docker

Kubernetes

AWS, Azure, GCP

Security Best Practices

Troubleshooting

Next Steps