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/
│   ├── webs/
│   │   ├── 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"

2. App-Specific Configuration

Each app can override or add to the root configuration:

# For auth app
cd apps/webs/auth
echo "CONVEX_DEPLOYMENT=$CONVEX_DEPLOYMENT_AUTH" > .env.local

# For data apps
cd apps/webs/[app-name]
echo "CONVEX_DEPLOYMENT=dev:your-app-deployment" > .env.local

3. Convex CLI Configuration

Configure Convex CLI to work with multiple deployments:

# Install Convex CLI globally
npm install -g convex

# Login to Convex
npx convex login

4. Working with Multiple Deployments

Auth Deployment

cd apps/webs/auth
npx convex dev --deployment dependable-pika-747

App Data Deployment

cd apps/webs/[app-name]
npx convex dev --deployment [app-deployment-id]

Development Workflow

Local Development Ports

To avoid conflicts, each app runs on a different port:

auth: 3030 (auth service)
dodev: 3005 (main app)
local-test: 3025 (test app)
promptnow: 3000
groktalk: 3001

Environment Variable Loading Order

Root .env.local (shared variables)
App-specific .env.local (overrides)
Process environment (CI/CD)

Using Environment Variables in Code

// For auth deployment
const authUrl = process.env.NEXT_PUBLIC_CONVEX_URL_AUTH

// For app deployment
const appUrl = process.env.NEXT_PUBLIC_CONVEX_URL

// Dynamic selection
const convexUrl = isAuthOperation 
  ? process.env.NEXT_PUBLIC_CONVEX_URL_AUTH
  : process.env.NEXT_PUBLIC_CONVEX_URL

OAuth Configuration

Development Setup

Google OAuth
- Create OAuth app at console.cloud.google.com
- Add redirect URIs:
  - http://localhost:3030/api/auth/callback/google
  - https://auth.do.dev/api/auth/callback/google
GitHub OAuth
- Create OAuth app at github.com/settings/developers
- Add redirect URIs:
  - http://localhost:3030/api/auth/callback/github
  - https://auth.do.dev/api/auth/callback/github

Dynamic Redirect Handling

The auth service handles dynamic redirects by:

Storing the originating app in OAuth state
Reading state on callback
Redirecting to the correct app

Troubleshooting

Common Issues

1. Environment Variables Not Loading

# Check if variables are set
echo $NEXT_PUBLIC_CONVEX_URL_AUTH

# Restart dev server after changes
pnpm dev

2. Wrong Convex Deployment

# Verify deployment in use
npx convex dashboard

# Check convex.json
cat convex.json

3. OAuth Redirect Issues

Ensure redirect URIs match exactly
Check OAuth state handling
Verify cookie domain settings

Debug Commands

# List all env variables
env | grep CONVEX

# Test Convex connection
npx convex function:list --deployment dependable-pika-747

# Check deployment status
npx convex dashboard --deployment dependable-pika-747

Production Deployment

Environment Variables in Vercel

Go to Vercel Dashboard
Select your project
Go to Settings → Environment Variables
Add all required variables:
- CONVEX_DEPLOYMENT_AUTH
- NEXT_PUBLIC_CONVEX_URL_AUTH
- OAuth credentials
- Email service keys

Domain Configuration

auth.do.dev
- Point to auth app deployment
- Configure SSL
- Set up CORS for API access
App Domains
- Each app on its own domain
- Shared auth cookies on *.do.dev

Security Best Practices

Environment Variable Security

Never commit .env.local

# Ensure it's in .gitignore
echo ".env.local" >> .gitignore

Use different keys for dev/prod
- Development: test keys
- Production: production keys
Rotate keys regularly
- OAuth secrets
- API keys
- JWT secrets

CORS Configuration

// In auth service
const allowedOrigins = [
  'https://do.dev',
  'https://promptnow.dev',
  'https://groktalk.com',
  // Development
  'http://localhost:3000',
  'http://localhost:3005',
  'http://localhost:3025',
]

Monitoring

Health Checks

// Auth service health endpoint
GET /api/health

// Response
{
  "status": "healthy",
  "deployment": "dependable-pika-747",
  "version": "1.0.0"
}

Logging

Auth events → Convex logs
Errors → Sentry/LogRocket
Analytics → PostHog/Mixpanel

Next Steps

Complete auth app setup
Deploy schema to auth deployment
Configure OAuth providers
Test with local-test app
Create migration plan for existing apps

On this page