shell-leaderboard/GETTING_STARTED.md

# 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