GUI Installer - Implementation Plan

Status: Planned for v1.1.0 Priority: Medium Estimated effort: 8-12 hours

Overview

Web-based installation wizard accessible at /install that guides users through:

1. Requirements check
2. Database configuration
3. Environment setup
4. Initial admin account creation
5. First tenant creation

File Structure

app/
├── Http/
│   ├── Controllers/
│   │   └── Installer/
│   │       └── InstallerController.php
│   └── Middleware/
│       └── RedirectIfInstalled.php
│
resources/views/installer/
├── layouts/
│   └── installer.blade.php      # Clean layout without app chrome
├── welcome.blade.php            # Step 1: Welcome & license
├── requirements.blade.php       # Step 2: PHP, extensions, permissions
├── database.blade.php           # Step 3: Database credentials
├── environment.blade.php        # Step 4: App URL, mail, etc.
├── admin.blade.php              # Step 5: Super admin account
├── tenant.blade.php             # Step 6: First tenant (optional)
└── finished.blade.php           # Step 7: Success + next steps
│
routes/
└── installer.php                # Separate route file
│
storage/
└── installed                    # Flag file (created after install)

Step-by-Step Flow

Step 1: Welcome

• Display Tenanto logo and version
• License agreement checkbox
• "Start Installation" button

Step 2: Requirements Check

$requirements = [
    'php_version' => version_compare(PHP_VERSION, '8.2.0', '>='),
    'extensions' => [
        'pdo', 'pdo_pgsql', 'mbstring', 'openssl',
        'tokenizer', 'xml', 'ctype', 'json', 'bcmath',
        'fileinfo', 'redis'
    ],
    'directories' => [
        'storage/app' => is_writable(storage_path('app')),
        'storage/framework' => is_writable(storage_path('framework')),
        'storage/logs' => is_writable(storage_path('logs')),
        'bootstrap/cache' => is_writable(base_path('bootstrap/cache')),
    ],
];

• Green checkmarks / Red X for each item
• Cannot proceed if critical requirements fail

Step 3: Database Configuration

Form fields:

• Database Host (default: localhost)
• Database Port (default: 5432)
• Database Name (default: tenanto)
• Database Username
• Database Password

Actions:

1. Test connection before proceeding
2. Write to .env file
3. Display success/error message

Step 4: Environment Setup

Form fields:

• Application URL (auto-detected from request)
• Application Name (default: Tenanto)
• Mail Driver (select: smtp, mailgun, ses, log)
• Mail From Address
• Mail From Name

Optional (collapsible):

• Redis Host/Port
• Queue Connection
• Cache Driver

Step 5: Admin Account

Form fields:

• Name
• Email
• Password
• Confirm Password

Validation:

• Email must be valid format
• Password min 8 chars, mixed case, number

Step 6: First Tenant (Optional)

Form fields:

• Company Name
• Subdomain (slug)
• Admin becomes tenant owner

Skip option: "I'll create tenants later"

Step 7: Finish

Actions performed:

1. Run migrations: php artisan migrate --force
2. Seed roles/permissions: php artisan db:seed --class=RoleAndPermissionSeeder
3. Create admin user with super-admin role
4. Create tenant if provided
5. Clear caches: php artisan optimize:clear
6. Create storage/installed flag

Display:

• Success message
• Links to Admin Panel and Documentation
• "Remove installer files for security" warning

Security Considerations

RedirectIfInstalled Middleware

class RedirectIfInstalled
{
    public function handle($request, Closure $next)
    {
        if (file_exists(storage_path('installed'))) {
            return redirect('/');
        }
        return $next($request);
    }
}

Post-Install Recommendations

• Delete routes/installer.php after installation
• Or disable via .env: INSTALLER_ENABLED=false
• Warn in step 7 about security

Input Validation

• Sanitize all database credentials
• Validate email formats
• Escape shell commands if any
• Use Laravel's encryption for sensitive storage

UI Design

Layout

• Clean, minimal design (no sidebar/navbar)
• Progress indicator showing all steps
• Tenanto logo in header
• Tailwind CSS (already included)

Colors

• Primary: Indigo (matches landing page)
• Success: Green checkmarks
• Error: Red with clear messages
• Background: Slate gradient

Responsive

• Works on mobile (tablet minimum for best experience)
• Single column layout

Implementation Order

1. Create route file and middleware (30 min)
2. Create base layout (1 hour)
3. Step 1-2: Welcome + Requirements (2 hours)
4. Step 3: Database with test connection (2 hours)
5. Step 4: Environment (1.5 hours)
6. Step 5-6: Admin + Tenant (2 hours)
7. Step 7: Finish with migrations (1.5 hours)
8. Testing and polish (2 hours)

Total: ~12 hours

Alternative: CLI Installer Enhancement

For v1.0.0, enhance existing setup.sh:

#!/bin/bash
# Interactive CLI installer

echo "🚀 Tenanto Installation"
echo ""

# Check requirements
php -v | head -1
php -m | grep -E "pdo|redis|mbstring"

# Interactive prompts
read -p "Database host [localhost]: " DB_HOST
read -p "Database name [tenanto]: " DB_NAME
read -p "Database user: " DB_USER
read -s -p "Database password: " DB_PASS

# Generate .env
cp .env.example .env
sed -i "s/DB_HOST=.*/DB_HOST=${DB_HOST:-localhost}/" .env
# ... etc

# Run setup
composer install --no-dev
npm install && npm run build
php artisan key:generate
php artisan migrate --seed
php artisan optimize

echo "✅ Installation complete!"

Decision

v1.0.0: Ship with good documentation + setup.sh CLI v1.1.0: Add GUI installer as feature update

This approach:

• Gets product to market faster
• GUI installer becomes a "free update" for existing customers
• Matches what many Laravel products do on CodeCanyon

Created: 2025-01-17