Authentication Setup

Architecture Overview

Turbocamp uses a centralized authentication architecture with Better Auth:

• API App (localhost:3002) - Primary auth server handling all authentication
• Dashboard App (localhost:3001) - Main application with full auth pages
• Web App (localhost:3000) - Marketing site with auth modal + redirects
• Cross-domain cookies - Seamless auth across all domains

Required Environment Variables

Database Configuration

# Required for all apps
DATABASE_URL="postgresql://username:password@localhost:5432/turbocamp?schema=public"

createdb turbocamp

Better Auth Configuration

# Required for authentication to work
BETTER_AUTH_SECRET="your-32-character-secret-key-here"

Generate a secure secret:

openssl rand -base64 32

Application URLs

# API App (Primary auth server)
BETTER_AUTH_URL="http://localhost:3002"
AUTH_API_URL="http://localhost:3002"
NEXT_PUBLIC_AUTH_API_URL="http://localhost:3002"

# Application URLs
NEXT_PUBLIC_WEB_URL="http://localhost:3000"
NEXT_PUBLIC_DASHBOARD_URL="http://localhost:3001"

# API App
BETTER_AUTH_URL="https://api.turbocamp.dev"
AUTH_API_URL="https://api.turbocamp.dev"
NEXT_PUBLIC_AUTH_API_URL="https://api.turbocamp.dev"

# Application URLs
NEXT_PUBLIC_WEB_URL="https://turbocamp.dev"
NEXT_PUBLIC_DASHBOARD_URL="https://dashboard.turbocamp.dev"

# Optional: Additional trusted origins
ADDITIONAL_TRUSTED_ORIGINS="https://staging.turbocamp.dev"

Quick Setup

pnpm install

# Copy database environment
cp packages/db/.env.example packages/db/.env

# Edit packages/db/.env and add your DATABASE_URL
# Then run migrations
pnpm migrate

# API App (Primary auth server)
cp .env.example apps/api/.env.local

# Dashboard App  
cp .env.example apps/dashboard/.env.local

# Web App
cp .env.example apps/web/.env.local

DATABASE_URL="your-database-url"
BETTER_AUTH_SECRET="your-32-character-secret"
BETTER_AUTH_URL="http://localhost:3002"

AUTH_API_URL="http://localhost:3002"
NEXT_PUBLIC_AUTH_API_URL="http://localhost:3002"
NEXT_PUBLIC_DASHBOARD_URL="http://localhost:3001"
NEXT_PUBLIC_WEB_URL="http://localhost:3000"
BETTER_AUTH_SECRET="same-secret-as-api"

AUTH_API_URL="http://localhost:3002"
NEXT_PUBLIC_AUTH_API_URL="http://localhost:3002"
NEXT_PUBLIC_WEB_URL="http://localhost:3000"
NEXT_PUBLIC_DASHBOARD_URL="http://localhost:3001"

pnpm dev

Authentication Flow

Dual Auth Experience

Option 1: Quick Signup (Modal)

1. User clicks "Get Started" on web app
2. Modal opens with signup/signin tabs
3. User completes authentication
4. Modal closes and redirects to dashboard

Option 2: Full Page Auth (Redirect)

1. User clicks "Sign In" on web app
2. Redirects to dashboard login page
3. User completes authentication
4. Redirects to dashboard

Cross-Domain Session Management

• Primary Auth Server: API app handles all authentication
• Cross-domain Cookies: Sessions work across all subdomains
• Trusted Origins: CORS configured for secure cross-domain requests
• Automatic Redirects: Seamless experience across applications

Advanced Configuration

Email Integration

For transactional emails with Resend:

RESEND_API_KEY="re_xxxxxxxxxxxxxxxx"
RESEND_FROM="noreply@yourdomain.com"

Rate Limiting

Using Upstash Redis for rate limiting:

UPSTASH_REDIS_REST_URL="https://xxxxxxxx.upstash.io"
UPSTASH_REDIS_REST_TOKEN="xxxxxxxxxxxxxxxx"

Analytics

PostHog for user analytics:

NEXT_PUBLIC_POSTHOG_KEY="your-posthog-key"
NEXT_PUBLIC_POSTHOG_HOST="https://app.posthog.com"

Monitoring

Sentry for error tracking:

NEXT_PUBLIC_SENTRY_DSN="https://xxxxxxxxxxxxxxxx@sentry.io/xxxxxxxx"

Testing the Setup

Basic Authentication Test

1. Visit http://localhost:3000
2. Click "Get Started" - modal should open
3. Create an account
4. Should redirect to http://localhost:3001 (dashboard)

Cross-Domain Auth Test

1. Visit http://localhost:3001/sign-in directly
2. Sign in with your account
3. Visit http://localhost:3000
4. Should recognize you're already signed in

Sign Out Test

1. Sign out from dashboard
2. Visit web app - should not be signed in
3. Cross-domain session clearing working correctly

Troubleshooting

Common Issues

Debug Mode

Enable debug logging:

NODE_ENV="development"
DEBUG="better-auth:*"

Production Deployment

Domain Configuration

For production, update all URLs to use your actual domains:

# Example production configuration
BETTER_AUTH_URL="https://api.turbocamp.dev"
NEXT_PUBLIC_WEB_URL="https://turbocamp.dev"
NEXT_PUBLIC_DASHBOARD_URL="https://dashboard.turbocamp.dev"

Cross-Domain Cookie Setup

The system automatically handles cross-domain cookies:

• Development: Uses localhost as cookie domain
• Production: Uses .turbocamp.dev for subdomain sharing
• HTTPS Required: Secure cookies in production
• CORS Configured: Trusted origins for all your domains

DNS Configuration

Set up your DNS records:

A    turbocamp.dev              → Your web server IP
A    dashboard.turbocamp.dev    → Your dashboard server IP  
A    api.turbocamp.dev         → Your API server IP

Security Considerations

Required for Production

1. HTTPS Only: All auth endpoints must use HTTPS
2. Secure Secrets: Use strong, unique secrets
3. Rate Limiting: Configure to prevent brute force attacks
4. CORS Policy: Strict trusted origins configuration
5. Cookie Security: Secure, HttpOnly, SameSite configured

Recommended

• Use environment-specific secrets
• Enable error monitoring with Sentry
• Set up proper logging and alerting
• Regular security audits
• Keep dependencies updated

Mobile App Integration

The centralized API is ready for mobile app integration:

REST API Endpoints

All auth operations available via REST:

• POST /api/auth/sign-in - Email/password login
• POST /api/auth/sign-up - Create account
• POST /api/auth/sign-out - Sign out
• GET /api/auth/session - Get current session
• POST /api/auth/reset-password - Password reset

React Native Example

// Mobile app can directly call API endpoints
const authResponse = await fetch('https://api.turbocamp.dev/api/auth/sign-in', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password })
});

Next Steps

Once authentication is working:

1. Customize UI: Update auth modal and pages with your branding
2. Add OAuth: Configure Google, GitHub, etc. in Better Auth
3. Email Features: Set up welcome emails and notifications
4. User Profiles: Add user profile management
5. Organizations: Configure team/organization features
6. Mobile Apps: Integrate with React Native or other mobile frameworks