Auth Environment Setup Guide

Overview

This guide walks through setting up the environment for the auth.do.dev unified authentication service and integrating it with multiple Convex deployments.

Environment Structure

Multiple Convex Deployments

The project uses multiple Convex deployments for different purposes:

Auth Deployment - Centralized authentication
App Data Deployments - Application-specific data

Root Project
├── .env.local (shared environment variables)
├── apps/
│   ├── auth/        (uses AUTH deployment)
│   ├── dodev/       (uses original deployment)
│   ├── local-test/  (uses LOCAL deployment)
│   └── [other apps]

Step-by-Step Setup

1. Root Environment Configuration

Create or update .env.local in the project root:

# Copy the example file
cp .env.local.example .env.local

# Edit with your values
nano .env.local

Required variables:

# Auth Convex Deployment
CONVEX_DEPLOYMENT_AUTH="dev:dependable-pika-747"
NEXT_PUBLIC_CONVEX_URL_AUTH="https://dependable-pika-747.convex.cloud"

# Email Service
RESEND_API_KEY="your-resend-api-key"
AUTH_RESEND_FROM="hello@do.dev"

# OAuth Providers (optional for testing)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

# Main App Deployment (existing)
NEXT_PUBLIC_CONVEX_URL="https://standing-bird-371.convex.cloud"

# Local Infrastructure Deployment (existing)
NEXT_PUBLIC_CONVEX_DEPLOYMENT_LOCAL="https://agile-cardinal-285.convex.cloud"

2. Auth App Configuration

Create apps/auth/.env.local:

# Auth-specific configuration
CONVEX_DEPLOYMENT=dependable-pika-747
NEXT_PUBLIC_CONVEX_URL=https://dependable-pika-747.convex.cloud

# Next.js configuration
NEXT_PUBLIC_URL=http://localhost:3030

3. Individual App Configuration

Each app maintains its own Convex deployment:

dodev App

# apps/dodev/.env.local
CONVEX_DEPLOYMENT=standing-bird-371
NEXT_PUBLIC_CONVEX_URL=https://standing-bird-371.convex.cloud

local-test App

# apps/local-test/.env.local  
CONVEX_DEPLOYMENT=agile-cardinal-285
NEXT_PUBLIC_CONVEX_URL=https://agile-cardinal-285.convex.cloud

Convex Environment Variables

Auth Deployment (dependable-pika-747)

Set these in the Convex dashboard:

# Email Provider
RESEND_API_KEY=re_xxxxxxxxxxxx
AUTH_RESEND_FROM=auth@notifications.do.dev

# OAuth Providers
AUTH_GITHUB_ID=xxxxxxxxxxxx
AUTH_GITHUB_SECRET=xxxxxxxxxxxx
AUTH_GOOGLE_ID=xxxxxxxxxxxx.apps.googleusercontent.com
AUTH_GOOGLE_SECRET=xxxxxxxxxxxx

# Security
JWT_SECRET=your-random-jwt-secret-string

App Data Deployments

Each app deployment only needs app-specific variables:

# Example for dodev deployment
DATABASE_URL=your-database-url
STRIPE_SECRET_KEY=your-stripe-key
# etc.

Development Workflow

Starting Services

# Terminal 1: Auth Convex backend
cd apps/auth
npx convex dev

# Terminal 2: Auth Next.js frontend  
cd apps/auth
pnpm dev --port 3030

# Terminal 3: Main app (dodev)
cd apps/dodev  
pnpm dev --port 3005

# Terminal 4: Other apps as needed
cd apps/local-test
pnpm dev --port 3001

Environment Validation

Create a validation script:

// scripts/validate-env.ts
const requiredVars = [
  'CONVEX_DEPLOYMENT_AUTH',
  'NEXT_PUBLIC_CONVEX_URL_AUTH',
  'RESEND_API_KEY',
];

for (const varName of requiredVars) {
  if (!process.env[varName]) {
    console.error(`❌ Missing required environment variable: ${varName}`);
    process.exit(1);
  }
}

console.log('✅ All required environment variables are set');

Run validation:

npx tsx scripts/validate-env.ts

Port Configuration

Development Ports

Auth Service: 3030
dodev App: 3005
local-test App: 3001
Other apps: 3002, 3003, 3004, etc.

Production URLs

Auth Service: https://auth.do.dev
dodev App: https://do.dev
Other apps: https://app-name.do.dev

Troubleshooting

Common Issues

"Cannot find module 'convex'"

# Install dependencies in each app
cd apps/auth && pnpm install
cd apps/dodev && pnpm install

"Deployment not found"

# Check deployment configuration
npx convex dashboard
cat .env.local | grep CONVEX

"Environment variable not found"

# Check environment loading
cd apps/auth
node -e "console.log(process.env.CONVEX_DEPLOYMENT)"

Environment Debugging

Add debug logging to check environment loading:

// apps/auth/lib/debug-env.ts
export function debugEnvironment() {
  console.log('Environment Debug:', {
    CONVEX_DEPLOYMENT: process.env.CONVEX_DEPLOYMENT,
    NEXT_PUBLIC_CONVEX_URL: process.env.NEXT_PUBLIC_CONVEX_URL,
    NODE_ENV: process.env.NODE_ENV,
  });
}

Convex Connection Issues

# Test Convex connection
cd apps/auth
npx convex dev --verbose

# Check deployment status
npx convex dashboard

Production Deployment

Environment Variables

Set production environment variables in:

Vercel (for Next.js apps):
- NEXT_PUBLIC_CONVEX_URL_AUTH
- NEXT_PUBLIC_URL
- App-specific variables
Convex Dashboard (for backend functions):
- RESEND_API_KEY
- AUTH_GITHUB_ID / AUTH_GITHUB_SECRET
- AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET
- JWT_SECRET

Domain Configuration

DNS Setup:

auth.do.dev → Vercel (auth service)
do.dev → Vercel (dodev app)

SSL Certificates:
- Automatic via Vercel
- Ensure HTTPS for all OAuth redirects

OAuth Configuration

Update OAuth app settings for production:

GitHub OAuth App:
- Homepage URL: https://auth.do.dev
- Callback URL: https://auth.do.dev/api/auth/callback/github
Google OAuth App:
- Authorized origins: https://auth.do.dev
- Redirect URIs: https://auth.do.dev/api/auth/callback/google

Security Considerations

Development

Use .env.local for secrets (never commit)
Use localhost URLs for OAuth development
Different OAuth apps for dev/prod

Production

Store secrets in secure environment variable systems
Use HTTPS only
Implement proper CORS policies
Monitor for security issues

Migration Checklist

Pre-Migration

All environment variables configured
OAuth apps set up for production URLs
SSL certificates configured
Domain DNS pointing to correct services

Migration

Deploy auth service to auth.do.dev
Update OAuth redirect URLs
Test complete auth flows
Monitor error rates and performance

Post-Migration

Monitor auth success rates
Check email delivery rates
Verify OAuth flows work correctly
Set up alerting for failures

Last updated: January 2025