Environment Variables Reference

Environment variables are configuration values set outside your code that control how Supamode connects to Supabase, handles authentication, and behaves in different environments. They keep secrets out of your codebase and allow the same code to run in development and production.

Supamode uses environment variables to configure both the frontend (Vite) and backend (Hono API). This reference covers all available variables, their purposes, and example values.

Quick Setup

For local development, copy the template files and fill in your values:

# Frontend
cp apps/app/.env.template apps/app/.env
# Backend
cp apps/api/.env.template apps/api/.env

Frontend Variables (apps/app/.env)

These variables configure the React frontend. Variables prefixed with VITE_ are exposed to the browser.

Required

Optional

Example .env File

# Required
VITE_SUPABASE_URL=http://localhost:54331
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
VITE_SITE_URL=http://localhost:5173
# Optional
VITE_OAUTH_PROVIDERS=google,github
VITE_DEFAULT_THEME=dark
VITE_ENABLE_VERSION_CHECK=false

Backend Variables (apps/api/.env)

These variables configure the Hono API server.

Required

Optional

Example .env File

# Required
SUPABASE_URL=http://localhost:54331
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54332/postgres
APP_URL=http://localhost:5173
# Optional
PERF_LOG_LEVEL=off

Production Configuration

For production deployments, use your hosted Supabase project credentials.

Frontend (Production)

VITE_SUPABASE_URL=https://YOUR_PROJECT_ID.supabase.co
VITE_SUPABASE_ANON_KEY=your-production-anon-key
VITE_SITE_URL=https://admin.yourdomain.com
VITE_OAUTH_PROVIDERS=google
VITE_ENABLE_VERSION_CHECK=true

Backend (Production)

SUPABASE_URL=https://YOUR_PROJECT_ID.supabase.co
SUPABASE_ANON_KEY=your-production-anon-key
SERVICE_ROLE_KEY=your-production-service-role-key
SUPABASE_DATABASE_URL=postgresql://postgres:PASSWORD@db.YOUR_PROJECT_ID.supabase.co:5432/postgres
APP_URL=https://admin.yourdomain.com

Finding Your Supabase Credentials

Project URL and Anon Key

1. Go to your Supabase dashboard
2. Select your project
3. Navigate to Settings > API
4. Copy the Project URL and anon public key

Service Role Key

1. In Settings > API
2. Under Project API keys, reveal and copy the service_role key

Database URL

1. Navigate to Settings > Database
2. Copy the Connection string (URI format)
3. Replace [YOUR-PASSWORD] with your database password

OAuth Configuration

To enable OAuth providers:

1. Configure providers in your Supabase dashboard (Authentication > Providers)
2. Add provider names to VITE_OAUTH_PROVIDERS

Supported providers:

• google - Google OAuth
• github - GitHub OAuth
• azure - Microsoft Azure AD
• apple - Apple Sign In
• discord - Discord OAuth
• slack - Slack OAuth

Example:

VITE_OAUTH_PROVIDERS=google,github,azure

Captcha Configuration

To enable Cloudflare Turnstile captcha on login:

1. Create a Turnstile widget at Cloudflare Dashboard
2. Add your domain to allowed hostnames
3. Copy the Site Key to VITE_CAPTCHA_SITE_KEY

VITE_CAPTCHA_SITE_KEY=0x4AAAAAAAB...

Platform-Specific Configuration

Vercel

Set environment variables in your Vercel project settings:

1. Go to Settings > Environment Variables
2. Add each variable with appropriate scope (Production, Preview, Development)

Railway

Add environment variables in your Railway service:

1. Go to Variables tab
2. Add variables using the Railway interface or .env file reference

Docker

Pass environment variables via docker-compose.yml:

services:
  api:
    environment:
      - SUPABASE_URL=${SUPABASE_URL}
      - SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY}
      - SERVICE_ROLE_KEY=${SERVICE_ROLE_KEY}
      - SUPABASE_DATABASE_URL=${SUPABASE_DATABASE_URL}
      - APP_URL=${APP_URL}

Or use --env-file:

docker run --env-file .env supamode-api

Troubleshooting

"Invalid API Key"

• Verify the anon key matches your Supabase project
• Ensure there are no trailing spaces or newlines in the key
• Check you're using the correct environment (local vs. production)

"Database Connection Failed"

• Verify the SUPABASE_DATABASE_URL format
• Ensure the password is correct and URL-encoded if it contains special characters
• Check network connectivity to the database

CORS Errors

• Verify APP_URL matches your frontend's actual URL
• Include the protocol (http:// or https://)
• For local development, use http://localhost:5173

OAuth Not Working

• Confirm providers are enabled in Supabase dashboard
• Check VITE_OAUTH_PROVIDERS matches the enabled providers exactly
• Verify redirect URLs are configured in each OAuth provider