FrankenPHP Docker Environment

A modern, high-performance Docker environment for PHP applications using FrankenPHP, featuring built-in HTTP/2, HTTP/3, and automatic HTTPS support with Node.js integration.

Features

• FrankenPHP Server: Modern PHP server with HTTP/2, HTTP/3, and automatic HTTPS
• MariaDB Database: Reliable database server with persistent data storage
• Node.js Integration: Full Node.js runtime for frontend tooling and build processes
• Framework Support: Optimized for OpenCart, Laravel, and Symfony
• Multiple Modes: Local development, proxy, and production configurations
• Rich PHP Extensions: Comprehensive set of PHP extensions including Redis, APCu, and ImageMagick
• Composer & NPM: PHP and JavaScript dependency management
• Volume Persistence: Persistent data for database and Caddy certificates
• Hot Reload: Automatic code reloading during development

Requirements

• Docker
• Docker Compose
• Git (optional, for cloning)

Quick Start

1. Clone or download the project

   git clone <repository-url>
   cd franken
   

2. Configure environment variables Edit the .env file with your preferred settings:

   # Example configuration
   PHP_VERSION=8.2
   FRAMEWORK=opencart  # or laravel, symfony
   MODE=proxy          # or local, prod
   PORT=80
   

3. Start the environment

   docker-compose up -d
   

4. Access your application

   • Local/Proxy mode: http://localhost:{PORT} (default: http://localhost:80)
   • Production: https://yourdomain.com (configure DNS and SSL certificates)

Configuration

Environment Variables (.env)

Variable	Description	Options/Default
PHP_VERSION	PHP version to use	8.0, 8.1, 8.2, 8.3, 8.4, 8.5 (default: 8.2)
FRAMEWORK	Target PHP framework	opencart, laravel, symfony (default: opencart)
MODE	Environment mode	local, proxy, prod (default: proxy)
PORT	External port for HTTP	Any available port (default: 80)
MYSQL_ROOT_PASSWORD	MariaDB root password	root
MYSQL_DATABASE	Database name	database
MYSQL_USER_DATABASE	Database user	app
MYSQL_PASSWORD_DATABASE	Database user password	secret
SERVER_NAME	Domain for production	Your domain (leave empty for local/proxy)

Modes Explained

• local: Development mode with internal TLS disabled
• proxy: Proxy mode for use behind a reverse proxy or load balancer
• prod: Production mode with HTTPS and HTTP/2/3 enabled

PHP Configuration

Custom PHP settings can be added to php.ini. The file is mounted as a read-only volume at /usr/local/etc/php/php.ini.

Framework Support

The environment is optimized for different PHP frameworks:

OpenCart (Default)

• Container name: opencart{PHP_VERSION} (e.g., opencart8.2)
• Web root: ./www → /app/public
• Optimized for e-commerce applications

Laravel

• Container name: laravel{PHP_VERSION}
• Web root: ./www → /app (uncomment in docker-compose.yml)
• Includes storage permission fixes

Symfony

• Container name: symfony{PHP_VERSION}
• Web root: ./www → /app (uncomment in docker-compose.yml)
• Includes storage permission fixes

Production Mode

For production deployment:

1. Set MODE=prod in .env
2. Configure SERVER_NAME with your domain
3. Uncomment HTTPS ports in docker-compose.yml:

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

4. Set up DNS to point to your server
5. FrankenPHP will automatically obtain SSL certificates

Docker Services

PHP Service (FrankenPHP)

• Base Image: dunglas/frankenphp:php${PHP_VERSION}-alpine
• Container Name: {FRAMEWORK}{PHP_VERSION} (e.g., opencart8.2)
• Features:
  • HTTP/2 and HTTP/3 support
  • Automatic HTTPS with Let's Encrypt
  • Built-in Caddy web server
  • PHP-FPM compatibility
  • Node.js runtime included

Database Service (MariaDB)

• Image: mariadb:latest
• Features:
  • Persistent data storage
  • User and database creation
  • Optimized for web applications

PHP Extensions Included

The environment includes a comprehensive set of PHP extensions:

• Database: pdo_mysql, mysqli
• Image Processing: gd, imagick, exif
• Internationalization: intl, mbstring, iconv
• Data Formats: xml, dom, simplexml, zip, json
• Security: openssl, sodium
• Performance: opcache, apcu, redis
• Utilities: curl, fileinfo, ctype, tokenizer, bcmath, soap, sqlite3, xsl

Development Workflow

1. Code Changes: Edit files in the www/ directory
2. Database Access: Connect to localhost:3306 with configured credentials
3. Node.js Usage: Run npm/yarn commands in the container:

   docker-compose exec php npm install
   docker-compose exec php npm run build
   

4. Logs: View container logs with docker-compose logs -f
5. Rebuild: After Dockerfile changes: docker-compose up --build

File Structure

franken/
├── docker-compose.yml    # Docker services configuration
├── Dockerfile           # PHP container build instructions
├── .env                 # Environment variables
├── php.ini             # Custom PHP configuration
├── www/                # Web application files
│   └── index.php       # Sample PHP file
└── README.md           # This file

Troubleshooting

Common Issues

1. Port conflicts: Change the PORT variable in .env
2. Permission issues: Ensure proper file permissions in www/ directory
3. Database connection: Verify credentials in .env match application config
4. SSL issues: Check domain configuration and DNS propagation
5. Framework switching: Update FRAMEWORK in .env and rebuild containers

Useful Commands

# View logs
docker-compose logs -f

# Access container shell
docker-compose exec php sh

# Run Node.js commands
docker-compose exec php npm install
docker-compose exec php npm run dev

# Restart services
docker-compose restart

# Rebuild and restart
docker-compose up --build -d

# Stop and remove containers
docker-compose down

# Clean up volumes (WARNING: deletes data)
docker-compose down -v

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

[Specify your license here]

Support

For issues and questions:

• Check the troubleshooting section
• Review FrankenPHP documentation: https://frankenphp.dev/
• Open an issue in the repository

Changelog

[Latest Version]

• Added Node.js integration for frontend tooling
• Enhanced PHP extensions (Redis, APCu, ImageMagick, etc.)
• Framework-specific container naming
• Added proxy mode for reverse proxy setups
• Improved volume management and networking
• Updated configuration options and documentation
• Image: dunglas/frankenphp:php${PHP_VERSION}-alpine
• Features:
  • HTTP/2 and HTTP/3 support
  • Automatic HTTPS with Let's Encrypt
  • Built-in Caddy web server
  • PHP-FPM compatibility

Database Service (MariaDB)

• Image: mariadb:latest
• Features:
  • Persistent data storage
  • User and database creation
  • Optimized for web applications

Development Workflow

1. Code Changes: Edit files in the www/ directory
2. Database Access: Connect to localhost:3306 with configured credentials
3. Logs: View container logs with docker-compose logs -f
4. Rebuild: After Dockerfile changes: docker-compose up --build

File Structure

franken/
├── docker-compose.yml    # Docker services configuration
├── Dockerfile           # PHP container build instructions
├── .env                 # Environment variables
├── php.ini             # Custom PHP configuration
├── www/                # Web application files
│   └── index.php       # Sample PHP file
└── README.md           # This file

Troubleshooting

Common Issues

1. Port conflicts: Change port mappings in docker-compose.yml
2. Permission issues: Ensure proper file permissions in www/ directory
3. Database connection: Verify credentials in .env match application config
4. SSL issues: Check domain configuration and DNS propagation

Useful Commands

# View logs
docker-compose logs -f

# Restart services
docker-compose restart

# Rebuild and restart
docker-compose up --build -d

# Stop and remove containers
docker-compose down

# Clean up volumes (WARNING: deletes data)
docker-compose down -v

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

[Specify your license here]

Support

For issues and questions:

• Check the troubleshooting section
• Review FrankenPHP documentation: https://frankenphp.dev/
• Open an issue in the repository

Changelog

[Version]

• Initial release with FrankenPHP and MariaDB support
• Support for multiple PHP frameworks
• Development and production mode configurations