Dockerized PHP

A dockerized environment based on Caddy + PHP-FPM running on a Linux Alpine container.

[TOC]

---

Summary

This repository contains a dockerized environment for building PHP applications based on php:8.3.12-fpm-alpine with Caddy support.

Highlights

• Unified environment to build CLI, web applications and/or micro-services based on PHP8.
• Allows you to create an optimized development environment Docker image
• Allows you to create an optimized production-ready Docker image
• Self-signed local domains thanks to Caddy.

---

Requirements

To use this repository you need:

• Docker - An open source containerization platform.
• Git - The free and open source distributed version control system.
• Make - A command to automate the build/manage process.
• jq - A lightweight and flexible command-line JSON processor.

---

Built with

Type	Component	Description
Infrastructure	Docker	Containerization platform
Service	Caddy Server	Open source web server with automatic HTTPS written in Go
Service	PHP-FPM	PHP with FastCGI Process Manager
Miscelaneous	Bash	Allows to create an interactive shell within containerized service
Miscelaneous	Make	Allows to execute commands defined on a Makefile
Miscelaneous	jq	Allows to beautify the Docker inspections in JSON format

---

Getting Started

Just clone the repository into your preferred path:

$ mkdir -p ~/path/to/my-new-project && cd ~/path/to/my-new-project
$ git clone [email protected]:alcidesrc/dockerized-php.git .

Conventions

Dockerfile

Dockerfile is based on multi-stage builds in order to simplify the process to generate the development container image and the optimized production-ready container image.

Default Stages

Name	Description
base-image	Used to define the base Docker image
common	Used to define generic variables: WORKDIR, HEALTCHECK, etc.
extensions-builder-common	Used to build generic PHP extensions
extensions-builder-dev	Used to build development PHP extensions
build-development	Used to build the development environment
optimize-php-dependencies	Used to optimize the PHP dependencies in production by removing the development ones
build-production	Used to build the production environment

Default Stages Hierarchy

---
title: Dockerfile Stages Hierarchy
---
stateDiagram-v2
    [*] --> BaseImage
    BaseImage --> Common
    Common --> ExtensionsBuilderCommon
    
    ExtensionsBuilderCommon --> ExtensionsBuilderDev
    ExtensionsBuilderDev --> BuildDevelopment
    
    ExtensionsBuilderCommon --> OptimizePhpDependencies
    OptimizePhpDependencies --> BuildProduction

Loading

Health check

A custom health check script is provided to check the container service by performing a PHP-FPM ping/pong check.

You can find this shell script at build/healthcheck.sh.

Note

Review the Dockerfile file and adjust the HEALTHCHECK directive options accordingly.

Important

Remember to rebuild the Docker image if you make any change on this file.

Non-Privileged User

Current container service uses a non-privileged user to execute PHP-FPM, with same User/Group ID than the host user.

This mechanism allows to PHP-FPM create/update shared resources within the host with the same credentials than current host user, avoiding possible file-permissions issues.

To create this user in the container service, current host user details are collected in the Makefile and passed to Docker build command as arguments:

Argument	Default value	Required value	Description
HOST_USER_NAME	host-user-name	$ id --user --name	Current host user name
HOST_GROUP_NAME	host-group-name	$ id --group --name	Current host group name
HOST_USER_ID	1001	$ id --user	Current host user ID
HOST_GROUP_ID	1001	$ id --group	Current host user group ID

Note

Review the Makefile and Dockerfile files and adjust the arguments to your convenience.

Important

Remember to rebuild the Docker image if you make any change on Dockerfile file.

Logging

The container service logs to STDOUT by default.

Project Structure

├── build                           	# Docker-related configuration files
│   ├── Caddyfile                   	# Caddy's configuration file
│   ├── healthcheck.sh              	# Shell script for Docker's HEALTHCHECK  directive
│   ├── www.conf                    	# PHP-FPM configuration file
│   └── xdebug.ini                  	# xDebug configuration file
├── README                        		# README.md required assets
├── src                             	# PHP application folder
├── caddy-root-ca-authority.crt     	# Generated certificate file with Caddy Root CA Authority details
├── docker-compose.override.dev.yml     # Docker Compose file for development environment
├── docker-compose.override.prod.yml	# Docker Compose file for production environment
├── docker-compose.yml              	# Docker Compose base file
├── Dockerfile
├── LICENSE
├── Makefile
└── README.md

Volumes

There are some volumes created between the host and the container service:

Host path	Container path	Description
./src	/var/www/html	PHP application folder

Note

Review the docker-compose.xxx.yml files and adjust the volumes to your convenience.

Important

Remember to rebuild the Docker image if you make any change on Dockerfile file.

Available Commands

A Makefile is provided with following commands:

~/path/to/my-new-project$ make

╔════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ 	                                                                                                     ║
║ 	                                 .: AVAILABLE COMMANDS :. 	                                         ║
║ 	                                                                                                     ║
╚════════════════════════════════════════════════════════════════════════════════════════════════════════╝
· DOMAIN(s) .... https://localhost
· SERVICE(s) ... caddy app1
· USER ......... (1000) alcidesramos
· GROUP ........ (1000) alcidesramos

· build                               Docker: builds the service <env=[dev|prod]>
· up                                  Docker: starts the service <env=[dev|prod]>
· restart                             Docker: restarts the service <env=[dev|prod]>
· down                                Docker: stops the service <env=[dev|prod]>
· logs                                Docker: exposes the service logs <env=[dev|prod]> <service=[app1|caddy]>
· shell                               Docker: establish a shell session into main container
· inspect                             Docker: inspect the health for specific service <service=[app1|caddy]>
· install-caddy-certificate           Setup: extracts the Caddy Local Authority certificate
· install-skeleton                    Application: installs PHP Skeleton
· install-laravel                     Application: installs Laravel
· install-symfony                     Application: installs Symfony
· uninstall                           Application: removes the PHP application

Web Server

This project uses Caddy as main web server which provides HTTPS by default.

Warning

Caddy is optional and you can replace/remove it based on your preferences.

Default Domain

The default website domain is https://localhost

Tip

You can customize the domain name in docker-compose.override.xxx.yml

Review as well the Makefile to ensure WEBSITE_URL constant has the desired domain name for development environment.

Important

Remember to restart the container service(s) if you make any change on any Docker file.

Certificate Authority (CA) & SSL Certificate

You can generate/register the Caddy Authority Certificate in order to get SSL support .

Note

Just execute make install-caddy-certificate and follow the provided guidelines to generate the Caddy Authority Certificate and install it on your host.

Important

Remember to reinstall the certificate if you rebuild the container service.

PHP Application

PHP application must be placed into src folder.

Tip

There are some Makefile commands that allows you to install a PHP Skeleton as boilerplate or Laravel when creating PHP applications from scratch.

Testing

Mocking Date/Time functions

Testing with date and/or time variations sometimes can be a nightmare. To assist on this topic the UOPZ extension has been installed and enabled by default.

Tip

You can use slope-it/clock-mock as a development dependency when mocking date/time functions.

Max. simultaneous connectionsMax. simultaneous connectionsDevelopment Environment

Build Docker Image

Linux Based Hosts

$ make build

Windows Hosts

$ docker compose build

Access to Container

Linux Based Hosts

$ make bash

Windows Hosts

$ docker run -it --rm app:development bash

Setup PHPStorm

Help > Change Memory Settings

To allow PHPStorm index huge projects consider to increase the default assigned memory amount from 2048 MiB up to 8192 MiB.

Settings > PHP > Debug

Ensure the Max. simultaneous connections is set to 1 to avoid trace collisions when debugging.

Settings > PHP > Servers

Ensure the ~/path/to/my-new-project/src folder is mapped to /var/www/html

Settings > PHP

Important

When selecting Docker Compose configuration files, ensure to include:

1. The docker-compose.yml file, which contains the default service(s) specification
2. The docker-compose-dev.yml file, which contains some override values or customization from default specification.

The order on here is important!

Production Environment

Build Docker Image

Linux Based Hosts

$ make env=prod

Windows Hosts

$ docker buildx build --target=build-production --tag="app:production" .

Access to Container

Linux Based Hosts

$ make shell env=prod

Windows Hosts

$ docker run -it --rm app:production sh

---

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities:

PLEASE DON'T DISCLOSE SECURITY-RELATED ISSUES PUBLICLY

Supported Versions

Only the latest major version receives security fixes.

Reporting a Vulnerability

If you discover a security vulnerability within this project, please open an issue here. All security vulnerabilities will be promptly addressed.

---

License

The MIT License (MIT). Please see LICENSE file for more information.