tebogomas14/shell-leaderboard
1
0
Fork 0
generated from theradcoza/Laravel-Docker-Dev-Template
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
tebogomas14
2026-03-24 17:01:12 +00:00
commit a88504357d
237 changed files with 34375 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

420
TEST_SETUP.md Normal file
View File

@@ -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