Initial commit

2026-03-24 17:01:12 +00:00
commit a88504357d
237 changed files with 34375 additions and 0 deletions
--- a/GETTING_STARTED.md
+++ b/GETTING_STARTED.md
@@ -0,0 +1,364 @@
+# Getting Started
+
+This guide walks you through setting up your Laravel development environment using this template.
+
+## Prerequisites
+
+- Docker & Docker Compose
+- Git
+
+## Quick Start (2 minutes)
+
+**Everything is pre-installed!** Just clone and run:
+
+```bash
+# 1. Clone the template
+git clone https://github.com/your-repo/Laravel-Docker-Dev-Template.git my-project
+cd my-project
+
+# 2. Run setup (MySQL is default)
+./setup.sh          # Linux/Mac
+setup.bat           # Windows
+
+# Or choose a different database:
+./setup.sh pgsql    # PostgreSQL
+./setup.sh sqlite   # SQLite
+
+# 3. Access your app
+# Laravel: http://localhost:8080
+# Admin:   http://localhost:8080/admin (admin@example.com / password)
+# Mail:    http://localhost:8025
+```
+
+**That's it!** You now have a fully working Laravel application with:
+- ✅ Authentication (login, register, password reset)
+- ✅ Admin panel with user management
+- ✅ Testing framework (Pest)
+- ✅ Code style (Pint)
+- ✅ Email testing (Mailpit)
+
+## What's Pre-Installed
+
+This template comes with everything configured and ready to use:
+
+### Core Framework
+- **Laravel 11** - Latest version with all features
+- **Laravel Breeze** - Authentication scaffolding (Blade + dark mode)
+- **Livewire** - Reactive components without JavaScript
+
+### Admin & Management
+- **Filament v3.3** - Full-featured admin panel
+- **User Management** - CRUD interface for users
+- **Site Settings** - Logo, color scheme, and site configuration
+- **Spatie Permissions** - Role-based access control (admin, editor, viewer)
+- **Dashboard** - Admin dashboard with widgets
+
+### Security & Tracking
+- **Laravel Auditing** - Track all data changes and user actions
+- **Laravel Sanctum** - API authentication with tokens
+- **Spatie Ignition** - Enhanced error pages and debugging
+
+### Development Tools
+- **Pest** - Modern testing framework with elegant syntax
+- **Laravel Pint** - Opinionated code style fixer
+- **Mailpit** - Email testing tool
+- **Module System** - Artisan command to scaffold new features
+
+### Infrastructure
+- **Docker** - Containerized development environment
+- **MySQL/PostgreSQL/SQLite** - Choose your database
+- **Redis** - Caching and queues (OPcache enabled)
+- **Queue Workers** - Background job processing (optional)
+- **Scheduler** - Task scheduling (optional)
+
+## Step-by-Step Setup
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/your-repo/Laravel-Docker-Dev-Template.git my-project
+cd my-project
+
+# Optional: Remove template git history and start fresh
+rm -rf .git
+git init
+git add .
+git commit -m "Initial commit"
+```
+
+### 2. Choose Your Database
+
+| Database | Best For | Command |
+|----------|----------|---------|
+| **MySQL** | Most projects, production parity | `./setup.sh mysql` |
+| **PostgreSQL** | Advanced features, JSON, full-text search | `./setup.sh pgsql` |
+| **SQLite** | Simple apps, quick prototyping | `./setup.sh sqlite` |
+
+### 3. Run Setup Script
+
+```bash
+./setup.sh mysql    # Linux/Mac
+setup.bat mysql     # Windows
+```
+
+The script will:
+- ✅ Configure environment for chosen database
+- ✅ Install composer dependencies
+- ✅ Build and start Docker containers
+- ✅ Run database migrations
+- ✅ Create admin user automatically
+
+### 4. Start Developing
+
+Your application is now ready! The setup script created an admin user for you:
+
+**Admin Login:**
+- Email: `admin@example.com`
+- Password: `password`
+
+**Access Points:**
+- Public site: http://localhost:8080
+- Admin panel: http://localhost:8080/admin
+- Site settings: http://localhost:8080/admin/settings
+- Email testing: http://localhost:8025
+- API endpoints: http://localhost:8080/api/*
+
+## Common Commands
+
+```bash
+# Shell into container
+make shell
+
+# Create a module with a model
+php artisan make:module Inventory --model=Product
+
+# Run migrations
+php artisan migrate
+
+# Seed permissions
+php artisan db:seed --class=PermissionSeeder
+```
+
+Your module is now at:
+- Frontend: http://localhost:8080/inventory
+- Admin: http://localhost:8080/admin → Inventory section
+
+## Project Structure After Setup
+
+```
+my-project/
+├── src/                          # Laravel application
+│   ├── app/
+│   │   ├── Modules/              # Your feature modules
+│   │   │   └── Inventory/
+│   │   │       ├── Config/
+│   │   │       ├── Database/
+│   │   │       ├── Filament/     # Admin resources
+│   │   │       ├── Http/
+│   │   │       ├── Models/
+│   │   │       └── Routes/
+│   │   ├── Providers/
+│   │   └── Traits/
+│   │       └── ModuleAuditable.php
+│   ├── config/
+│   ├── database/
+│   ├── resources/
+│   │   └── views/
+│   │       └── errors/           # Custom error pages
+│   └── routes/
+├── docker/                       # Docker configuration
+├── deploy/                       # Production deployment
+└── docs/                         # Documentation
+```
+
+## Common Commands
+
+### Development
+
+| Command | Description |
+|---------|-------------|
+| `make up` | Start containers |
+| `make down` | Stop containers |
+| `make shell` | Shell into app container |
+| `make logs` | View container logs |
+| `make artisan cmd='...'` | Run artisan command |
+| `make composer cmd='...'` | Run composer command |
+
+### Database
+
+| Command | Description |
+|---------|-------------|
+| `make migrate` | Run migrations |
+| `make fresh` | Fresh migrate + seed |
+| `make tinker` | Laravel Tinker REPL |
+
+### Testing & Quality
+
+| Command | Description |
+|---------|-------------|
+| `make test` | Run tests |
+| `make lint` | Fix code style (Pint) |
+| `make lint-check` | Check code style |
+
+### Queues & Backup
+
+| Command | Description |
+|---------|-------------|
+| `make queue-start` | Start background job worker |
+| `make queue-logs` | View queue worker logs |
+| `make scheduler-start` | Start Laravel scheduler |
+| `make backup` | Backup database |
+| `make restore file=...` | Restore from backup |
+
+### Modules
+
+```bash
+# Create a complete module with CRUD, views, tests, and Filament resource
+php artisan make:module ProductCatalog
+
+# This creates:
+# - Model, Controller, Routes, Views
+# - Migration and Filament Resource
+# - Pest tests
+# - See app/Modules/README.md for details
+```
+
+## Environment Files
+
+| File | Purpose |
+|------|---------|
+| `.env` | Docker Compose config |
+| `src/.env` | Laravel app config |
+| `src/.env.mysql` | MySQL preset |
+| `src/.env.pgsql` | PostgreSQL preset |
+| `src/.env.sqlite` | SQLite preset |
+
+### Key Environment Variables
+
+```env
+# App
+APP_NAME="My App"
+APP_ENV=local
+APP_DEBUG=true
+APP_URL=http://localhost:8080
+
+# Database (set by profile)
+DB_CONNECTION=mysql
+DB_HOST=mysql
+DB_PORT=3306
+DB_DATABASE=laravel
+DB_USERNAME=laravel
+DB_PASSWORD=secret
+
+# Error Tracking
+FLARE_KEY=your_key_here
+
+# Ignition (dev)
+IGNITION_THEME=auto
+IGNITION_EDITOR=vscode
+```
+
+## Ports
+
+| Service | Port | URL |
+|---------|------|-----|
+| Laravel | 8080 | http://localhost:8080 |
+| MySQL | 3306 | localhost:3306 |
+| PostgreSQL | 5432 | localhost:5432 |
+| Redis | 6379 | localhost:6379 |
+| Mailpit UI | 8025 | http://localhost:8025 |
+| Mailpit SMTP | 1025 | localhost:1025 |
+
+## Troubleshooting
+
+### 🚨 FIRST STEP: Check Logs
+
+**Always check logs before trying fixes:**
+
+```bash
+# Laravel application logs (MOST IMPORTANT)
+docker-compose exec app tail -n 100 storage/logs/laravel.log
+
+# Search for specific error
+docker-compose exec app cat storage/logs/laravel.log | grep "ErrorType"
+
+# Container logs
+docker-compose logs --tail=50 app
+docker-compose logs --tail=50 nginx
+```
+
+**See [DEBUGGING.md](DEBUGGING.md) for complete debugging guide.**
+
+---
+
+### Application Errors
+
+When you see errors in the browser:
+
+1. **Check Laravel logs** (see above)
+2. **Read the full stack trace** - it shows exact file and line
+3. **Clear caches** after making changes:
+
+```bash
+docker-compose exec app php artisan optimize:clear
+docker-compose exec app php artisan permission:cache-reset
+```
+
+---
+
+### Container won't start
+
+```bash
+# Check logs
+make logs
+
+# Reset everything
+make clean
+make install DB=mysql
+```
+
+### Permission issues
+
+```bash
+make shell
+chmod -R 775 storage bootstrap/cache
+```
+
+### Database connection refused
+
+```bash
+# Wait for database to be ready
+docker-compose exec mysql mysqladmin ping -h localhost
+
+# Or restart
+make down
+make up
+```
+
+### Artisan commands fail
+
+```bash
+# Make sure you're in the container
+make shell
+
+# Then run artisan
+php artisan migrate
+```
+
+## Next Steps
+
+1. **Configure Site Settings** - Visit `/admin/settings` to set logo and colors
+2. **Set Up Roles** - Assign users to admin/editor/viewer roles in Filament
+3. **Create Modules** - `php artisan make:module YourFeature`
+4. **Build API** - Use Sanctum tokens for API authentication
+5. **Write Tests** - `php artisan test` or `./vendor/bin/pest`
+6. **Configure Flare** - Optional: Get API key at [flareapp.io](https://flareapp.io)
+7. **Deploy** - See [Production Deployment](README.md#production-deployment)
+
+## Documentation
+
+- [README.md](README.md) - Overview and commands
+- [DEBUGGING.md](DEBUGGING.md) - **Debugging strategy (READ THIS FIRST)**
+- [FEATURES.md](FEATURES.md) - Complete feature reference
+- [AI_CONTEXT.md](AI_CONTEXT.md) - Context for AI assistants
+- [app/Modules/README.md](src/app/Modules/README.md) - Module system guide