Laravel-Docker-Dev-Template/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
- **Dashboard** - Admin dashboard with widgets

### Development Tools
- **Pest** - Modern testing framework with elegant syntax
- **Laravel Pint** - Opinionated code style fixer
- **Mailpit** - Email testing tool

### Infrastructure
- **Docker** - Containerized development environment
- **MySQL/PostgreSQL/SQLite** - Choose your database
- **Redis** - Caching and queues
- **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
- Email testing: http://localhost:8025

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