theradcoza/Laravel-Docker-Dev-Template
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity
Files
a55fafd3a934fcdce9ca907082e50c7f82b8a008
Laravel-Docker-Dev-Template/GETTING_STARTED.md

7.9 KiB
Raw Blame History

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

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:

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:

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

# 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

# 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 Flare - Get API key at 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

Documentation

Reference in New Issue View Git Blame Copy Permalink