Local Development Setup

This guide explains how to set up the multi-domain application for local development.

Overview

The application uses three domains:

Quick Start

1. Configure Local Domains

Windows (PowerShell as Administrator):

.\scripts\setup-local-domains.ps1

Linux/macOS/WSL:

sudo ./scripts/setup/setup-local-domains.sh

Check status:

# Windows
.\scripts\setup-local-domains.ps1 -Check

# Linux/macOS
./scripts/setup/setup-local-domains.sh --check

2. Environment Setup

Copy the example environment file:

cp .env.example .env

The default .env.example is pre-configured for local development with .test domains.

3. Install Dependencies

composer install
npm install

4. Initialize Database

php artisan key:generate
php artisan migrate
php artisan db:seed

5. Start Development Server

composer dev

This runs Laravel, Vite, queue worker, and log viewer concurrently.

6. Access the Application

• Marketing: http://scopeforged.test:8000
• Portal: http://portal.scopeforged.test:8000
• Admin: http://admin.scopeforged.test:8000

Manual Hosts Configuration

If you prefer not to use the setup scripts, manually edit your hosts file:

Windows: C:\Windows\System32\drivers\etc\hosts Linux/macOS: /etc/hosts

Add these lines:

127.0.0.1    scopeforged.test
127.0.0.1    portal.scopeforged.test
127.0.0.1    admin.scopeforged.test

Alternative: Laravel Valet (macOS)

If you use Laravel Valet:

# Link the project
cd client-portal-laravel
valet link scopeforged

# The domains will automatically resolve:
# - http://scopeforged.test
# - http://portal.scopeforged.test
# - http://admin.scopeforged.test

No port number needed with Valet.

Alternative: Laravel Herd (Windows/macOS)

Laravel Herd provides similar functionality:

1. Install Herd
2. Add the project directory to Herd
3. Domains resolve automatically without port numbers

Environment Variables

Key domain-related variables in .env:

# Domain Configuration
MARKETING_DOMAIN=scopeforged.test
PORTAL_DOMAIN=portal.scopeforged.test
ADMIN_DOMAIN=admin.scopeforged.test

# Port for local development (required for artisan serve)
APP_PORT=8000

# Session cookie domain (with leading dot for subdomain sharing)
SESSION_DOMAIN=.scopeforged.test

For production, update these to:

MARKETING_DOMAIN=scopeforged.com
PORTAL_DOMAIN=portal.scopeforged.com
ADMIN_DOMAIN=admin.scopeforged.com
APP_PORT=
SESSION_DOMAIN=.scopeforged.com

Important: APP_PORT=8000 is required when using php artisan serve. Leave it empty for Laravel Valet, Herd, or production.

How Domain Routing Works

Domain-based routing is configured in bootstrap/app.php:

->withRouting(
    then: function () {
        // Marketing site
        Route::domain(config('domains.marketing'))
            ->middleware('web')
            ->group(base_path('routes/marketing.php'));

        // Portal subdomain
        Route::domain(config('domains.portal'))
            ->middleware('web')
            ->group(base_path('routes/portal-domain.php'));

        // Admin subdomain
        Route::domain(config('domains.admin'))
            ->middleware(['web', 'auth', 'verified', 'admin'])
            ->group(base_path('routes/admin-domain.php'));
    },
)

Configuration values come from config/domains.php which reads from environment variables.

Session Sharing

The SESSION_DOMAIN must start with a dot (.scopeforged.test) to allow session cookies to be shared across subdomains. This enables:

• Login once on any subdomain
• Stay logged in across marketing, portal, and admin
• Seamless navigation between domains

Troubleshooting

"Connection Refused" Error

1. Ensure the dev server is running: composer dev
2. Check you're using the correct port (:8000)
3. Verify hosts file entries: .\scripts\setup-local-domains.ps1 -Check

"Session Not Persisting" Between Domains

1. Verify SESSION_DOMAIN starts with a dot: .scopeforged.test
2. Clear browser cookies for scopeforged.test
3. Run php artisan config:clear

Changes Not Reflecting

php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan cache:clear

Permission Issues (Linux/macOS)

chmod +x scripts/setup/setup-local-domains.sh
sudo ./scripts/setup/setup-local-domains.sh

Can't Access Hosts File (Windows)

1. Open PowerShell as Administrator
2. Right-click PowerShell → "Run as administrator"
3. Navigate to project directory
4. Run the setup script

Default Credentials

After seeding the database (php artisan db:seed):

Related Documentation

• Deployment Guide
• Configuration Guide
• Contributing Guide