CRITICAL FIX: Move composer install after containers start

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'.
2026-03-09 18:35:56 +02:00
parent 7af4f1d14a
commit 97acc5e8ea
3 changed files with 454 additions and 23 deletions
--- a/TEST_SETUP.md
+++ b/TEST_SETUP.md
@@ -0,0 +1,420 @@
+# Testing the 2-Minute Setup
+
+This document verifies that the Laravel Docker Dev Template works as advertised.
+
+---
+
+## Test 1: Fresh Local Setup (Docker)
+
+### Prerequisites
+- Docker Desktop running
+- Git installed
+- No existing containers from this project
+
+### Steps
+
+```bash
+# 1. Clone to a fresh directory
+cd /tmp  # or C:\temp on Windows
+git clone https://git.radapps.co.za/theradcoza/Laravel-Docker-Dev-Template.git test-setup
+cd test-setup
+
+# 2. Run setup (should take ~2 minutes)
+./setup.sh mysql  # or setup.bat mysql on Windows
+
+# 3. Verify containers are running
+docker-compose ps
+```
+
+**Expected Output:**
+- `app` container: Up
+- `nginx` container: Up
+- `mysql` container: Up
+- `redis` container: Up
+- `mailpit` container: Up
+
+### Verification Checklist
+
+**Database:**
+```bash
+docker-compose exec app php artisan tinker
+```
+```php
+// Check admin user exists
+App\Models\User::where('email', 'admin@example.com')->exists();  // Should return: true
+
+// Check roles exist
+Spatie\Permission\Models\Role::count();  // Should return: 3
+
+// Check permissions exist
+Spatie\Permission\Models\Permission::count();  // Should return: 5
+
+// Check admin has admin role
+$admin = App\Models\User::where('email', 'admin@example.com')->first();
+$admin->hasRole('admin');  // Should return: true
+
+exit
+```
+
+**Web Access:**
+1. Visit http://localhost:8080 - Should show Laravel welcome page
+2. Visit http://localhost:8080/admin - Should show Filament login
+3. Login with:
+   - Email: admin@example.com
+   - Password: password
+4. Should successfully login and see admin dashboard
+5. Should see "Users" menu item
+6. Should see "Settings" menu item
+
+**Settings Page:**
+1. Click "Settings" in admin panel
+2. Should load without errors
+3. Should show form fields:
+   - Site Name
+   - Site Logo (file upload)
+   - Primary Color
+   - Secondary Color
+   - Accent Color
+   - Site Description
+   - Contact Email
+   - Maintenance Mode (toggle)
+4. Try saving - should show success notification
+
+**Users Management:**
+1. Click "Users" in admin panel
+2. Should see admin user in list
+3. Click "New User"
+4. Create test user
+5. Should save successfully
+
+**Mailpit:**
+1. Visit http://localhost:8025
+2. Should show Mailpit interface
+3. Send a test email (e.g., password reset)
+4. Email should appear in Mailpit
+
+### Success Criteria
+
+✅ Setup completes in under 3 minutes  
+✅ All containers start successfully  
+✅ Admin user exists with correct credentials  
+✅ 3 roles created (admin, editor, viewer)  
+✅ 5 permissions created  
+✅ Admin login works  
+✅ Settings page loads and saves  
+✅ Users management works  
+✅ No 500 errors  
+✅ No 419 CSRF errors  
+✅ No "Class Redis not found" errors  
+
+---
+
+## Test 2: Production Deployment Simulation
+
+### Prerequisites
+- Ubuntu 24.04 server (or VM)
+- Root or sudo access
+- Clean database
+
+### Steps
+
+Follow `PRODUCTION_DEPLOYMENT.md` exactly:
+
+```bash
+# 1. Install PHP and extensions
+sudo apt update
+sudo apt install -y php8.3 php8.3-fpm php8.3-cli php8.3-mysql \
+    php8.3-redis php8.3-curl php8.3-mbstring php8.3-xml \
+    php8.3-zip php8.3-bcmath php8.3-gd
+
+# 2. Verify Redis extension
+php -m | grep redis  # Should output: redis
+
+# 3. Clone repo
+cd /var/www
+sudo git clone https://git.radapps.co.za/theradcoza/Laravel-Docker-Dev-Template.git test-app
+cd test-app/src
+
+# 4. Install dependencies
+composer install --no-dev --optimize-autoloader
+npm install && npm run build
+
+# 5. Configure environment
+cp .env.mysql .env
+nano .env  # Set database credentials, APP_URL, etc.
+
+# 6. Generate key
+php artisan key:generate --force
+
+# 7. Run migrations
+php artisan migrate --force
+
+# 8. CRITICAL: Run seeders
+php artisan db:seed --force
+
+# 9. Set permissions
+sudo chown -R www-data:www-data storage bootstrap/cache
+sudo chmod -R 775 storage bootstrap/cache
+
+# 10. Create storage link
+php artisan storage:link
+
+# 11. Cache config
+php artisan config:cache
+php artisan route:cache
+php artisan view:cache
+```
+
+### Verification
+
+```bash
+# Check admin user exists
+php artisan tinker
+```
+```php
+App\Models\User::where('email', 'admin@example.com')->exists();  // true
+exit
+```
+
+**Configure web server** (Apache or Nginx) per `PRODUCTION_DEPLOYMENT.md`
+
+**Test web access:**
+1. Visit https://your-domain.com
+2. Visit https://your-domain.com/admin
+3. Login with admin@example.com / password
+4. Should work without errors
+
+### Success Criteria
+
+✅ PHP Redis extension installed  
+✅ Migrations run successfully  
+✅ Seeders run successfully  
+✅ Admin user created  
+✅ Roles and permissions created  
+✅ No "Class Redis not found" errors  
+✅ No 419 CSRF errors  
+✅ Admin login works  
+✅ Settings page works  
+✅ No 500 errors  
+
+---
+
+## Test 3: Common Error Scenarios
+
+### Scenario 1: Missing Redis Extension
+
+**Simulate:**
+```bash
+# On production server, DON'T install php-redis
+composer install
+php artisan migrate
+```
+
+**Expected:**
+- Should fail with clear error message
+- `PRODUCTION_DEPLOYMENT.md` should have solution
+
+**Fix:**
+```bash
+sudo apt install php8.3-redis
+sudo systemctl restart php8.3-fpm
+```
+
+### Scenario 2: Forgot to Run Seeders
+
+**Simulate:**
+```bash
+php artisan migrate --force
+# Skip: php artisan db:seed --force
+```
+
+**Expected:**
+- Admin user doesn't exist
+- Roles don't exist
+- Can't login
+
+**Fix:**
+```bash
+php artisan db:seed --force
+```
+
+### Scenario 3: Permission Issues
+
+**Simulate:**
+```bash
+# Wrong permissions on storage
+sudo chmod -R 755 storage
+```
+
+**Expected:**
+- 500 errors
+- Can't write logs
+
+**Fix:**
+```bash
+sudo chown -R www-data:www-data storage bootstrap/cache
+sudo chmod -R 775 storage bootstrap/cache
+```
+
+---
+
+## Automated Test Script
+
+Create `test-setup.sh`:
+
+```bash
+#!/bin/bash
+
+echo "🧪 Testing Laravel Docker Dev Template Setup..."
+echo ""
+
+# Test 1: Check containers
+echo "✓ Checking containers..."
+if ! docker-compose ps | grep -q "Up"; then
+    echo "❌ Containers not running"
+    exit 1
+fi
+echo "✅ Containers running"
+
+# Test 2: Check admin user
+echo "✓ Checking admin user..."
+ADMIN_EXISTS=$(docker-compose exec -T app php artisan tinker --execute="echo App\Models\User::where('email', 'admin@example.com')->exists() ? 'true' : 'false';")
+if [[ ! "$ADMIN_EXISTS" =~ "true" ]]; then
+    echo "❌ Admin user not found"
+    exit 1
+fi
+echo "✅ Admin user exists"
+
+# Test 3: Check roles
+echo "✓ Checking roles..."
+ROLE_COUNT=$(docker-compose exec -T app php artisan tinker --execute="echo Spatie\Permission\Models\Role::count();")
+if [[ ! "$ROLE_COUNT" =~ "3" ]]; then
+    echo "❌ Expected 3 roles, found: $ROLE_COUNT"
+    exit 1
+fi
+echo "✅ 3 roles created"
+
+# Test 4: Check permissions
+echo "✓ Checking permissions..."
+PERM_COUNT=$(docker-compose exec -T app php artisan tinker --execute="echo Spatie\Permission\Models\Permission::count();")
+if [[ ! "$PERM_COUNT" =~ "5" ]]; then
+    echo "❌ Expected 5 permissions, found: $PERM_COUNT"
+    exit 1
+fi
+echo "✅ 5 permissions created"
+
+# Test 5: Check admin has admin role
+echo "✓ Checking admin role assignment..."
+HAS_ROLE=$(docker-compose exec -T app php artisan tinker --execute="echo App\Models\User::where('email', 'admin@example.com')->first()->hasRole('admin') ? 'true' : 'false';")
+if [[ ! "$HAS_ROLE" =~ "true" ]]; then
+    echo "❌ Admin user doesn't have admin role"
+    exit 1
+fi
+echo "✅ Admin has admin role"
+
+# Test 6: Check web access
+echo "✓ Checking web access..."
+HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8080)
+if [ "$HTTP_CODE" != "200" ]; then
+    echo "❌ Web server not responding (HTTP $HTTP_CODE)"
+    exit 1
+fi
+echo "✅ Web server responding"
+
+# Test 7: Check admin panel
+echo "✓ Checking admin panel..."
+ADMIN_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/admin)
+if [ "$ADMIN_CODE" != "200" ]; then
+    echo "❌ Admin panel not responding (HTTP $ADMIN_CODE)"
+    exit 1
+fi
+echo "✅ Admin panel responding"
+
+echo ""
+echo "🎉 All tests passed!"
+echo ""
+echo "Admin Login:"
+echo "  URL: http://localhost:8080/admin"
+echo "  Email: admin@example.com"
+echo "  Password: password"
+```
+
+Make executable:
+```bash
+chmod +x test-setup.sh
+```
+
+Run:
+```bash
+./test-setup.sh
+```
+
+---
+
+## Quick Test (30 seconds)
+
+If you just want to verify the basics work:
+
+```bash
+# After running setup.sh
+docker-compose exec app php artisan tinker --execute="
+    echo 'Admin exists: ' . (App\Models\User::where('email', 'admin@example.com')->exists() ? 'YES' : 'NO') . PHP_EOL;
+    echo 'Roles count: ' . Spatie\Permission\Models\Role::count() . PHP_EOL;
+    echo 'Permissions count: ' . Spatie\Permission\Models\Permission::count() . PHP_EOL;
+    echo 'Admin has role: ' . (App\Models\User::where('email', 'admin@example.com')->first()->hasRole('admin') ? 'YES' : 'NO') . PHP_EOL;
+"
+```
+
+**Expected output:**
+```
+Admin exists: YES
+Roles count: 3
+Permissions count: 5
+Admin has role: YES
+```
+
+Then visit http://localhost:8080/admin and login.
+
+---
+
+## Reporting Issues
+
+If any test fails:
+
+1. **Capture logs:**
+   ```bash
+   docker-compose logs app > app-logs.txt
+   docker-compose exec app cat storage/logs/laravel.log > laravel-logs.txt
+   ```
+
+2. **Capture database state:**
+   ```bash
+   docker-compose exec app php artisan tinker --execute="
+       echo 'Users: ' . App\Models\User::count() . PHP_EOL;
+       echo 'Roles: ' . Spatie\Permission\Models\Role::count() . PHP_EOL;
+       echo 'Permissions: ' . Spatie\Permission\Models\Permission::count() . PHP_EOL;
+   " > db-state.txt
+   ```
+
+3. **Report with:**
+   - Which test failed
+   - Error messages
+   - Log files
+   - Steps to reproduce
+
+---
+
+## Success Metrics
+
+The template is considered "working correctly" if:
+
+- ✅ Fresh setup completes in under 3 minutes
+- ✅ Zero manual intervention required
+- ✅ Admin user auto-created with correct credentials
+- ✅ All roles and permissions seeded
+- ✅ Admin panel accessible immediately
+- ✅ Settings page works without errors
+- ✅ No Redis errors
+- ✅ No CSRF errors
+- ✅ Production deployment follows clear guide
+- ✅ All common errors documented with solutions
--- a/setup.bat
+++ b/setup.bat
@@ -34,11 +34,10 @@ if exist "src\.env.%DB%" (
    exit /b 1
 )

-REM Step 2: Install composer dependencies
-echo Installing composer dependencies...
+REM Step 2: Build containers
+echo Building Docker containers...
 docker-compose build
-docker-compose --profile %DB% run --rm app composer install --no-interaction
-echo Dependencies installed
+echo Containers built
 echo.

 REM Step 3: Start containers
@@ -47,7 +46,13 @@ docker-compose --profile %DB% up -d
 echo Containers started
 echo.

-REM Step 4: Wait for database
+REM Step 4: Install composer dependencies
+echo Installing composer dependencies...
+docker-compose exec app composer install --no-interaction
+echo Dependencies installed
+echo.
+
+REM Step 5: Wait for database
 if "%DB%"=="mysql" (
    echo Waiting for database...
    timeout /t 5 /nobreak >nul
@@ -61,27 +66,28 @@ if "%DB%"=="pgsql" (
    echo.
 )

-REM Step 5: Generate app key
+REM Step 6: Generate app key
 echo Generating application key...
 docker-compose exec app php artisan key:generate --force
 echo App key generated
 echo.

-REM Step 6: Run migrations
-echo → Running database migrations...
+REM Step 7: Run migrations
+echo Running database migrations...
 docker-compose exec app php artisan migrate --force
-echo ✓ Migrations completed
+echo Migrations completed
 echo.

-echo → Seeding database (roles, permissions, admin user)...
+REM Step 8: Seed database
+echo Seeding database (roles, permissions, admin user)...
 docker-compose exec app php artisan db:seed --force
-echo ✓ Database seeded
+echo Database seeded
 echo.

-REM Step 7: Create storage link
-echo → Creating storage symlink...
+REM Step 9: Create storage link
+echo Creating storage symlink...
 docker-compose exec app php artisan storage:link
-echo ✓ Storage linked
+echo Storage linked
 echo.

 REM Done
--- a/setup.sh
+++ b/setup.sh
@@ -42,11 +42,10 @@ else
    exit 1
 fi

-# Step 2: Install composer dependencies
-echo -e "${YELLOW}→ Installing composer dependencies...${NC}"
+# Step 2: Build containers
+echo -e "${YELLOW}→ Building Docker containers...${NC}"
 docker-compose build
-docker-compose --profile ${DB} run --rm app composer install --no-interaction
-echo -e "${GREEN}✓ Dependencies installed${NC}"
+echo -e "${GREEN}✓ Containers built${NC}"
 echo ""

 # Step 3: Start containers
@@ -55,7 +54,13 @@ docker-compose --profile ${DB} up -d
 echo -e "${GREEN}✓ Containers started${NC}"
 echo ""

-# Step 4: Wait for database
+# Step 4: Install composer dependencies
+echo -e "${YELLOW}→ Installing composer dependencies...${NC}"
+docker-compose exec app composer install --no-interaction
+echo -e "${GREEN}✓ Dependencies installed${NC}"
+echo ""
+
+# Step 5: Wait for database
 if [ "$DB" = "mysql" ] || [ "$DB" = "pgsql" ]; then
    echo -e "${YELLOW}→ Waiting for database...${NC}"
    sleep 5
@@ -63,25 +68,25 @@ if [ "$DB" = "mysql" ] || [ "$DB" = "pgsql" ]; then
    echo ""
 fi

-# Step 5: Generate app key if needed
+# Step 6: Generate app key
 echo -e "${YELLOW}→ Generating application key...${NC}"
 docker-compose exec app php artisan key:generate --force
 echo -e "${GREEN}✓ App key generated${NC}"
 echo ""

-# Step 6: Run migrations
+# Step 7: Run migrations
 echo -e "${YELLOW}→ Running database migrations...${NC}"
 docker-compose exec app php artisan migrate --force
 echo -e "${GREEN}✓ Migrations completed${NC}"
 echo ""

-# Step 7: Seed database (roles, permissions, admin user)
+# Step 8: Seed database (roles, permissions, admin user)
 echo -e "${YELLOW}→ Seeding database (roles, permissions, admin user)...${NC}"
 docker-compose exec app php artisan db:seed --force
 echo -e "${GREEN}✓ Database seeded${NC}"
 echo ""

-# Step 8: Create storage link
+# Step 9: Create storage link
 echo -e "${YELLOW}→ Creating storage symlink...${NC}"
 docker-compose exec app php artisan storage:link
 echo -e "${GREEN}✓ Storage linked${NC}"