generated from theradcoza/Laravel-Docker-Dev-Template
571 lines
18 KiB
Markdown
571 lines
18 KiB
Markdown
# 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
|
|
|
|
### One-Command Setup
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <repo-url> my-laravel-app
|
|
cd my-laravel-app
|
|
|
|
# Run setup script (MySQL is default)
|
|
./setup.sh # Linux/Mac
|
|
setup.bat # Windows
|
|
|
|
# Or specify database:
|
|
./setup.sh mysql # MySQL (default)
|
|
./setup.sh pgsql # PostgreSQL
|
|
./setup.sh sqlite # SQLite
|
|
```
|
|
|
|
**That's it!** The script will:
|
|
- ✅ Configure environment for your database
|
|
- ✅ Install composer dependencies
|
|
- ✅ Build and start Docker containers
|
|
- ✅ Run migrations
|
|
- ✅ Create admin user (admin@example.com / password)
|
|
|
|
**Everything is pre-installed:**
|
|
- ✅ Laravel 11 with Breeze authentication
|
|
- ✅ Filament admin panel with user management
|
|
- ✅ Pest testing framework
|
|
- ✅ Laravel Pint code style
|
|
- ✅ Queue workers & scheduler (optional)
|
|
|
|
**Access your app:**
|
|
- Laravel App: http://localhost:8080
|
|
- Admin Panel: http://localhost:8080/admin
|
|
- Mailpit: http://localhost:8025
|
|
|
|
**Admin Login:**
|
|
- Email: admin@example.com
|
|
- Password: password
|
|
|
|
### Manual Setup (Alternative)
|
|
|
|
If you prefer manual control:
|
|
|
|
1. **Clone and configure**
|
|
```bash
|
|
git clone <repo-url> my-laravel-app
|
|
cd my-laravel-app
|
|
```
|
|
|
|
2. **Build containers**
|
|
```bash
|
|
docker-compose build
|
|
```
|
|
|
|
3. **Install Laravel**
|
|
```bash
|
|
docker-compose --profile mysql run --rm app composer create-project laravel/laravel:^11.0 /tmp/new
|
|
docker-compose --profile mysql run --rm app sh -c "cp -r /tmp/new/. /var/www/html/ && rm -rf /tmp/new"
|
|
```
|
|
|
|
4. **Configure environment**
|
|
```bash
|
|
cp src/.env.mysql src/.env # For MySQL
|
|
# OR
|
|
cp src/.env.pgsql src/.env # For PostgreSQL
|
|
# OR
|
|
cp src/.env.sqlite src/.env # For SQLite
|
|
```
|
|
|
|
5. **Start containers**
|
|
```bash
|
|
docker-compose --profile mysql up -d
|
|
```
|
|
|
|
6. **Run migrations**
|
|
```bash
|
|
docker-compose exec app php artisan migrate --force
|
|
```
|
|
|
|
7. **Run setup scripts (optional)**
|
|
```bash
|
|
docker-compose exec app bash scripts/laravel-setup.sh
|
|
```
|
|
|
|
### 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
|