Laravel-Docker-Dev-Template/TEST_SETUP.md

# 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