<p align="center"> <img width="320px" src="https://user-images.githubusercontent.com/16992394/132966279-6f4bd8a6-9d50-4940-96f0-7edb73688ab9.png"> </p> <h2 align="center">KubePHP - Production Grade, Rootless, Optimized, PHP Container Image for Cloud Native PHP Apps 🐳 </h2> <p align="center">Compatible with popular PHP Frameworks such as <a href="https://laravel.com/">Laravel</a> &amp; <a href="https://symfony.com/">Symfony</a> and their variants. </br> Typically deployed on Kubernetes. </p> <p align="center"> <a> <img src="https://img.shields.io/github/v/tag/sherifabdlnaby/kubephp?label=release&amp;sort=semver"> </a> <a href="https://github.com/sherifabdlnaby/kubephp/actions/workflows/build-test-scan.yml"> <img src="https://img.shields.io/github/actions/workflow/status/sherifabdlnaby/kubephp/build-test-scan.yml?label=Build&amp;branch=main" alt="Build Status"> </a> <a href="https://github.com/sherifabdlnaby/kubephp/actions/workflows/build-test-scan.yml"> <img src="https://img.shields.io/github/actions/workflow/status/sherifabdlnaby/kubephp/build-test-scan.yml?label=Tests&amp;branch=main" alt="Test Status"> </a> <a> <img src="https://img.shields.io/badge/PHP-8.4-%23777BB4?logo=php" alt="PHP 8.4"> </a> <a> <img src="https://img.shields.io/badge/Platform-amd64%20%7C%20arm64-blue" alt="Multi-arch"> </a> <a href="https://github.com/sherifabdlnaby/kubephp/network"> <img src="https://img.shields.io/github/forks/sherifabdlnaby/kubephp.svg" alt="GitHub forks"> </a> <a href="https://github.com/sherifabdlnaby/kubephp/issues"> <img src="https://img.shields.io/github/issues/sherifabdlnaby/kubephp.svg" alt="GitHub issues"> </a> <a href="https://raw.githubusercontent.com/sherifabdlnaby/kubephp/blob/master/LICENSE"> <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="GitHub license"> </a> <a> <img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat" alt="contributions welcome"> </a> </p>

Introduction

Production Grade Image for PHP 8.4+ Applications running Nginx + PHP FPM based on PHP & Nginx Official Images, compatible with popular PHP Frameworks such as Laravel & Symfony 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. See Requirements first, then follow How to use with my project and How to configure image to run my project for setup instructions.
• The Image utilizes multistage builds to create multiple targets optimized for production OR development use cases. Hyper-optimized for caching and build time. See Image Targets and Build Arguments for details.
• Demo applications are available for both frameworks to give you a quick start:
  • use make demo/symfony/setup for Symfony Demo (latest Symfony 7.x)
  • use make demo/laravel/setup for Laravel (latest Laravel 11.x).

Features 📜

• Designed to run in orchestrated environments like Kubernetes. See How is it deployed? for architecture details.
• Multi-architecture support - native images for AMD64 and ARM64.
• Uses Alpine based images and multistage builds for minimal images. (~135 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.
• PHP 8.4 optimizations including JIT compilation and OPcache file caching.
• 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 out of the box.
• Cache-friendly mechanism to update OS packages and auto-patch security vulnerabilities (see cache mechanism).

How to use with my project ?

This is a template, it's expected from you to tailor it to your needs. And then generate a build pipeline to build the image and push it to your registry.

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

How to configure image to run my project ?

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.

1. Add System Dependencies and PHP Extensions your application depends on to the Image.
2. Port in any configuration changes you made for PHP.ini to the image, otherwise use the sane defaults.
3. make build && make up for development setup, make deploy to run the production variant.

These steps explained in details below.

How is it deployed ?

<img src="https://user-images.githubusercontent.com/16992394/116017065-dd8b2900-a63e-11eb-917e-6b04a4e6e89b.png">

Your application will be split into two components.

1. 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.
2. 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.

---

Requirements

• Docker 20.10.0 or higher
• Docker Compose V2 (included with Docker Desktop)
• PHP >= 8.2 Application

Setup

1. Add Template to your repo.

1. Download This Repository
2. Copy Dockerfile, docker Directory, Makefile, docker-compose.yml, docker-compose.prod.yml and .dockerignore Into your Application Repository.

OR

<a href="https://github.com/sherifabdlnaby/kubephp/generate"> <img src="https://user-images.githubusercontent.com/16992394/133710871-178f9cb6-922e-41e1-9c69-dff8f9773b97.png" alt="create repository from template"></a>

2. Start

1. Modify Dockerfile to your app needs, and add your app needed OS Packages, and PHP Extensions.
   1. Dockerfile Header has Build Time Arguments, customize it, most notably the RUNTIME_DEPS argument.
   2. Below in the base image, add the PHP Extensions your application depends on.
2. Run make up for development or make deploy for production.
   1. For Dev: make up is just an alias for docker compose up -d
   2. For Dev: Make sure to delete previous vendor directory if you had it before.
   3. Docker-Compose will start App container first, and only start Web server when it's ready, on initial install, it might take some time.
3. Go to http://localhost:8080

Makefile is just a wrapper over docker compose commands.

Building, Configuring and Extending Image

Image Targets and Build Arguments

• 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.)

  Build Time Arguments

  | ARG | Description | Default | |----------------------|-----------------|-------------| | PHP_VERSION | PHP Version used in the Image | 8.4 | | PHP_ALPINE_VERSION | Alpine Version for the PHP Image | 3.21 | | NGINX_VERSION | Nginx Version | 1.28 | | COMPOSER_VERSION | Composer Version used in Image | 2 | | COMPOSER_AUTH | A Json Object with Bitbucket or Github token to clone private Repos with composer.</br>Reference | {} | | XDEBUG_VERSION | Xdebug Version to use in Development Image | 3.5.0 | | OS_PACKAGE_UPGRADE_TRIGGER | Cache buster for OS packages. Changing this value triggers a fresh installation and update of all OS packages. See OS Package Cache Busting for details. | 1 |

  Image Targets

  | Target | Env | Desc | Size | Based On | |------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|-------------------------------| | app | Production | The PHP Application with immutable code/dependencies. By default starts PHP-FPM process listening on 9000. Command can be extended to run any PHP Consumer/Job, entrypoint will still start the pre-run setup and then run the supplied command. | ~135m