shell-leaderboard/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

# 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:

docker-compose exec app php artisan tinker

// 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:

# 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

# Check admin user exists
php artisan tinker

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:

# 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:

sudo apt install php8.3-redis
sudo systemctl restart php8.3-fpm

Scenario 2: Forgot to Run Seeders

Simulate:

php artisan migrate --force
# Skip: php artisan db:seed --force

Expected:

• Admin user doesn't exist
• Roles don't exist
• Can't login

Fix:

php artisan db:seed --force

Scenario 3: Permission Issues

Simulate:

# Wrong permissions on storage
sudo chmod -R 755 storage

Expected:

• 500 errors
• Can't write logs

Fix:

sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

---

Automated Test Script

Create test-setup.sh:

#!/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:

chmod +x test-setup.sh

Run:

./test-setup.sh

---

Quick Test (30 seconds)

If you just want to verify the basics work:

# 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:

   docker-compose logs app > app-logs.txt
   docker-compose exec app cat storage/logs/laravel.log > laravel-logs.txt
   

2. Capture database state:

   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