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.8-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.

---

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

---

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]:fonil/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
├── coverage                        # Code Coverage HTML report target folder
├── src                             # PHP application folder
├── caddy-root-ca-authority.crt     # Generated certificate file with Caddy Root CA Authority details
├── docker-compose.yml
├── Dockerfile
├── Makefile
└── README.md                       # This file

Volumes

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

Host path	Container path	Description
./src	/code	PHP application folder
./coverage	/coverage	Code Coverage HTML report target folder

Note

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

Important

Remember to restart the container service if you make any change in docker-compose.yml.

Available Commands

A Makefile is provided with following commands:

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

╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║                           .: AVAILABLE COMMANDS :.                           ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝

· build                          Docker: builds the service
· up                             Docker: starts the service
· restart                        Docker: restarts the service
· down                           Docker: stops the service
· logs                           Docker: exposes the service logs
· bash                           Docker: establish a bash session into main container
· get-caddy-certificate          Setup: gets the Caddy Local Authority certificate
· show-context                   Setup: show context
· install-clean                  Application: clean up the ./src folder
· install-skeleton               Application: installs PHP Skeleton
· install-laravel                Application: installs Laravel

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://website.localhost.

Any .localhost TLD resolves by default to 127.0.0.1 so no any additional action is required on your host.

Note

Review the build/Caddyfile and apply the changes based on your preferences.

Review the Makefile to ensure WEBSITE_URL constant has the desired domain URL.

Important

Remember to restart the container service if you make any change in build/Caddyfile 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.

Development 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

Production Environment

Build Docker Image

Linux Based Hosts

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

Windows Hosts

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

Access to Container

Linux Based Hosts

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

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.