Laravel-Docker-Dev-Template/GETTING_STARTED.md

# Getting Started

This guide walks you through setting up a new Laravel project using this template.

## Prerequisites

- Docker & Docker Compose
- Git
- Make (optional, but recommended)

## Quick Start (5 minutes)

```bash
# 1. Clone the template
git clone https://github.com/your-repo/Laravel-Docker-Dev-Template.git my-project
cd my-project

# 2. Copy environment file
cp .env.example .env

# 3. Choose your database and start
make install DB=mysql    # or: pgsql, sqlite

# 4. Run setup scripts (interactive)
make setup-tools         # Flare, Pint, error pages
make setup-laravel       # Auth, Filament, modules, audit trail

# 5. Access your app
# Laravel: http://localhost:8080
# Admin:   http://localhost:8080/admin
# Mail:    http://localhost:8025
```

## Step-by-Step Setup

### 1. Clone and Configure

```bash
git clone https://github.com/your-repo/Laravel-Docker-Dev-Template.git my-project
cd my-project

# Remove template git history and start fresh
rm -rf .git
git init
```

### 2. Choose Database

| Database | Best For | Command |
|----------|----------|---------|
| **MySQL** | Most projects, production parity | `make install DB=mysql` |
| **PostgreSQL** | Advanced features, JSON, full-text search | `make install DB=pgsql` |
| **SQLite** | Simple apps, quick prototyping | `make install DB=sqlite` |

### 3. Install Laravel

```bash
# Start containers and create Laravel project
make install DB=mysql

# This will:
# - Build Docker images
# - Start containers
# - Run composer create-project laravel/laravel
# - Copy appropriate .env file
# - Generate app key
# - Run initial migrations
```

### 4. Run Setup Scripts

#### Post-Install Tools

```bash
make setup-tools
```

Installs:
- ✅ Spatie Ignition (dev error pages)
- ✅ Spatie Flare (production error tracking)
- ✅ Laravel Pint (code style)
- ✅ Custom error pages (404, 500, 503)
- ❓ Laravel Telescope (optional debugging)

#### Laravel Base Setup

```bash
make setup-laravel
```

Interactive prompts for:

1. **Authentication** - Choose one:
   - Breeze + Blade (recommended)
   - Breeze + Livewire
   - Breeze API only
   - Jetstream + Livewire

2. **Filament Admin** - User management dashboard

3. **Audit Trail** - Track all data changes

4. **Module System** - Modular architecture

5. **API (Sanctum)** - Token authentication

6. **Security Middleware** - HTTPS, headers

### 5. Create Your First Module

```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 module
php artisan make:module ModuleName

# With model
php artisan make:module ModuleName --model=ModelName

# With API
php artisan make:module ModuleName --api

# Without Filament
php artisan make:module ModuleName --no-filament
```

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

### 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 Flare** - Get API key at [flareapp.io](https://flareapp.io)
2. **Create modules** - `php artisan make:module YourFeature`
3. **Add models** - `php artisan make:module YourFeature --model=YourModel`
4. **Write tests** - `make test`
5. **Deploy** - See [Production Deployment](README.md#production-deployment)

## Documentation

- [README.md](README.md) - Overview and commands
- [docs/laravel-setup.md](docs/laravel-setup.md) - Detailed setup options
- [docs/modules.md](docs/modules.md) - Module architecture
- [docs/audit-trail.md](docs/audit-trail.md) - Audit configuration
- [docs/filament-admin.md](docs/filament-admin.md) - Admin panel
- [docs/error-logging.md](docs/error-logging.md) - Error tracking
- [docs/queues.md](docs/queues.md) - Background jobs
- [docs/ci-cd.md](docs/ci-cd.md) - CI/CD pipeline
- [docs/backup.md](docs/backup.md) - Database backup