# Laravel Docker Development Template

A comprehensive Laravel development environment with Docker for local development and deployment configurations for Ubuntu 24.04 with Nginx Proxy Manager or Apache.

> **New here?** Start with [GETTING_STARTED.md](GETTING_STARTED.md) for a step-by-step setup guide.
>
> **AI Assistant?** See [CLAUDE.md](CLAUDE.md) for EXACT module templates and step-by-step instructions.
> Also see [AI_CONTEXT.md](AI_CONTEXT.md) for project context and conventions.

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                     DEVELOPMENT (Docker)                        │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌───────────────┐  ┌─────┐  ┌─────┐ │
│  │  Nginx  │──│   PHP   │──│ MySQL/PgSQL/  │  │Redis│  │Mail │ │
│  │  :8080  │  │   FPM   │  │    SQLite     │  │:6379│  │:8025│ │
│  └─────────┘  └─────────┘  └───────────────┘  └─────┘  └─────┘ │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│              PRODUCTION (Ubuntu 24.04 - No Docker)              │
├─────────────────────────────────────────────────────────────────┤
│  Option A: Nginx Proxy Manager                                  │
│  ┌───────────────┐    ┌─────────┐    ┌─────────┐               │
│  │ NPM (SSL/443) │───▶│  Nginx  │───▶│ PHP-FPM │───▶ Laravel   │
│  └───────────────┘    └─────────┘    └─────────┘               │
├─────────────────────────────────────────────────────────────────┤
│  Option B: Apache Virtual Host                                  │
│  ┌─────────────────┐    ┌─────────┐                            │
│  │ Apache + SSL    │───▶│ PHP-FPM │───▶ Laravel                │
│  │ (Certbot)       │    └─────────┘                            │
│  └─────────────────┘                                           │
└─────────────────────────────────────────────────────────────────┘
```

## Project Structure

```
├── docker/
│   ├── nginx/default.conf      # Dev Nginx config
│   ├── php/
│   │   ├── Dockerfile          # PHP-FPM image
│   │   └── local.ini           # PHP dev settings
│   └── mysql/my.cnf            # MySQL config
├── deploy/
│   ├── nginx/
│   │   ├── laravel-site.conf   # Production Nginx config
│   │   └── nginx-proxy-manager-notes.md
│   ├── apache/
│   │   ├── laravel-site.conf   # Apache virtual host
│   │   └── apache-setup.md
│   ├── production/
│   │   ├── .env.mysql.production   # MySQL env template
│   │   ├── .env.pgsql.production   # PostgreSQL env template
│   │   └── .env.sqlite.production  # SQLite env template
│   └── scripts/
│       ├── server-setup.sh         # Ubuntu server setup (DB selection)
│       ├── deploy.sh               # Deployment script
│       ├── fix-permissions.sh      # Permission fixer
│       ├── supervisor-worker.conf  # Queue worker config
│       ├── supervisor-scheduler.conf # Scheduler config
│       └── laravel-scheduler.cron  # Cron job template
├── src/
│   ├── .env.mysql              # MySQL dev config
│   ├── .env.pgsql              # PostgreSQL dev config
│   ├── .env.sqlite             # SQLite dev config
│   └── pint.json               # Code style config
├── scripts/
│   ├── post-install.sh         # Flare/Telescope/Pint setup
│   └── laravel-setup.sh        # Auth/API/Middleware setup
├── docs/
│   ├── error-logging.md        # Error logging docs
│   ├── laravel-setup.md        # Laravel setup guide
│   ├── filament-admin.md       # Admin panel docs
│   ├── modules.md              # Modular architecture guide
│   ├── audit-trail.md          # Audit trail docs
│   ├── site-settings.md        # Appearance settings
│   ├── testing.md              # Pest testing guide
│   ├── queues.md               # Background jobs
│   ├── ci-cd.md                # GitHub Actions pipeline
│   └── backup.md               # Database backup/restore
├── docker-compose.yml          # Multi-DB profiles
├── Makefile
├── README.md
├── GETTING_STARTED.md          # Step-by-step setup guide
└── AI_CONTEXT.md               # Context for AI assistants
```

## Database Options

This template supports three database engines via Docker Compose profiles:

| Database | Profile | Port | Use Case |
|----------|---------|------|----------|
| MySQL 8.0 | `mysql` | 3306 | Production-grade, most Laravel tutorials |
| PostgreSQL 16 | `pgsql` | 5432 | Advanced features, JSON, full-text search |
| SQLite | `sqlite` | - | Lightweight, no server, great for testing |

## Quick Start (Development)

### Prerequisites
- Docker & Docker Compose

### One-Command Setup

```bash
# Clone the repository
git clone <repo-url> my-laravel-app
cd my-laravel-app

# Run setup script (MySQL is default)
./setup.sh          # Linux/Mac
setup.bat           # Windows

# Or specify database:
./setup.sh mysql    # MySQL (default)
./setup.sh pgsql    # PostgreSQL
./setup.sh sqlite   # SQLite
```

**That's it!** The script will:
- ✅ Configure environment for your database
- ✅ Install composer dependencies
- ✅ Build and start Docker containers
- ✅ Run migrations
- ✅ Create admin user (admin@example.com / password)

**Everything is pre-installed:**
- ✅ Laravel 11 with Breeze authentication
- ✅ Filament admin panel with user management
- ✅ Pest testing framework
- ✅ Laravel Pint code style
- ✅ Queue workers & scheduler (optional)

**Access your app:**
- Laravel App: http://localhost:8080
- Admin Panel: http://localhost:8080/admin
- Mailpit: http://localhost:8025

**Admin Login:**
- Email: admin@example.com
- Password: password

### Manual Setup (Alternative)

If you prefer manual control:

1. **Clone and configure**
   ```bash
   git clone <repo-url> my-laravel-app
   cd my-laravel-app
   ```

2. **Build containers**
   ```bash
   docker-compose build
   ```

3. **Install Laravel**
   ```bash
   docker-compose --profile mysql run --rm app composer create-project laravel/laravel:^11.0 /tmp/new
   docker-compose --profile mysql run --rm app sh -c "cp -r /tmp/new/. /var/www/html/ && rm -rf /tmp/new"
   ```

4. **Configure environment**
   ```bash
   cp src/.env.mysql src/.env  # For MySQL
   # OR
   cp src/.env.pgsql src/.env  # For PostgreSQL
   # OR
   cp src/.env.sqlite src/.env # For SQLite
   ```

5. **Start containers**
   ```bash
   docker-compose --profile mysql up -d
   ```

6. **Run migrations**
   ```bash
   docker-compose exec app php artisan migrate --force
   ```

7. **Run setup scripts (optional)**
   ```bash
   docker-compose exec app bash scripts/laravel-setup.sh
   ```

### Common Commands

| Command | Description |
|---------|-------------|
| `make up DB=mysql` | Start with MySQL |
| `make up DB=pgsql` | Start with PostgreSQL |
| `make up DB=sqlite` | Start with SQLite |
| `make down` | Stop all containers |
| `make shell` | Shell into app container |
| `make artisan cmd='migrate'` | Run Artisan commands |
| `make composer cmd='require package'` | Run Composer |
| `make logs` | View logs |
| `make fresh` | Fresh migrate + seed |
| `make lint` | Fix code style (Pint) |
| `make lint-check` | Check code style |
| `make test` | Run tests |
| `make setup-tools` | Install Flare, Pint, error pages |
| `make setup-laravel` | Configure auth, API, middleware |
| `make setup-all` | Run both setup scripts |

## Laravel Setup (Auth, API, Middleware)

After installing Laravel, run the interactive setup:

```bash
make setup-laravel
```

This configures:

| Feature | Options |
|---------|---------|
| **Authentication** | Breeze (Blade/Livewire/API) or Jetstream + Livewire |
| **Admin Panel** | Filament with user management |
| **Site Settings** | Logo, favicon, color scheme management |
| **Modules** | Modular architecture with `make:module` command |
| **Audit Trail** | Track all data changes with user, old/new values |
| **Testing** | Pest framework with module test generation |
| **Queues** | Redis-powered background jobs |
| **CI/CD** | GitHub Actions for tests + deploy |
| **Backup** | Database backup/restore scripts |
| **API** | Sanctum token authentication |
| **Middleware** | ForceHttps, SecurityHeaders |
| **Storage** | Public storage symlink |

> **Note:** This template focuses on Blade and Livewire (no Vue/React/Inertia). Server-side rendering keeps debugging simple.

### Admin Panel (Filament)

The setup includes optional [Filament](https://filamentphp.com/) admin panel:

- **User management** - List, create, edit, delete users
- **Dashboard** - Stats widgets, charts
- **Extensible** - Add resources for any model

Access at: `http://localhost:8080/admin`

See [docs/filament-admin.md](docs/filament-admin.md) for customization.

### Site Settings (Appearance)

Manage logo, favicon, and colors from admin panel:

```
/admin → Settings → Appearance
```

Use in Blade templates:

```blade
{{-- In your <head> --}}
<x-site-head :title="$title" />

{{-- Logo --}}
<img src="{{ site_logo() }}" alt="{{ site_name() }}">

{{-- Colors available as CSS variables --}}
<div class="bg-primary">Uses --primary-color</div>
```

See [docs/site-settings.md](docs/site-settings.md) for configuration.

### Modular Architecture

Build features as self-contained modules:

```bash
# Create a module with model and admin panel
php artisan make:module StockManagement --model=Product

# Creates:
# - app/Modules/StockManagement/
# - Routes, controllers, views
# - Filament admin resources
# - Permissions for role-based access
```

Each module gets:
- **Landing page** at `/{module-slug}`
- **Admin section** in Filament panel
- **Permissions** auto-registered with roles

See [docs/modules.md](docs/modules.md) for full documentation.

### Audit Trail

Every module includes an **Audit Log** page showing all data changes:

- **Who** changed what
- **Old → New** values
- **When** and from which **IP**
- Filterable by user, event type, date

Configure per module in `Config/module_name.php`:

```php
'audit' => [
    'enabled' => true,
    'strategy' => 'all',  // 'all', 'include', 'exclude', 'none'
],
```

See [docs/audit-trail.md](docs/audit-trail.md) for configuration options.

See [docs/laravel-setup.md](docs/laravel-setup.md) for detailed configuration.

## Production Deployment

### Ubuntu 24.04 Server Setup

1. **Run server setup script**
   ```bash
   sudo bash deploy/scripts/server-setup.sh
   ```

   This installs:
   - PHP 8.3 + extensions (MySQL, PostgreSQL, SQLite drivers)
   - Composer
   - Node.js 20
   - Database server (MySQL, PostgreSQL, or SQLite - your choice)
   - Redis
   - Nginx or Apache (your choice)

2. **Create database** (based on your selection during setup)

   **MySQL:**
   ```bash
   sudo mysql_secure_installation
   sudo mysql
   CREATE DATABASE your_app;
   CREATE USER 'your_user'@'localhost' IDENTIFIED BY 'secure_password';
   GRANT ALL PRIVILEGES ON your_app.* TO 'your_user'@'localhost';
   FLUSH PRIVILEGES;
   EXIT;
   ```

   **PostgreSQL:**
   ```bash
   sudo -u postgres psql
   CREATE DATABASE your_app;
   CREATE USER your_user WITH ENCRYPTED PASSWORD 'secure_password';
   GRANT ALL PRIVILEGES ON DATABASE your_app TO your_user;
   \q
   ```

   **SQLite:**
   ```bash
   touch /var/www/your-app/database/database.sqlite
   chmod 664 /var/www/your-app/database/database.sqlite
   chown www-data:www-data /var/www/your-app/database/database.sqlite
   ```

### Option A: Nginx + Nginx Proxy Manager

1. **Deploy your app**
   ```bash
   cd /var/www
   git clone <repo-url> your-app
   cd your-app/src
   composer install --no-dev --optimize-autoloader
   
   # Copy the appropriate .env file for your database:
   cp ../deploy/production/.env.mysql.production .env   # For MySQL
   cp ../deploy/production/.env.pgsql.production .env   # For PostgreSQL
   cp ../deploy/production/.env.sqlite.production .env  # For SQLite
   
   # Edit .env with your settings
   php artisan key:generate
   php artisan migrate
   npm install && npm run build
   ```

2. **Configure Nginx**
   ```bash
   sudo cp deploy/nginx/laravel-site.conf /etc/nginx/sites-available/your-app
   # Edit: server_name, root, log paths
   sudo ln -s /etc/nginx/sites-available/your-app /etc/nginx/sites-enabled/
   sudo nginx -t
   sudo systemctl reload nginx
   ```

3. **Configure NPM**
   - See `deploy/nginx/nginx-proxy-manager-notes.md` for NPM setup

4. **Fix permissions**
   ```bash
   sudo bash deploy/scripts/fix-permissions.sh /var/www/your-app/src
   ```

### Option B: Apache Virtual Host

1. **Deploy your app** (same as above)

2. **Configure Apache**
   ```bash
   sudo cp deploy/apache/laravel-site.conf /etc/apache2/sites-available/your-app.conf
   # Edit: ServerName, DocumentRoot, paths
   sudo a2ensite your-app.conf
   sudo apache2ctl configtest
   sudo systemctl reload apache2
   ```

3. **SSL with Certbot**
   ```bash
   sudo certbot --apache -d your-domain.com
   ```

See `deploy/apache/apache-setup.md` for detailed instructions.

### Automated Deployments

Use the deployment script for updates:
```bash
sudo bash deploy/scripts/deploy.sh /var/www/your-app/src main
```

### Queue Workers (Optional)

If using queues:
```bash
sudo cp deploy/scripts/supervisor-worker.conf /etc/supervisor/conf.d/laravel-worker.conf
# Edit paths in the config
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*
```

## Services

### Development

| Service | Port | Description |
|---------|------|-------------|
| Nginx | 8080 | Web server |
| MySQL | 3306 | Database |
| Redis | 6379 | Cache/Queue |
| Mailpit | 8025 | Email testing UI |
| Mailpit SMTP | 1025 | SMTP server |

### Connecting to MySQL from host

```bash
mysql -h 127.0.0.1 -P 3306 -u laravel -p
# Password: secret (from .env)
```

## Error Logging

This template uses **Flare + Ignition** by Spatie for error tracking.

| Environment | Tool | What You Get |
|-------------|------|--------------|
| Development | Ignition | Rich error pages, AI explanations, click-to-open in VS Code |
| Production | Flare | Remote error tracking, clean user-facing error pages |

### Setup

After installing Laravel, run the post-install script:

```bash
make setup-tools
```

This installs:
- Flare for production error tracking
- Custom error pages (404, 500, 503)
- Optional: Laravel Telescope for debugging

Get your Flare API key at [flareapp.io](https://flareapp.io) and add to `.env`:

```env
FLARE_KEY=your_key_here
```

See [docs/error-logging.md](docs/error-logging.md) for full documentation.

## Code Style (Laravel Pint)

This template includes [Laravel Pint](https://laravel.com/docs/pint) for code style enforcement.

```bash
# Fix code style
make lint

# Check without fixing
make lint-check
```

Configuration: `src/pint.json` (uses Laravel preset with sensible defaults).

## Scheduler (Production)

Laravel's task scheduler needs to run every minute. Two options:

### Option 1: Cron (Recommended)

```bash
# Add to crontab
sudo crontab -e -u www-data

# Add this line:
* * * * * cd /var/www/your-app && php artisan schedule:run >> /dev/null 2>&1
```

### Option 2: Supervisor

```bash
sudo cp deploy/scripts/supervisor-scheduler.conf /etc/supervisor/conf.d/
# Edit paths in the config
sudo supervisorctl reread && sudo supervisorctl update
```

## Customization

### Changing PHP Version

Edit `docker/php/Dockerfile`:
```dockerfile
FROM php:8.2-fpm  # Change version here
```

Then rebuild: `docker-compose build app`

### Adding PHP Extensions

Edit `docker/php/Dockerfile` and add to the install list, then rebuild.

### Using PostgreSQL

1. Uncomment PostgreSQL in `docker-compose.yml`
2. Update `src/.env`:
   ```
   DB_CONNECTION=pgsql
   DB_HOST=pgsql
   ```

## Troubleshooting

### Permission Issues
```bash
# Development
docker-compose exec app chmod -R 775 storage bootstrap/cache

# Production
sudo bash deploy/scripts/fix-permissions.sh /var/www/your-app/src
```

### Container won't start
```bash
docker-compose logs app  # Check for errors
docker-compose down -v   # Reset volumes
docker-compose up -d
```

### Database connection refused
- Ensure MySQL container is running: `docker-compose ps`
- Check `DB_HOST=mysql` in `src/.env` (not `localhost`)

## License

MIT