Skip to content

Apex Domain Configuration Guide

Overview

This guide documents the configuration changes needed to serve the Laravel app from vell.ai (apex domain) instead of only app.vell.ai.

Current State

  • app.vell.ai → Production ALB → Laravel App
  • vell.ai → Kajabi (to be migrated)

Target State

  • vell.ai → Production ALB → Laravel App (homepage)
  • app.vell.ai → Production ALB → Laravel App (same app)
  • Both domains share the same session

Environment Variables Changes

Production (.env)

# Before
APP_URL=https://app.vell.ai
SESSION_DOMAIN=app.vell.ai

# After
APP_URL=https://vell.ai
SESSION_DOMAIN=.vell.ai

Key Changes:

Variable Before After Reason
APP_URL https://app.vell.ai https://vell.ai Primary URL for generated links
SESSION_DOMAIN app.vell.ai .vell.ai Leading dot enables cookie sharing across subdomains

Why .vell.ai for SESSION_DOMAIN?

The leading dot (.vell.ai) allows the session cookie to be shared across: - vell.ai (apex) - app.vell.ai - www.vell.ai

This means users logged in on vell.ai will remain logged in when visiting app.vell.ai.

SSM Parameter Store Updates

If using AWS Systems Manager Parameter Store for environment config:

# Update APP_URL
aws ssm put-parameter \
    --name "/prod/app/APP_URL" \
    --value "https://vell.ai" \
    --type "SecureString" \
    --overwrite

# Update SESSION_DOMAIN
aws ssm put-parameter \
    --name "/prod/app/SESSION_DOMAIN" \
    --value ".vell.ai" \
    --type "String" \
    --overwrite

Laravel Configuration

No Code Changes Required

The app already: 1. ✅ Trusts ALB proxy headers (TrustProxies middleware) 2. ✅ Has no domain-specific route restrictions 3. ✅ Serves the homepage from / route 4. ✅ Uses environment variables for session domain

Verification Points

  1. Session Config (config/session.php:158) 

    'domain' => env('SESSION_DOMAIN'),

  2. TrustProxies (app/Http/Middleware/TrustProxies.php) 

    protected $headers =
    Request::HEADER_X_FORWARDED_FOR|
    Request::HEADER_X_FORWARDED_HOST|
    Request::HEADER_X_FORWARDED_PORT|
    Request::HEADER_X_FORWARDED_PROTO|
    Request::HEADER_X_FORWARDED_AWS_ELB;

  3. Routes (routes/web.php:37) 

    Route::get('', IndexController::class)->name('index');

Optional: www → apex Redirect

If you want www.vell.ai to redirect to vell.ai:

Already handled by CNAME: www.vell.ai → vell.ai

Option B: Laravel Middleware (More Control)

// app/Http/Middleware/RedirectWwwToApex.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class RedirectWwwToApex
{
    public function handle(Request $request, Closure $next)
    {
        $host = $request->getHost();

        if (str_starts_with($host, 'www.')) {
            $apex = substr($host, 4);
            return redirect()->to(
                $request->getScheme() . '://' . $apex . $request->getRequestUri(),
                301
            );
        }

        return $next($request);
    }
}

Register in app/Http/Kernel.php: 

protected $middleware = [
    \App\Http\Middleware\RedirectWwwToApex::class,
    // ... other middleware
];

Testing Checklist

Local Testing

# Add to /etc/hosts
127.0.0.1 vell.ai
127.0.0.1 app.vell.ai
127.0.0.1 www.vell.ai

# Update local .env
APP_URL=https://vell.ai
SESSION_DOMAIN=.vell.ai

Production Verification

After DNS migration:

  • https://vell.ai loads homepage
  • https://app.vell.ai loads homepage
  • https://www.vell.ai redirects to https://vell.ai
  • Login at vell.ai maintains session at app.vell.ai
  • Dashboard links use correct domain
  • Password reset emails use correct domain
  • OAuth callbacks work (may need provider config update)

OAuth Provider Updates

If using social login, update callback URLs in provider dashboards:

Provider Old Callback New Callback
Google https://app.vell.ai/google/callback Add https://vell.ai/google/callback
GitHub https://app.vell.ai/github/callback Add https://vell.ai/github/callback
Facebook https://app.vell.ai/facebook/callback Add https://vell.ai/facebook/callback

Best practice: Add both URLs to each provider to support both domains during transition.

CORS Configuration

If your app has CORS configured, ensure vell.ai is allowed:

// config/cors.php
'allowed_origins' => [
    'https://vell.ai',
    'https://app.vell.ai',
    'https://www.vell.ai',
],

Rollback Plan

If issues occur:

  1. Revert APP_URL to https://app.vell.ai
  2. Revert SESSION_DOMAIN to app.vell.ai
  3. Clear session cache: php artisan cache:clear
  4. Users on vell.ai will need to login again

Timeline

Step Action Downtime
1 Update env vars in SSM/Secrets Manager None
2 Deploy with new config ~2 min (rolling)
3 Run DNS migration script None
4 Change nameservers at registrar 5-30 min propagation
5 Verify all services None

References