Docker Laravel FrankenPHP 8.4

Production-ready Docker setup for Laravel 11 with FrankenPHP 8.4, optimized for Docker cache efficiency and CI/CD pipelines.

🎯 Features

• Base Runtime Image: Reusable base image with all system dependencies and PHP extensions
• Multi-Architecture Support: Native support for linux/amd64 and linux/arm64 (Apple Silicon, AWS Graviton)
• Dual Registry Support: Push to Scaleway Container Registry and GitHub Container Registry (GHCR)
• Full & Slim Variants: Standard production image and minimized slim variant
• Optimized Layer Caching: Strategic layer ordering maximizes Docker cache hits
• Laravel 11 Ready: Pre-configured for Laravel 11 with PHP 8.4
• Production OPcache: Optimized OPcache settings with JIT compilation
• Redis Support: Full Redis support for cache, sessions, and queues
• Doppler Integration: Optional secrets management (can be used or ignored)
• Kubernetes Compatible: Logs to stderr, health checks, proper signal handling
• Laravel Octane: FrankenPHP worker mode for high-performance applications
• Multi-Stage Build: Separate stages for dependencies, frontend, and final image
• Security Hardened: Non-root user, minimal attack surface

📋 Prerequisites

• Docker 20.10+
• Docker Compose 2.0+
• Laravel 11 project
• (Optional) Doppler CLI for secrets management

🚀 Quick Start

For Development

1. Clone this repository into your Laravel project or copy the Docker files:

# Copy to your Laravel project
cp Dockerfile docker-compose.yml Caddyfile .dockerignore /path/to/your/laravel/project/

2. Create .env file from example:

cp .env.example .env
# Edit .env with your configuration

3. Start the development environment:

docker-compose up -d

4. Access your application:

• Application: http://localhost
• Redis Commander: http://localhost:8081 (with debug profile)
• Mailhog: http://localhost:8025 (with debug profile)

For Production

Build the optimized production image:

# Build base runtime (cached for future builds)
docker build --target base-runtime -t my-app-base:latest .

# Build final production image
docker build --target app -t my-app:latest .

# Or build for multiple architectures (amd64 + arm64)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --target app \
  -t my-app:latest \
  --load \
  .

# Run production container
docker run -d \
  -p 80:80 \
  -p 443:443 \
  -e APP_ENV=production \
  -e APP_KEY=your-app-key \
  -e DB_HOST=your-db-host \
  --name laravel-app \
  my-app:latest

🏗️ Architecture & Layer Optimization

Multi-Stage Build Strategy

The Dockerfile uses a multi-stage build with four stages, optimized for maximum cache efficiency:

┌─────────────────────┐
│  1. base-runtime    │  ← Cached for weeks/months (rarely changes)
│  System packages    │
│  PHP extensions     │
│  OPcache config     │
│  Composer binary    │
└─────────────────────┘
          ↓
┌─────────────────────┐
│  2. dependencies    │  ← Cached until composer.json/lock changes
│  composer.json      │
│  composer install   │
└─────────────────────┘
          ↓
┌─────────────────────┐
│  3. frontend-build  │  ← Parallel build, cached until package.json changes
│  package.json       │
│  npm install        │
│  npm run build      │
└─────────────────────┘
          ↓
┌─────────────────────┐
│  4. app (final)     │  ← Rebuilt on every code change
│  Application code   │
│  Built assets       │
│  Vendor from stage 2│
└─────────────────────┘

Layer Ordering Rationale

Why this order maximizes cache efficiency:

1. Base Runtime (Stage 1) - Changes: ~1-2 times per year

   • System packages and PHP extensions
   • OPcache configuration
   • Reason: Infrastructure dependencies rarely change
   • Cache Hit Rate: 99%+ in CI/CD

2. Dependencies (Stage 2) - Changes: ~Weekly

   • Composer dependencies
   • Only rebuilds when composer.json or composer.lock changes
   • Cache Hit Rate: 90%+ in CI/CD

3. Frontend Build (Stage 3) - Changes: ~Weekly

   • Node dependencies and built assets
   • Runs in parallel with dependencies stage
   • Only rebuilds when package.json or frontend code changes
   • Cache Hit Rate: 85%+ in CI/CD

4. Application (Stage 4) - Changes: Every commit

   • Application source code
   • Combines cached layers from stages 1, 2, and 3
   • Only this layer rebuilds on code changes

Cache Efficiency Gains

Traditional Single-Stage Build:

• Every code change: ~5-10 minutes (full rebuild)
• Composer install: ~2-3 minutes
• System packages: ~1-2 minutes
• PHP extensions: ~1-2 minutes

Optimized Multi-Stage Build:

• First build: ~5-10 minutes (same as traditional)
• Subsequent builds with code changes only: ~30 seconds
• Builds with new dependencies: ~2-3 minutes
• Builds with infrastructure changes: ~5-10 minutes

CI/CD Pipeline Improvements:

• Average build time reduction: 80-90%
• Docker registry bandwidth savings: 70-80%
• Build cache reuse across branches: Yes
• Parallel frontend/backend builds: Yes

🔧 Configuration

Environment Variables

Key environment variables for production:

# FrankenPHP Workers (adjust based on CPU cores)
FRANKENPHP_NUM_WORKERS=4

# Server name for Caddy
SERVER_NAME=:80

# Laravel configuration
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:...

# Database
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=secret

# Redis (recommended for Octane)
REDIS_HOST=redis
REDIS_PORT=6379
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

# Logging (stderr for K8S)
LOG_CHANNEL=stderr
LOG_LEVEL=error

OPcache Configuration

Production OPcache settings (pre-configured):

opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=20000
opcache.validate_timestamps=0  # Disable in production
opcache.save_comments=1
opcache.fast_shutdown=1
opcache.jit=tracing
opcache.jit_buffer_size=100M

Why these settings?

• validate_timestamps=0: Maximum performance, requires container restart for code updates
• max_accelerated_files=20000: Handles large Laravel applications with many classes
• jit=tracing: PHP 8.4 JIT compiler for 20-30% performance boost
• jit_buffer_size=100M: Adequate for most Laravel applications

FrankenPHP Worker Configuration

Configure workers in Caddyfile:

{
    frankenphp {
        num_workers {$FRANKENPHP_NUM_WORKERS:4}
    }
}

Worker Sizing Guide:

• Development: 1-2 workers
• Small Production: 2-4 workers (1-2 CPU cores)
• Medium Production: 4-8 workers (2-4 CPU cores)
• Large Production: 8-16 workers (4-8 CPU cores)

Rule of thumb: 2 workers per CPU core, adjust based on load testing.

🔐 Security Features

1. Non-root User: Application runs as www-data
2. Minimal Base: Based on Debian Bookworm (slim)
3. Security Headers: Pre-configured in Caddyfile
4. No Development Tools: Production image excludes dev dependencies
5. Secret Management: Doppler CLI included (optional usage)
6. Regular Updates: Based on official FrankenPHP image

☸️ Kubernetes Deployment

Example Deployment YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: laravel-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: laravel
  template:
    metadata:
      labels:
        app: laravel
    spec:
      containers:
      - name: app
        image: my-app:latest
        ports:
        - containerPort: 80
        env:
        - name: APP_ENV
          value: "production"
        - name: APP_KEY
          valueFrom:
            secretKeyRef:
              name: laravel-secrets
              key: app-key
        - name: DB_HOST
          value: "mysql-service"
        - name: REDIS_HOST
          value: "redis-service"
        - name: FRANKENPHP_NUM_WORKERS
          value: "4"
        livenessProbe:
          httpGet:
            path: /up
            port: 80
          initialDelaySeconds: 40
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /up
            port: 80
          initialDelaySeconds: 10
          periodSeconds: 5
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "1Gi"
            cpu: "1000m"
---
apiVersion: v1
kind: Service
metadata:
  name: laravel-service
spec:
  selector:
    app: laravel
  ports:
  - port: 80
    targetPort: 80
  type: ClusterIP

Health Check Endpoint

The /up endpoint is pre-configured for Kubernetes health checks:

curl http://localhost/up
# Returns: OK (200)

🎨 Frontend Assets

The Dockerfile includes a separate stage for building frontend assets:

FROM node:20-bookworm-slim AS frontend-builder
# ... builds Vite/Mix assets

Benefits:

• Parallel build with backend dependencies
• Cached until package.json or frontend code changes
• Smaller final image (Node.js not included)

🔍 Doppler Integration (Optional)

Doppler CLI is pre-installed but optional:

Using Doppler

# In Dockerfile or entrypoint
doppler run -- php artisan serve

# In Kubernetes
env:
- name: DOPPLER_TOKEN
  valueFrom:
    secretKeyRef:
      name: doppler-token
      key: token

Not Using Doppler

Simply ignore it - the image works perfectly without Doppler. Use standard environment variables or Kubernetes secrets.

📊 Performance Benchmarks

Typical performance improvements with this setup:

Metric	Traditional PHP-FPM	FrankenPHP + Octane
Requests/sec	100-200	1,000-2,000
Response time (avg)	50-100ms	5-15ms
Memory usage	50-100MB/worker	30-50MB/worker
Cold start time	1-2s	100-200ms

Note: Actual performance depends on application complexity and database queries.

🛠️ Development Workflow

Local Development

# Start development environment
docker-compose up -d

# View logs
docker-compose logs -f app

# Run artisan commands
docker-compose exec app php artisan migrate

# Install new composer package
docker-compose exec app composer require vendor/package

# Run tests
docker-compose exec app php artisan test

# Access MySQL
docker-compose exec mysql mysql -u laravel -p laravel

# Access Redis CLI
docker-compose exec redis redis-cli

Debug Mode

Enable debug services (Redis Commander, Mailhog):

docker-compose --profile debug up -d

🔄 CI/CD Integration

GitHub Actions Example

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2
      
      - name: Cache Docker layers
        uses: actions/cache@v3
        with:
          path: /tmp/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-buildx-
      
      - name: Build base runtime
        uses: docker/build-push-action@v4
        with:
          context: .
          target: base-runtime
          tags: my-app-base:latest
          cache-from: type=local,src=/tmp/.buildx-cache
          cache-to: type=local,dest=/tmp/.buildx-cache-new
      
      - name: Build application
        uses: docker/build-push-action@v4
        with:
          context: .
          target: app
          push: true
          tags: my-app:${{ github.sha }}
          cache-from: type=local,src=/tmp/.buildx-cache
          cache-to: type=local,dest=/tmp/.buildx-cache-new
      
      - name: Move cache
        run: |
          rm -rf /tmp/.buildx-cache
          mv /tmp/.buildx-cache-new /tmp/.buildx-cache

GitLab CI Example

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker build --target base-runtime -t $CI_REGISTRY_IMAGE:base .
    - docker build --target app -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  cache:
    key: docker-cache
    paths:
      - .docker-cache/

📦 Build Targets

The Dockerfile provides multiple build targets:

# Base runtime only (for CI cache)
docker build --target base-runtime -t my-app-base .

# Dependencies only (for debugging)
docker build --target dependencies -t my-app-deps .

# Frontend build only (for debugging)
docker build --target frontend-builder -t my-app-frontend .

# Development image (with dev tools)
docker build --target dev -t my-app-dev .

# Production image (default)
docker build --target app -t my-app .

# Slim production image (minimal, without dev tools)
docker build --target slim -t my-app-slim .

Image Variants

Full Image (app target):

• Complete production setup with all tools
• Includes git, curl, and development utilities
• Doppler CLI for secrets management
• Recommended for most production use cases
• Size: ~800MB

Slim Image (slim target):

• Minimized production image
• Removes git, curl, vim, nano, and other dev tools
• Removes Doppler CLI (use K8S secrets instead)
• Optimized for environments with strict size constraints
• Size: ~650MB (20% smaller)
• Use when: deploying to edge locations, bandwidth-constrained, or security-hardened environments

Multi-Architecture Builds

Build for both AMD64 (Intel/AMD) and ARM64 (Apple Silicon, AWS Graviton):

# Setup buildx (first time only)
make setup-buildx

# Build for multiple architectures
make build-multiarch

# Push multi-arch image to registry
make push-multiarch REGISTRY=ghcr.io/your-org

See MULTIARCH.md for detailed multi-architecture documentation.

🔄 CI/CD with Dual Registry Support

The project includes a GitHub Actions workflow (docker-build.yml) that automatically builds and pushes images to both:

• Scaleway Container Registry (rg.fr-par.scw.cloud/registry-ixys-dev)
• GitHub Container Registry (ghcr.io)

Workflow Behavior

Build triggers:

• Push to main, develop, or feature/* branches
• Pull requests to main or develop
• Release published
• Manual workflow dispatch

Push behavior:

• ✅ Pushes to registries: Push to main or develop, or release published
• ❌ Build only (no push): Pull requests or feature branches

Image Tags

For each build, the following tags are created:

Full image:

• {branch}_{sha} - Specific build (e.g., main_abc1234)
• {branch} - Latest for branch (e.g., main, develop)
• latest - Latest on main branch
• {version} - Release tag (e.g., v1.2.3) - only on release events

Slim image:

• {branch}_{sha}-slim
• {branch}-slim
• slim - Latest slim on main branch
• {version}-slim - Release slim tag

Required Secrets

Configure these secrets in your GitHub repository:

SCW_REGISTRY_PASSWORD - Scaleway Container Registry password
GITHUB_TOKEN - Automatically provided by GitHub Actions

Example Usage

# Pull from GHCR
docker pull ghcr.io/your-org/your-app:latest
docker pull ghcr.io/your-org/your-app:slim

# Pull from Scaleway
docker pull rg.fr-par.scw.cloud/registry-ixys-dev/your-app:latest
docker pull rg.fr-par.scw.cloud/registry-ixys-dev/your-app:slim

# Pull specific version
docker pull ghcr.io/your-org/your-app:v1.2.3
docker pull ghcr.io/your-org/your-app:v1.2.3-slim

🐛 Troubleshooting

OPcache Not Working

If you need to disable validation in production:

docker exec -it laravel-app php -r "opcache_reset();"

Workers Not Starting

Check FrankenPHP logs:

docker logs laravel-app

Adjust worker count:

docker run -e FRANKENPHP_NUM_WORKERS=2 my-app:latest

Permission Issues

Ensure proper ownership:

docker exec -it laravel-app chown -R www-data:www-data /app/storage

Build Cache Issues

Clear Docker build cache:

docker builder prune -af

📄 License

MIT License - See LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please ensure:

1. Docker layer ordering is maintained
2. Cache efficiency is not reduced
3. Security best practices are followed
4. Documentation is updated

🔗 Resources

• FrankenPHP Documentation
• Laravel 11 Documentation
• Laravel Octane Documentation
• Docker Best Practices
• Docker Buildx Multi-Platform
• Doppler Documentation
• AWS Graviton

📚 Additional Documentation

• WORKFLOW_DUAL_REGISTRY.md - Complete guide for Scaleway + GHCR workflow
• USAGE_EXAMPLES.md - Practical examples for Docker Compose, Kubernetes, AWS, etc.
• MULTIARCH.md - Multi-architecture deep dive
• ARCHITECTURE.md - Visual diagrams and flows
• DOCKER_OPTIMIZATION.md - Technical optimization details
• CONTRIBUTING.md - Maintenance and contribution guide
• SUMMARY.md - Complete project overview

📈 Version History

• v1.1.0 - Multi-architecture support
  • Added linux/amd64 and linux/arm64 support
  • Apple Silicon native performance
  • AWS Graviton compatibility
  • Updated CI/CD for multi-arch builds
• v1.0.0 - Initial release with optimized multi-stage build
  • FrankenPHP 1 with PHP 8.4
  • Laravel 11 support
  • OPcache with JIT
  • Redis support
  • Kubernetes compatibility
  • 80-90% CI/CD build time reduction