theradcoza/Laravel-Docker-Dev-Template
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity
Files
17dbdad28bcc18cdf628dcf117dd81b2ad3bf20d
Laravel-Docker-Dev-Template/GETTING_STARTED.md
theRADcozaDEV 17dbdad28b templave v1
2026-03-06 08:57:05 +02:00

7.2 KiB
Raw Blame History

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)

# 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

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

# 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

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

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

# 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