Two critical fixes:
1. DB_PORT was being appended to Laravel .env file
- Setup script was writing DB_PORT=3307 (external port)
- Laravel needs internal Docker port (3306)
- Now ports are commented out in .env (reference only)
- Docker-compose uses env vars, Laravel uses fixed internal ports
2. DatabaseSeeder.php had UTF-8 BOM (Byte Order Mark)
- Caused 'Namespace declaration must be first statement' error
- Removed invisible BOM bytes from file
These fixes ensure:
- MySQL connections work from within Docker network
- Database seeding completes successfully
- Fresh setup works end-to-end
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.
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
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.
