Skip to main content
Evaly requires environment variables for both the frontend application and the Convex backend. This guide covers all necessary configuration.

​
Frontend Environment Variables

Frontend environment variables are stored in a .env.local file in the root directory.

​
Required Variables

# Convex Deployment
CONVEX_DEPLOYMENT=your-convex-deployment-name
The .env.local file is automatically created when you run npx convex dev for the first time. The Convex CLI will populate it with your deployment name.

​
Backend Environment Variables

Backend environment variables are configured in your Convex deployment. You can set them through the Convex Dashboard or using the Convex CLI.

​
Authentication

Evaly uses Convex Auth with Google OAuth for authentication. 
# Set up Google OAuth credentials
npx convex env set AUTH_GOOGLE_ID your-google-client-id
npx convex env set AUTH_GOOGLE_SECRET your-google-client-secret

# Application URL for OAuth redirects
npx convex env set SITE_URL http://localhost:3000
1

Create Google OAuth Credentials

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Navigate to APIs & Services > Credentials
  4. Click Create Credentials > OAuth 2.0 Client ID
  5. Configure the consent screen if prompted
  6. Set Application type to Web application
  7. Add authorized redirect URIs:
    • http://localhost:3000/api/auth/callback/google (development)
    • https://yourdomain.com/api/auth/callback/google (production)
2

Copy Credentials to Convex

Copy the Client ID and Client Secret and set them as environment variables:
npx convex env set AUTH_GOOGLE_ID <your-client-id>
npx convex env set AUTH_GOOGLE_SECRET <your-client-secret>

​
File Storage (Cloudflare R2)

Evaly uses Cloudflare R2 for file storage. This is required for uploading images in questions and handling file attachments. 
# R2 Access Credentials
npx convex env set R2_ACCESS_KEY_ID your-r2-access-key-id
npx convex env set R2_SECRET_ACCESS_KEY your-r2-secret-access-key

# R2 Bucket Configuration
npx convex env set R2_BUCKET your-bucket-name
npx convex env set R2_ENDPOINT https://your-account-id.r2.cloudflarestorage.com

# Public CDN URL for serving files
npx convex env set R2_CDN_URL https://your-cdn-url.com
npx convex env set R2_TOKEN your-r2-api-token
1

Create R2 Bucket

  1. Log in to Cloudflare Dashboard
  2. Go to R2 in the sidebar
  3. Click Create bucket
  4. Choose a bucket name (e.g., evaly-uploads)
  5. Select a location and create the bucket
2

Generate API Token

  1. In the R2 dashboard, click Manage R2 API Tokens
  2. Click Create API Token
  3. Set permissions to Object Read & Write
  4. Scope it to your bucket
  5. Copy the Access Key ID, Secret Access Key, and Endpoint URL
3

Set Up Public Access (Optional)

For public file access, connect your bucket to a custom domain:
  1. Go to your bucket settings
  2. Click Connect Domain
  3. Add your domain (e.g., cdn.yourdomain.com)
  4. Update your DNS records as instructed
  5. Use this domain as your R2_CDN_URL
Alternatively, you can enable public access directly on the bucket and use the R2.dev domain.

​
Email Service (Plunk)

Evaly uses Plunk for sending transactional emails (invitations, password resets, notifications). 
# Plunk API Configuration
npx convex env set PLUNK_SECRET_API_KEY your-plunk-api-key
npx convex env set PLUNK_API_URL https://api.useplunk.com
npx convex env set PLUNK_FROM_EMAIL [email protected]
1

Create Plunk Account

  1. Sign up at useplunk.com
  2. Verify your sending domain
  3. Copy your API key from the dashboard
2

Configure Environment Variables

Set the Plunk credentials in your Convex deployment:
npx convex env set PLUNK_SECRET_API_KEY <your-api-key>
npx convex env set PLUNK_API_URL https://api.useplunk.com
npx convex env set PLUNK_FROM_EMAIL [email protected]
Email sending is optional for development. If not configured, the system will log a warning but continue functioning. Emails simply won’t be sent.

​
AI Question Generation (Google Gemini)

Evaly can generate questions using AI. This requires a Google Gemini API key. 
# AI API Key
npx convex env set GOOGLE_GENERATIVE_AI_API_KEY your-gemini-api-key
1

Get Gemini API Key

  1. Go to Google AI Studio
  2. Sign in with your Google account
  3. Click Get API Key or Create API Key
  4. Copy the generated API key
2

Set Environment Variable

npx convex env set GOOGLE_GENERATIVE_AI_API_KEY <your-api-key>
AI question generation will not work without this API key. The feature will be disabled in the UI if the key is not configured.

​
JWT Configuration (Auto-Generated)

These variables are automatically generated by Convex Auth. Do not set these manually unless migrating from another deployment. 
JWKS=<auto-generated-by-convex-auth>
JWT_PRIVATE_KEY=<auto-generated-by-convex-auth>

​
Complete Configuration Example

Here’s a complete example of all environment variables: 
# Authentication
npx convex env set AUTH_GOOGLE_ID 123456789.apps.googleusercontent.com
npx convex env set AUTH_GOOGLE_SECRET GOCSPX-abc123def456
npx convex env set SITE_URL http://localhost:3000

# File Storage (Cloudflare R2)
npx convex env set R2_ACCESS_KEY_ID abc123def456
npx convex env set R2_SECRET_ACCESS_KEY xyz789
npx convex env set R2_BUCKET evaly-uploads-dev
npx convex env set R2_ENDPOINT https://1234567890.r2.cloudflarestorage.com
npx convex env set R2_CDN_URL https://cdn-dev.evaly.io
npx convex env set R2_TOKEN abc123token

# Email Service (Plunk)
npx convex env set PLUNK_SECRET_API_KEY sk_abc123
npx convex env set PLUNK_API_URL https://api.useplunk.com
npx convex env set PLUNK_FROM_EMAIL [email protected]

# AI Question Generation
npx convex env set GOOGLE_GENERATIVE_AI_API_KEY AIzaSyAbc123Def456

​
Managing Environment Variables

​
View All Variables

npx convex env list

​
Update a Variable

npx convex env set VARIABLE_NAME new-value

​
Remove a Variable

npx convex env remove VARIABLE_NAME

​
Switch Between Deployments

Convex allows you to have multiple deployments (dev, staging, production): 
# Deploy to production
npx convex deploy --prod

# Set production-specific variables
npx convex env set SITE_URL https://evaly.io --prod

​
Environment-Specific Configuration

​
Development

  • Use http://localhost:3000 for SITE_URL
  • Use separate R2 buckets for development
  • Consider using test API keys where available

​
Production

  • Use your production domain for SITE_URL
  • Use production R2 buckets with CDN
  • Ensure all API keys are production-ready
  • Set up proper monitoring and logging

​
Security Best Practices

Never commit sensitive environment variables to version control. All environment variables contain sensitive credentials and should be kept secure.
  • Use different credentials for development and production
  • Rotate API keys regularly
  • Use Convex’s built-in environment variable management instead of .env files for the backend
  • Restrict R2 bucket permissions to only what’s needed
  • Monitor API usage to detect unauthorized access

​
Troubleshooting

​
Authentication Not Working

  • Verify OAuth redirect URIs match exactly
  • Check that SITE_URL matches your application URL
  • Ensure Google OAuth consent screen is configured

​
File Uploads Failing

  • Verify R2 credentials are correct
  • Check bucket permissions allow read/write
  • Ensure R2_CDN_URL is accessible publicly

​
Emails Not Sending

  • Verify Plunk API key is valid
  • Check that sending domain is verified in Plunk
  • Review Plunk dashboard for delivery errors

​
AI Generation Not Available

  • Ensure GOOGLE_GENERATIVE_AI_API_KEY is set
  • Verify the API key has proper permissions
  • Check Google AI Studio quota limits

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us