theradcoza/Laravel-Docker-Dev-Template
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

templave v1

Browse Source
This commit is contained in:
theRADcozaDEV
2026-03-06 08:57:05 +02:00
commit 17dbdad28b
50 changed files with 8720 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

540
README.md Normal file
View File

@@ -0,0 +1,540 @@
# Laravel Docker Development Template
A comprehensive Laravel development environment with Docker for local development and deployment configurations for Ubuntu 24.04 with Nginx Proxy Manager or Apache.
> **New here?** Start with [GETTING_STARTED.md](GETTING_STARTED.md) for a step-by-step setup guide.
>
> **AI Assistant?** See [AI_CONTEXT.md](AI_CONTEXT.md) for project context and conventions.
## Architecture Overview
```
┌─────────────────────────────────────────────────────────────────┐
│ DEVELOPMENT (Docker) │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌───────────────┐ ┌─────┐ ┌─────┐ │
│ │ Nginx │──│ PHP │──│ MySQL/PgSQL/ │ │Redis│ │Mail │ │
│ │ :8080 │ │ FPM │ │ SQLite │ │:6379│ │:8025│ │
│ └─────────┘ └─────────┘ └───────────────┘ └─────┘ └─────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ PRODUCTION (Ubuntu 24.04 - No Docker) │
├─────────────────────────────────────────────────────────────────┤
│ Option A: Nginx Proxy Manager │
│ ┌───────────────┐ ┌─────────┐ ┌─────────┐ │
│ │ NPM (SSL/443) │───▶│ Nginx │───▶│ PHP-FPM │───▶ Laravel │
│ └───────────────┘ └─────────┘ └─────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ Option B: Apache Virtual Host │
│ ┌─────────────────┐ ┌─────────┐ │
│ │ Apache + SSL │───▶│ PHP-FPM │───▶ Laravel │
│ │ (Certbot) │ └─────────┘ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## Project Structure
```
├── docker/
│ ├── nginx/default.conf # Dev Nginx config
│ ├── php/
│ │ ├── Dockerfile # PHP-FPM image
│ │ └── local.ini # PHP dev settings
│ └── mysql/my.cnf # MySQL config
├── deploy/
│ ├── nginx/
│ │ ├── laravel-site.conf # Production Nginx config
│ │ └── nginx-proxy-manager-notes.md
│ ├── apache/
│ │ ├── laravel-site.conf # Apache virtual host
│ │ └── apache-setup.md
│ ├── production/
│ │ ├── .env.mysql.production # MySQL env template
│ │ ├── .env.pgsql.production # PostgreSQL env template
│ │ └── .env.sqlite.production # SQLite env template
│ └── scripts/
│ ├── server-setup.sh # Ubuntu server setup (DB selection)
│ ├── deploy.sh # Deployment script
│ ├── fix-permissions.sh # Permission fixer
│ ├── supervisor-worker.conf # Queue worker config
│ ├── supervisor-scheduler.conf # Scheduler config
│ └── laravel-scheduler.cron # Cron job template
├── src/
│ ├── .env.mysql # MySQL dev config
│ ├── .env.pgsql # PostgreSQL dev config
│ ├── .env.sqlite # SQLite dev config
│ └── pint.json # Code style config
├── scripts/
│ ├── post-install.sh # Flare/Telescope/Pint setup
│ └── laravel-setup.sh # Auth/API/Middleware setup
├── docs/
│ ├── error-logging.md # Error logging docs
│ ├── laravel-setup.md # Laravel setup guide
│ ├── filament-admin.md # Admin panel docs
│ ├── modules.md # Modular architecture guide
│ ├── audit-trail.md # Audit trail docs
│ ├── site-settings.md # Appearance settings
│ ├── testing.md # Pest testing guide
│ ├── queues.md # Background jobs
│ ├── ci-cd.md # GitHub Actions pipeline
│ └── backup.md # Database backup/restore
├── docker-compose.yml # Multi-DB profiles
├── Makefile
├── README.md
├── GETTING_STARTED.md # Step-by-step setup guide
└── AI_CONTEXT.md # Context for AI assistants
```
## Database Options
This template supports three database engines via Docker Compose profiles:
| Database | Profile | Port | Use Case |
|----------|---------|------|----------|
| MySQL 8.0 | `mysql` | 3306 | Production-grade, most Laravel tutorials |
| PostgreSQL 16 | `pgsql` | 5432 | Advanced features, JSON, full-text search |
| SQLite | `sqlite` | - | Lightweight, no server, great for testing |
## Quick Start (Development)
### Prerequisites
- Docker & Docker Compose
- Make (optional, for convenience commands)
### Setup
1. **Clone the repository**
```bash
git clone <repo-url> my-laravel-app
cd my-laravel-app
```
2. **Copy environment file**
```bash
cp .env.example .env
```
3. **Install Laravel with your preferred database**
```bash
# With MySQL (default)
make install DB=mysql
# With PostgreSQL
make install DB=pgsql
# With SQLite
make install DB=sqlite
# Or without Make:
docker-compose build
docker-compose --profile mysql run --rm app composer create-project laravel/laravel .
cp src/.env.mysql src/.env
```
4. **Start the development environment**
```bash
# Start with your chosen database
make up DB=mysql # or pgsql, sqlite
# Or: docker-compose --profile mysql up -d
```
5. **Access your application**
- Laravel App: http://localhost:8080
- Mailpit: http://localhost:8025
6. **Run setup scripts**
```bash
# Install Flare, Pint, error pages
make setup-tools
# Configure auth, API, middleware (interactive)
make setup-laravel
# Or run both
make setup-all
```
### Common Commands
| Command | Description |
|---------|-------------|
| `make up DB=mysql` | Start with MySQL |
| `make up DB=pgsql` | Start with PostgreSQL |
| `make up DB=sqlite` | Start with SQLite |
| `make down` | Stop all containers |
| `make shell` | Shell into app container |
| `make artisan cmd='migrate'` | Run Artisan commands |
| `make composer cmd='require package'` | Run Composer |
| `make logs` | View logs |
| `make fresh` | Fresh migrate + seed |
| `make lint` | Fix code style (Pint) |
| `make lint-check` | Check code style |
| `make test` | Run tests |
| `make setup-tools` | Install Flare, Pint, error pages |
| `make setup-laravel` | Configure auth, API, middleware |
| `make setup-all` | Run both setup scripts |
## Laravel Setup (Auth, API, Middleware)
After installing Laravel, run the interactive setup:
```bash
make setup-laravel
```
This configures:
| Feature | Options |
|---------|---------|
| **Authentication** | Breeze (Blade/Livewire/API) or Jetstream + Livewire |
| **Admin Panel** | Filament with user management |
| **Site Settings** | Logo, favicon, color scheme management |
| **Modules** | Modular architecture with `make:module` command |
| **Audit Trail** | Track all data changes with user, old/new values |
| **Testing** | Pest framework with module test generation |
| **Queues** | Redis-powered background jobs |
| **CI/CD** | GitHub Actions for tests + deploy |
| **Backup** | Database backup/restore scripts |
| **API** | Sanctum token authentication |
| **Middleware** | ForceHttps, SecurityHeaders |
| **Storage** | Public storage symlink |
> **Note:** This template focuses on Blade and Livewire (no Vue/React/Inertia). Server-side rendering keeps debugging simple.
### Admin Panel (Filament)
The setup includes optional [Filament](https://filamentphp.com/) admin panel:
- **User management** - List, create, edit, delete users
- **Dashboard** - Stats widgets, charts
- **Extensible** - Add resources for any model
Access at: `http://localhost:8080/admin`
See [docs/filament-admin.md](docs/filament-admin.md) for customization.
### Site Settings (Appearance)
Manage logo, favicon, and colors from admin panel:
```
/admin → Settings → Appearance
```
Use in Blade templates:
```blade
{{-- In your <head> --}}
<x-site-head :title="$title" />
{{-- Logo --}}
<img src="{{ site_logo() }}" alt="{{ site_name() }}">
{{-- Colors available as CSS variables --}}
<div class="bg-primary">Uses --primary-color</div>
```
See [docs/site-settings.md](docs/site-settings.md) for configuration.
### Modular Architecture
Build features as self-contained modules:
```bash
# Create a module with model and admin panel
php artisan make:module StockManagement --model=Product
# Creates:
# - app/Modules/StockManagement/
# - Routes, controllers, views
# - Filament admin resources
# - Permissions for role-based access
```
Each module gets:
- **Landing page** at `/{module-slug}`
- **Admin section** in Filament panel
- **Permissions** auto-registered with roles
See [docs/modules.md](docs/modules.md) for full documentation.
### Audit Trail
Every module includes an **Audit Log** page showing all data changes:
- **Who** changed what
- **Old → New** values
- **When** and from which **IP**
- Filterable by user, event type, date
Configure per module in `Config/module_name.php`:
```php
'audit' => [
'enabled' => true,
'strategy' => 'all', // 'all', 'include', 'exclude', 'none'
],
```
See [docs/audit-trail.md](docs/audit-trail.md) for configuration options.
See [docs/laravel-setup.md](docs/laravel-setup.md) for detailed configuration.
## Production Deployment
### Ubuntu 24.04 Server Setup
1. **Run server setup script**
```bash
sudo bash deploy/scripts/server-setup.sh
```
This installs:
- PHP 8.3 + extensions (MySQL, PostgreSQL, SQLite drivers)
- Composer
- Node.js 20
- Database server (MySQL, PostgreSQL, or SQLite - your choice)
- Redis
- Nginx or Apache (your choice)
2. **Create database** (based on your selection during setup)
**MySQL:**
```bash
sudo mysql_secure_installation
sudo mysql
CREATE DATABASE your_app;
CREATE USER 'your_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON your_app.* TO 'your_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```
**PostgreSQL:**
```bash
sudo -u postgres psql
CREATE DATABASE your_app;
CREATE USER your_user WITH ENCRYPTED PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE your_app TO your_user;
\q
```
**SQLite:**
```bash
touch /var/www/your-app/database/database.sqlite
chmod 664 /var/www/your-app/database/database.sqlite
chown www-data:www-data /var/www/your-app/database/database.sqlite
```
### Option A: Nginx + Nginx Proxy Manager
1. **Deploy your app**
```bash
cd /var/www
git clone <repo-url> your-app
cd your-app/src
composer install --no-dev --optimize-autoloader
# Copy the appropriate .env file for your database:
cp ../deploy/production/.env.mysql.production .env # For MySQL
cp ../deploy/production/.env.pgsql.production .env # For PostgreSQL
cp ../deploy/production/.env.sqlite.production .env # For SQLite
# Edit .env with your settings
php artisan key:generate
php artisan migrate
npm ci && npm run build
```
2. **Configure Nginx**
```bash
sudo cp deploy/nginx/laravel-site.conf /etc/nginx/sites-available/your-app
# Edit: server_name, root, log paths
sudo ln -s /etc/nginx/sites-available/your-app /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```
3. **Configure NPM**
- See `deploy/nginx/nginx-proxy-manager-notes.md` for NPM setup
4. **Fix permissions**
```bash
sudo bash deploy/scripts/fix-permissions.sh /var/www/your-app/src
```
### Option B: Apache Virtual Host
1. **Deploy your app** (same as above)
2. **Configure Apache**
```bash
sudo cp deploy/apache/laravel-site.conf /etc/apache2/sites-available/your-app.conf
# Edit: ServerName, DocumentRoot, paths
sudo a2ensite your-app.conf
sudo apache2ctl configtest
sudo systemctl reload apache2
```
3. **SSL with Certbot**
```bash
sudo certbot --apache -d your-domain.com
```
See `deploy/apache/apache-setup.md` for detailed instructions.
### Automated Deployments
Use the deployment script for updates:
```bash
sudo bash deploy/scripts/deploy.sh /var/www/your-app/src main
```
### Queue Workers (Optional)
If using queues:
```bash
sudo cp deploy/scripts/supervisor-worker.conf /etc/supervisor/conf.d/laravel-worker.conf
# Edit paths in the config
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*
```
## Services
### Development
| Service | Port | Description |
|---------|------|-------------|
| Nginx | 8080 | Web server |
| MySQL | 3306 | Database |
| Redis | 6379 | Cache/Queue |
| Mailpit | 8025 | Email testing UI |
| Mailpit SMTP | 1025 | SMTP server |
### Connecting to MySQL from host
```bash
mysql -h 127.0.0.1 -P 3306 -u laravel -p
# Password: secret (from .env)
```
## Error Logging
This template uses **Flare + Ignition** by Spatie for error tracking.
| Environment | Tool | What You Get |
|-------------|------|--------------|
| Development | Ignition | Rich error pages, AI explanations, click-to-open in VS Code |
| Production | Flare | Remote error tracking, clean user-facing error pages |
### Setup
After installing Laravel, run the post-install script:
```bash
make setup-tools
```
This installs:
- Flare for production error tracking
- Custom error pages (404, 500, 503)
- Optional: Laravel Telescope for debugging
Get your Flare API key at [flareapp.io](https://flareapp.io) and add to `.env`:
```env
FLARE_KEY=your_key_here
```
See [docs/error-logging.md](docs/error-logging.md) for full documentation.
## Code Style (Laravel Pint)
This template includes [Laravel Pint](https://laravel.com/docs/pint) for code style enforcement.
```bash
# Fix code style
make lint
# Check without fixing
make lint-check
```
Configuration: `src/pint.json` (uses Laravel preset with sensible defaults).
## Scheduler (Production)
Laravel's task scheduler needs to run every minute. Two options:
### Option 1: Cron (Recommended)
```bash
# Add to crontab
sudo crontab -e -u www-data
# Add this line:
* * * * * cd /var/www/your-app && php artisan schedule:run >> /dev/null 2>&1
```
### Option 2: Supervisor
```bash
sudo cp deploy/scripts/supervisor-scheduler.conf /etc/supervisor/conf.d/
# Edit paths in the config
sudo supervisorctl reread && sudo supervisorctl update
```
## Customization
### Changing PHP Version
Edit `docker/php/Dockerfile`:
```dockerfile
FROM php:8.2-fpm # Change version here
```
Then rebuild: `docker-compose build app`
### Adding PHP Extensions
Edit `docker/php/Dockerfile` and add to the install list, then rebuild.
### Using PostgreSQL
1. Uncomment PostgreSQL in `docker-compose.yml`
2. Update `src/.env`:
```
DB_CONNECTION=pgsql
DB_HOST=pgsql
```
## Troubleshooting
### Permission Issues
```bash
# Development
docker-compose exec app chmod -R 775 storage bootstrap/cache
# Production
sudo bash deploy/scripts/fix-permissions.sh /var/www/your-app/src
```
### Container won't start
```bash
docker-compose logs app # Check for errors
docker-compose down -v # Reset volumes
docker-compose up -d
```
### Database connection refused
- Ensure MySQL container is running: `docker-compose ps`
- Check `DB_HOST=mysql` in `src/.env` (not `localhost`)
## License
MIT