Compatible with popular PHP Frameworks such as Laravel 5+ & Symfony 4+ and their variants.
Typically deployed on Kubernetes.
Production Grade Image for PHP 7+ Applications running Nginx + PHP FPM based on PHP & Nginx Official Images, compatible with popular PHP Frameworks such as Laravel 5+ & Symfony 4+ and their variants.
- This is a pre-configured template image for your PHP Application, and you shall extend and edit it according to your app requirements. (instructions below)
- The Image utilizes multistage builds to create multiple targets optimized for production and development usecases.
- Image designed to be run in Kubernetes.
- Supports PHP applications that uses a single-entrypoint framework in
public/index.php
, such as Laravel, Symfony, and all their variants.
- Designed to run in orchestrated environments like Kubernetes.
- Uses Alpine based images and multistage builds for minimal images. (~130 MB)
- Multi-Container setup with
Nginx
&PHP-FPM
communicating via TCP. - Productions Image that are immutable and fully contained.
- Runs as non-root in both application containers.
- Configured for graceful shutdowns/restarts, zero downtime deployments, auto-healing, and auto-scaling.
- Easily extend the image with extra configuration, and scripts; such as post-build & pre-run scripts.
- Minimal startup time, container almost start serving requests almost instantly.
- Image tries to fail at build time as much as possible by running all sort of checks.
- Ability to run Commands, Consumers and Crons using same image. (No supervisor or crontab)
- Development Image supports mounting code and hot-reloading and XDebug.
- Copy this repository
Dockerfile
,docker
Directory,Makefile
,docker-compose.yml
,docker-compose.prod.yml
and.dockerignore
to your application root directory and configure it to your needs.
You'll need to iterate over your application's dependency system packages, and required PHP Extensions; and add them to their respective locations in the image.
- Add System Dependencies and PHP Extensions your application depends on to the Image.
- Port in any configuration changes you made for PHP.ini to the image, otherwise use the sane defaults.
make build && make up
for development setup,make deploy
to run the production variant.
These steps explained in details below.
Your application will be split into two components.
- The Webserver -> Server Static Content and proxy dynamic requests to PHP-FPM over TCP, webserver also applies rate limiting, security headers... and whatever it is configured for.
- The PHP Process -> PHP FPM process that will run you PHP Code.
Other type of deployments such as a cron-job, or a supervised consumer can be achieved by overriding the default image CMD.
- Docker 20.10.0 or higher
- Docker-Compose 1.27 or higher (optional)
- PHP >= 7 Application
- Download This Repository
- Copy
Dockerfile
,docker
Directory,Makefile
,docker-compose.yml
,docker-compose.prod.yml
and.dockerignore
Into your Application Repository.
OR
![create repository from template](https://user-images.githubusercontent.com/16992394/133710871-178f9cb6-922e-41e1-9c69-dff8f9773b97.png)
- Modify
Dockerfile
to your app needs, and add your app needed OS Packages, and PHP Extensions.- Dockerfile Header has Build Time Arguments, customize it, most notably the
RUNTIME_DEPS
argument. - Below in the
base
image, add the PHP Extensions your application depends on.
- Dockerfile Header has Build Time Arguments, customize it, most notably the
- Run
make up
for development ormake deploy
for production.- For Dev:
make up
is just an alias fordocker-compose up -d
- For Dev: Make sure to delete previous
vendor
directory if you had it before. - Docker-Compose will start App container first, and only start Web server when it's ready, on initial install, it might take some time.
- For Dev:
- Go to https://localhost
Makefile is just a wrapper over docker-compose commands.
-
The image comes with a handy Makefile to build the image using Docker-Compose files, it's handy when manually building the image for development or in a not-orchestrated docker host. However, in an environment where CI/CD pipelines will build the image, they will need to supply some build-time arguments for the image. (tho defaults exist.)
ARG Description Default PHP_VERSION
PHP Version used in the Image 7.4
PHP_ALPINE_VERSION
Alpine Version for the PHP Image 3.15
NGINX_VERSION
Nginx Version 1.21
COMPOSER_VERSION
Composer Version used in Image 2.0
COMPOSER_AUTH
A Json Object with Bitbucket or Github token to clone private Repos with composer.
Reference{}
XDEBUG_VERSION
Xdebug Version to use in Development Image 3.1.3
Target Env Desc Size Based On app Production The PHP Application with immutable code/dependencies. By default starts PHP-FPM
process listening on9000
. Command can be extended to run any PHP Consumer/Job, entrypoint will still start the pre-run setup and then run the supplied command.~135mb PHP Official Image (Alpine) web Production The webserver, an Nginx container that is configured to server static content and forward dynamic requests to the PHP-FPM container running in the app
image variant~21mb Nginx Official Image (Alpine) app-dev Development Development PHP Application variant with dependencies inside. Image expects the code to be mounted on /app
to support hot-reloading. You need to mount dummy/app/vendor
volume too to avoid code volume to overwrite dependencies already inside the image.~150mb PHP Official Image (Alpine) web-dev Development Development Webserver with the exact configuration as the production configuration. Expects public directory to be mounted at /app/public
~21mb Nginx Official Image (Alpine)
-
The image is to be used as a base for your PHP application image, you should modify its Dockerfile to your needs.
- Install System Packages in the following section in the Dockerfile.
- Add OS Packages needed in
RUNTIME_DEPS
in Dockerfile.
- Add OS Packages needed in
- Install PHP Extensions In the following section in the Dockerfile.
# ---------------------------------------- Install / Enable PHP Extensions --------------------------------------------- RUN docker-php-ext-install \ opcache \ intl \ pdo_mysql \ # Pecl Extentions RUN pecl install apcu-5.1.20 && docker-php-ext-enable apcu # EX: RUN pecl install memcached && docker-php-ext-enable memcached
- Install System Packages in the following section in the Dockerfile.
At build time, Image will run
composer check-platform-reqs
to check that PHP and extensions versions match the platform requirements of the installed packages.
- PHP
base
Configuration that are common in all environments indocker/php/base-php.ini
π - PHP
prod
Only Configurationdocker/php/php-prod.ini
π - PHP
dev
Only Configurationdocker/php/php-dev.ini
π
- PHP FPM Configuration
docker/fpm/*.conf
π
- Nginx Configuration
docker/nginx/*.conf && docker/nginx/conf.d/*
π
In docker/
directory there is post-build-*
and pre-run-*
scripts that are used to extend the image and add extra behavior.
-
post-build
command runs at the end of Image build.Run as the last step during the image build. Are Often framework specific commands that generate optimized builds, generate assets, etc.
-
pre-run
command runs in runtime before running the container main commandRuns before the container's CMD, but after the composer's post-install and post-autload-dump. Used for commands that needs to run at runtime before the application is started. Often are scripts that depends on other services or runtime parameters.
-
*-base
scripts run on bothproduction
anddevelopment
images.
- Your application should log app logs to stdout.. Read about 12factor/logs
- By default,
php-fpm
access logs are disabled as they're mirrored onnginx
, this is so thatphp-fpm
image will contain only application logs written by PHP. - In production, Image contains source-code, however, you must sync both
php-fpm
andnginx
images so that they contain the same build.
-
Why two containers instead of one ?
- In containerized environment, you need to only run one process inside the container. This allows us to better instrument our application for many reasons like separation of health status, metrics, logs, etc.
-
Image Build Fails as it try to connect to DB.
- A typical scenario in most frameworks that comes with
Doctrine
ORM is that if Doctrine not configured with a DB Version, will try to access the DB at php's script initialization (even at the post-install cmd's), and it will fail when it cannot connect to DB. Make sure you configure doctrine to avoid this extra DB Check connection.
- A typical scenario in most frameworks that comes with
MIT License Copyright (c) 2022 Sherif Abdel-Naby
PR(s) are Open and welcomed.