The previous 5-second fixed wait was insufficient for MySQL 8.0 to fully
initialize, causing migrations and seeders to fail with 'Connection refused'.
Changes:
- Replace 'sleep 5' with active connection polling
- Try to connect every second for up to 30 seconds
- Use PHP PDO to test actual database connectivity
- Only proceed when database accepts connections
- Show clear status when database is ready
This ensures migrations and seeders run only after database is fully ready,
preventing 'Connection refused' errors on fresh setup.
Fixes the issue where Laravel loads but shows MySQL connection error.
Instead of stopping existing processes, setup scripts now automatically
find and use alternative ports if defaults are in use.
Features:
- Automatically detects port conflicts
- Finds next available port (e.g., 8080 -> 8081 -> 8082...)
- Writes custom ports to .env file
- Shows which ports were reassigned
- Displays correct URLs at end of setup
- Zero user interaction needed
Implementation:
- setup.bat: Uses netstat and batch functions to find free ports
- setup.sh: Uses lsof/netstat and bash functions to find free ports
- Ports checked: APP_PORT, MAIL_DASHBOARD_PORT, MAIL_PORT, REDIS_PORT, DB_PORT
- All ports written to src/.env for docker-compose to use
Example output:
[OK] Port 8080 (Web Server) - Available
[!] Port 8025 in use - using 8026 for Mailpit Dashboard
Your app will be at: http://localhost:8080
Mailpit at: http://localhost:8026
This ensures setup never fails due to port conflicts and doesn't
disrupt existing services.
Fixed 'was unexpected at this time' error caused by:
- Unescaped parentheses in echo statements
- Removed extra pipe to LISTENING filter (not needed)
- Changed √ symbol to OK for better Windows compatibility
- Escaped all parentheses with ^ character
The port check now works correctly on Windows.
Before starting Docker containers, setup scripts now check if required
ports are available and warn users about conflicts.
Features:
- Checks all required ports: 8080, 8025, 1025, 6379
- Checks database port based on selection (3306 for MySQL, 5432 for PostgreSQL)
- Shows clear status for each port (Available/In Use)
- If conflicts found:
- Displays warning message
- Shows helpful commands to find and stop conflicting processes
- Asks user if they want to continue anyway
- Exits if user chooses not to continue
Benefits:
- Prevents confusing 'port already in use' errors during container startup
- Provides clear diagnostic information
- Gives users control over how to handle conflicts
- Improves setup experience and reduces frustration
Implementation:
- setup.bat: Uses netstat with findstr for Windows
- setup.sh: Uses lsof and netstat for Linux/Mac compatibility
This solves the Windows/WSL2 performance issue that caused composer install
to timeout after 300 seconds.
Changes:
1. docker-compose.yml:
- Added vendor_data named volume for app, queue, scheduler services
- vendor/ now uses fast Docker volume instead of slow bind mount
2. Dockerfile:
- Pre-install composer dependencies during image build
- Copy composer.json/lock first, run install, then copy rest of src
- Runs as devuser to match runtime permissions
- Dependencies baked into image = truly 'pre-installed'
3. setup.bat & setup.sh:
- Removed composer install step (now in Dockerfile)
- Added -T flag to all docker-compose exec commands (fixes Windows TTY hang)
- Added 3-second wait for container readiness
Benefits:
- ✅ Setup completes in 2-3 minutes (not 10+ minutes)
- ✅ No composer timeout issues
- ✅ Works on Windows/Mac/Linux
- ✅ vendor/ persists in Docker volume (fast)
- ✅ True 'everything pre-installed' experience
Trade-offs:
- vendor/ not visible in Windows filesystem (in Docker volume)
- Need to rebuild image when adding composer packages
- Slightly larger Docker image (~200MB more)
This is the correct approach for a Docker-based development template.
The previous setup scripts ran 'composer install' in a temporary container
before starting the actual containers. This caused vendor/ directory to be
created inside the temporary container and then deleted, leaving the host
filesystem without dependencies.
Changes:
- setup.bat: Move composer install to Step 4 (after containers start)
- setup.sh: Move composer install to Step 4 (after containers start)
- Use 'docker-compose exec' instead of 'docker-compose run --rm'
- This ensures vendor/ is written to the host filesystem via volume mount
- Added TEST_SETUP.md with comprehensive testing procedures
Now the vendor/ directory will persist correctly on Windows/WSL2 and the
app will load without 'vendor/autoload.php not found' errors.
This was the root cause of the setup not being truly '2-minute ready'.
CRITICAL FIXES:
- DatabaseSeeder now calls RolePermissionSeeder to create roles, permissions, and admin user
- setup.sh and setup.bat now run db:seed automatically during setup
- Created PRODUCTION_DEPLOYMENT.md with complete production deployment guide
- Removed duplicate admin user creation from setup scripts
This ensures:
- Admin user (admin@example.com / password) is created automatically
- Roles (admin, editor, viewer) are created during setup
- Permissions are seeded properly
- Production deployments have clear step-by-step instructions
- PHP Redis extension installation documented
- All common deployment issues addressed
The 2-minute setup now truly works out of the box.
- Install spatie/laravel-permission v6.24 with 3 roles (admin, editor, viewer) and 5 base permissions
- Install owen-it/laravel-auditing v14.0 for tracking model changes
- Install laravel/sanctum v4.3 for API token authentication
- Install spatie/laravel-ignition v2.11 and spatie/flare-client-php v1.10 for enhanced error tracking
- Add Module System with make:module artisan command for scaffolding features
- Create Site Settings page in Filament admin for logo, colors, and configuration
- Add comprehensive debugging documentation (DEBUGGING.md, AI_CONTEXT.md updates)
- Create FEATURES.md with complete feature reference
- Update User model with HasRoles and HasApiTokens traits
- Configure Redis cache and OPcache for performance
- Add RolePermissionSeeder with pre-configured roles and permissions
- Update documentation with debugging-first workflow
- All features pre-installed and production-ready
