FrankenPHP Docker Environment

A modern, lightweight Docker environment for PHP applications using FrankenPHP, featuring HTTP/2, HTTP/3, automatic HTTPS, and built-in Node.js support for multiple PHP frameworks.

Features

• 🚀 FrankenPHP Server: Modern PHP server with HTTP/2, HTTP/3, and automatic HTTPS via Caddy
• 🗄️ MariaDB Database: Persistent relational database for your applications
• 📦 Node.js Integration: Full Node.js runtime (v20.x) for frontend tooling and build processes
• 🎯 Multi-Framework Support: Optimized build targets for Laravel, Symfony, Magento2, WordPress, and OpenCart
• 📝 PHP 8.0 - 8.5: Support for multiple PHP versions with configurable extensions
• 🔧 Flexible Configuration: Local, proxy, and production modes
• 🔒 Automatic HTTPS: Let's Encrypt SSL certificates in production
• 🎨 Extension-Rich: Pre-installed essential PHP extensions (PDO/MySQL, Redis, APCu, and more)
• ⚡ Alpine-Based: Lightweight, fast, and efficient container images
• 🔄 Hot Reload: Automatic code reloading during development

Requirements

• Docker Desktop (or Docker Engine + Docker Compose)
• 2GB+ RAM available
• Terminal/Command-line access

Quick Start

1. Clone the Repository

git clone <repository-url>
cd franken

2. Configure Environment

cp .env.example .env

Edit the .env file with your preferred settings:

# Core Configuration
PHP_VERSION=8.4              # PHP version (8.0-8.5)
FRAMEWORK=opencart           # Framework: laravel, symfony, magento2, wordpress, opencart
MODE=proxy                   # Mode: local, prod, proxy
PORT=80                      # Local port
PROJECT_NAME=opencart        # Project name

# Database Configuration
MYSQL_ROOT_PASSWORD=root
MYSQL_DATABASE=database
MYSQL_USER_DATABASE=app
MYSQL_PASSWORD_DATABASE=secret

3. Start Services

docker-compose up -d

4. Access Your Application

• Local/Proxy Mode: http://localhost:{PORT}
  • Default: http://localhost:80

Configuration Guide

Environment Variables

Variable	Description	Options
PHP_VERSION	PHP version	8.0, 8.1, 8.2, 8.3, 8.4, 8.5
FRAMEWORK	Target framework	laravel, symfony, magento2, wordpress, opencart
MODE	Run mode	local (dev), proxy (behind reverse proxy), prod (production)
PORT	HTTP port	Any available port (default: 80)
PROJECT_NAME	Project identifier	Any alphanumeric name
MYSQL_ROOT_PASSWORD	Database root password	Your secure password
MYSQL_DATABASE	Database name	database
MYSQL_USER_DATABASE	Database user	app
MYSQL_PASSWORD_DATABASE	Database user password	Your secure password
SERVER_NAME	Domain (prod mode)	Your domain (e.g., example.com)

Framework-Specific Setup

Laravel

1. Update .env:

   FRAMEWORK=laravel
   

2. Uncomment Laravel volume in docker-compose.yml:

   volumes:
     - ./www:/app          # Instead of /app/public
   

3. Start services:

   docker-compose up -d --build
   

Symfony

1. Update .env:

   FRAMEWORK=symfony
   

2. Uncomment Symfony volume in docker-compose.yml:

   volumes:
     - ./www:/app          # Instead of /app/public
   

3. Build and start:

   docker-compose up -d --build
   

WordPress

1. Update .env:

   FRAMEWORK=wordpress
   

2. The default volume mount /app/public works for WordPress

3. Start services:

   docker-compose up -d --build
   

OpenCart

1. Update .env:

   FRAMEWORK=opencart
   

2. Default configuration uses /app/public

3. Start services:

   docker-compose up -d --build
   

Magento 2

1. Update .env:

   FRAMEWORK=magento2
   

2. Start services:

   docker-compose up -d --build
   

Modes Explained

• local: Development mode with internal TLS disabled, suitable for local development
• proxy: Designed for use behind a reverse proxy or load balancer
• prod: Production mode with HTTPS enabled, automatic SSL certificates, and optimized PHP settings

Production Deployment

1. Update .env:

   MODE=prod
   SERVER_NAME=yourdomain.com
   PHP_VERSION=8.4
   

2. Enable HTTPS in docker-compose.yml:

   ports:
     - "443:443"           # HTTPS
     - "443:443/udp"       # HTTP/3
   

3. Start services:

   docker-compose up -d --build
   

4. FrankenPHP automatically obtains SSL certificates from Let's Encrypt

How to Run

Start Services

# Start in background
docker-compose up -d

# Start with output
docker-compose up

# Start and rebuild images
docker-compose up -d --build

Stop Services

docker-compose down

View Logs

# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f php
docker-compose logs -f db

Access Container Shell

# PHP container
docker-compose exec php sh

# Database container
docker-compose exec db mysql -u app -p

Development Workflow

Running Commands Inside Container

# Composer commands
docker-compose exec php composer install
docker-compose exec php composer require package/name

# NPM/Node commands
docker-compose exec php npm install
docker-compose exec php npm run dev
docker-compose exec php npm run build

# PHP CLI
docker-compose exec php php -v
docker-compose exec php php artisan migrate          # Laravel
docker-compose exec php bin/console doctrine:schema  # Symfony

# Database management
docker-compose exec db mysql -u app -p database

File Structure

franken/
├── docker-compose.yml    # Docker services configuration
├── Dockerfile           # Multi-stage PHP container build
├── .env                 # Environment configuration
├── php.ini             # Custom PHP settings
├── www/                # Web application root
│   └── index.php       # Entry point
└── README.md           # This file

PHP Configuration

Edit php.ini to customize PHP settings:

; Example configurations
display_errors = On
memory_limit = 512M
upload_max_filesize = 100M
post_max_size = 100M

Changes take effect after container restart:

docker-compose restart php

Docker Architecture

Multi-Stage Build

The Dockerfile uses multi-stage builds to optimize for different frameworks:

• base: Foundation with core PHP extensions
• node: Adds Node.js runtime
• laravel: Laravel-specific extensions (Redis, APCu)
• symfony: Symfony-specific extensions (APCu, Sodium)
• wordpress: WordPress-specific configuration
• opencart: OpenCart-specific configuration
• magento2: Magento 2-specific configuration

Services

PHP Service (FrankenPHP)

• Image: dunglas/frankenphp:php{PHP_VERSION}-alpine
• Includes:
  • PHP 8.0-8.5
  • Node.js v20.x
  • Caddy web server
  • Framework-specific extensions

Database Service (MariaDB)

• Image: mariadb:latest
• Volume: db_data (persistent)
• Port: 3306 (internal)

Network & Volumes

networks:
  app-network:           # Internal communication
    driver: bridge

volumes:
  caddy_data:           # Caddy cache and data
  caddy_config:         # Caddy configuration
  db_data:              # Database persistence

PHP Extensions

Core Extensions

• Database: pdo_mysql, mysqli
• String: mbstring, ctype, iconv
• Data: xml, dom, simplexml, fileinfo
• Security: openssl, tokenizer
• Utilities: curl, zip, intl, opcache

Framework-Specific Extensions

Laravel/Magento2:

• redis: Redis cache support

Symfony:

• apcu: APCu caching
• sodium: Modern cryptography

Troubleshooting

Port Already in Use

# Change PORT in .env and restart
PORT=8080 docker-compose up -d

Database Connection Issues

Verify credentials in .env:

docker-compose exec php php -r "
\$db = new mysqli('db', 'app', 'secret', 'database');
if (\$db->connect_error) exit('Connection failed: ' . \$db->connect_error);
echo 'Connected successfully!';
"

Permission Issues

# Fix permissions in www directory
chmod -R 755 www/

Rebuild Everything

docker-compose down -v
docker-compose up --build -d

Check Container Status

docker-compose ps
docker-compose logs -f

Useful Commands

# List running containers
docker-compose ps

# Restart a service
docker-compose restart php

# Rebuild images
docker-compose build --no-cache

# Execute command in container
docker-compose exec php <command>

# Copy files from container
docker cp <container>:/path/to/file ./local/path

# View resource usage
docker stats

Performance Optimization

For Production

1. Set MODE=prod in .env
2. Enable opcache in php.ini:

   opcache.enable=1
   opcache.memory_consumption=256
   

3. Configure Redis for caching:

   docker-compose exec php redis-cli
   

Database Optimization

1. Set appropriate MYSQL_ROOT_PASSWORD
2. Monitor with:

   docker-compose exec db mysql -u root -p -e "SHOW PROCESSLIST;"
   

Security Best Practices

• ✅ Change default database credentials in .env
• ✅ Use strong passwords for MYSQL_ROOT_PASSWORD and MYSQL_PASSWORD_DATABASE
• ✅ Set MODE=prod for production deployments
• ✅ Keep php.ini locked to read-only (default)
• ✅ Use environment variables for sensitive data
• ✅ Keep Docker images updated

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/improvement)
3. Make your changes
4. Test thoroughly
5. Commit with clear messages (git commit -am 'Add improvement')
6. Push to your fork (git push origin feature/improvement)
7. Open a Pull Request

License

[Specify your license here]

Support & Resources

• FrankenPHP Docs: https://frankenphp.dev/
• Caddy Docs: https://caddyserver.com/docs/
• Docker Docs: https://docs.docker.com/
• Compose Docs: https://docs.docker.com/compose/

Changelog

v1.1.0 (Current)

• Multi-stage Docker build for framework-specific optimization
• Node.js v20.x integration
• Support for 5+ PHP frameworks with dedicated configurations
• Improved documentation and examples
• Production mode with automatic HTTPS

v1.0.0

• Initial release with FrankenPHP and MariaDB
• Basic framework support
• Development and production modes

---

Last Updated: March 2026
Maintainer: Development Team