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:

# 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

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

./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

# 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

# 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

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

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

docker-compose exec app php artisan optimize:clear
docker-compose exec app php artisan permission:cache-reset

---

Container won't start

# Check logs
make logs

# Reset everything
make clean
make install DB=mysql

Permission issues

make shell
chmod -R 775 storage bootstrap/cache

Database connection refused

# Wait for database to be ready
docker-compose exec mysql mysqladmin ping -h localhost

# Or restart
make down
make up

Artisan commands fail

# 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
7. Deploy - See Production Deployment

Documentation

• README.md - Overview and commands
• DEBUGGING.md - Debugging strategy (READ THIS FIRST)
• FEATURES.md - Complete feature reference
• AI_CONTEXT.md - Context for AI assistants
• app/Modules/README.md - Module system guide