From 3475739bc7b5c0d316f34932f41edce60d5077d5 Mon Sep 17 00:00:00 2001 From: lotyp Date: Mon, 9 Sep 2024 15:02:19 +0300 Subject: [PATCH] docs: update README.md --- README.md | 326 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 237 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index 510dc5f..73b144a 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,49 @@ # Docker Image: PHP Base -Repository contains dist folder with generated basic PHP images and source code, written on Ansible, to generate them. Is used together with other WOD images, to create local development environment for our projects. +The `docker-php-base` project is a **system** for creating and maintaining **PHP Docker images**. -Enabled extensions by default: +It uses **Ansible** to generate **Dockerfiles** for multiple PHP versions (7.4, 8.0, **8.1, 8.2, 8.3**) and types (**CLI, FPM, Supervisord**) on **Alpine Linux**. + +The project automates the build process using **GitHub Actions**, creating multi-architecture images (**AMD64** and **ARM64**) that are tested with [goss](https://github.com/goss-org/goss). + +Images come pre-configured with a wide array of PHP extensions and are designed to serve as a base for PHP applications in both **development** and **production** environments. + +
+ +If you **like/use** this package, please consider โญ๏ธ **starring** it. Thanks! + +
+ +## ๐Ÿš€ Features + +- **Multiple PHP Versions:** Supports PHP 7.4, 8.0, 8.1, 8.2, and 8.3. +- **Various PHP Types:** Includes CLI, FPM, and Supervisord configurations. +- **Alpine-based:** Lightweight images built on Alpine Linux. +- **Pre-configured Extensions:** Comes with a wide range of pre-installed PHP extensions. +- **Customizable Settings:** Easily adjustable PHP and OPcache settings. +- **Multi-architecture Support:** Built for both AMD64 and ARM64 architectures. +- **Automated Builds:** Utilizes GitHub Actions for continuous integration and delivery. +- **Comprehensive Testing:** Implements dgoss for thorough Docker image testing. +- **Ansible-based Generation:** Leverages Ansible for flexible and maintainable Dockerfile generation. +- **Security Focused:** Includes Docker Scout scans for vulnerability checks. + +
+ +## ๐Ÿ›  Technology Stack + +- **Ansible:** For generating Dockerfiles and configurations. +- **Docker:** Base technology for containerization. +- **GitHub Actions:** CI/CD pipeline for automated building, testing, and publishing. +- **dgoss:** For Docker image testing. +- **Alpine Linux:** Base OS for the Docker images. +- **PHP:** Core language with multiple versions (7.4, 8.0, 8.1, 8.2, 8.3). + +
+ +## ๐Ÿ“ฆ Pre-installed PHP Extensions + +The images come with a variety of pre-installed PHP extensions: | Extension | Description | Type | |--------------------------------------------------------------|----------------------------------------------------------------------------------|--------| @@ -31,7 +71,7 @@ Enabled extensions by default: | [pcntl](https://www.php.net/manual/en/book.pcntl.php) | Process control | native | | [sockets](https://www.php.net/manual/en/book.sockets.php) | Socket communication functions | native | | [pdo_pgsql](https://www.php.net/manual/en/ref.pdo-pgsql.php) | PostgreSQL functions | native | -| [pdo_mysql](https://www.php.net/manual/en/ref.pdo-mysql.php) | Mysql functions | native | +| [pdo_mysql](https://www.php.net/manual/en/ref.pdo-mysql.php) | MySQL functions | native | | [opcache](https://www.php.net/manual/en/book.opcache.php) | Improves PHP performance by storing precompiled script bytecode in shared memory | native | | [zip](https://www.php.net/manual/en/book.zip.php) | Read/write functions for ZIP archives | native | | [bcmath](https://www.php.net/manual/en/book.bc.php) | For arbitrary precision mathematics | native | @@ -47,15 +87,135 @@ Enabled extensions by default:
-If you **like/use** this repository, please consider **starring** it. Thanks! +## ๐Ÿš€ Usage + +The PHP base images are available on both Docker Hub and GitHub Container Registry (ghcr.io). You can pull the images using either of the following methods: + +### โ†’ Docker Hub + +```bash +docker pull wayofdev/php-base:8.3-fpm-alpine-latest +``` + +### โ†’ GitHub Container Registry + +```bash +docker pull ghcr.io/wayofdev/docker-php-base:8.3-fpm-alpine-latest +``` + +Replace `8.3-fpm-alpine-latest` with your desired PHP version, type, and tag. + +### โ†’ Available Image Variants + +The images are available in various combinations of PHP versions, types, and architectures: + +- **PHP Versions:** 8.1, 8.2, 8.3 +- **Types:** cli, fpm, supervisord +- **Architectures:** amd64, arm64 + +#### Examples + +```bash +# PHP 8.1 CLI +docker pull wayofdev/php-base:8.1-cli-alpine-latest + +# PHP 8.2 FPM +docker pull wayofdev/php-base:8.2-fpm-alpine-latest + +# PHP 8.3 with Supervisord +docker pull wayofdev/php-base:8.3-supervisord-alpine-latest +``` + +For a complete list of available tags, please refer to the [Docker Hub Tags](https://hub.docker.com/r/wayofdev/php-base/tags) or [GitHub Container Registry Packages](https://github.com/wayofdev/docker-php-base/pkgs/container/docker-php-base) page. + +### โ†’ Using in Dockerfile + +To use these images as a base for your own Dockerfile: + +```dockerfile +# From Docker Hub +FROM wayofdev/php-base:8.3-fpm-alpine-latest + +# Or from GitHub Container Registry +# FROM ghcr.io/wayofdev/docker-php-base:8.3-fpm-alpine-latest + +# Your additional Dockerfile instructions here +# ... +``` + +
+ +## ๐Ÿ”จ Development + +This project uses a set of tools for development and testing. The `Makefile` provides various commands to streamline the development process. + +### โ†’ Requirements + +- Docker +- Make +- Ansible +- goss and dgoss for testing + +### โ†’ Setting Up the Development Environment + +Clone the repository: + +```bash +git clone git@github.com:wayofdev/docker-php-base.git && \ +cd docker-php-base +``` + +### โ†’ Generating Dockerfiles + +Ansible is used to generate Dockerfiles and configurations. To generate distributable Dockerfiles from Jinja template source code: + +```bash +make generate +``` + +### โ†’ Building Images + +- Build the default image: + + ```bash + make build + ``` + + This command builds the image specified by the `IMAGE_TEMPLATE` variable in the Makefile. By default, it's set to `8.3-fpm-alpine`. + +- Build a specific image: + + ```bash + make build IMAGE_TEMPLATE="8.3-fpm-alpine" + ``` + + Replace `8.3-fpm-alpine` with your desired PHP version, type, and OS. + +- Build all images: + + ```bash + make build IMAGE_TEMPLATE="8.1-cli-alpine" + make build IMAGE_TEMPLATE="8.1-fpm-alpine" + make build IMAGE_TEMPLATE="8.1-supervisord-alpine" + make build IMAGE_TEMPLATE="8.2-cli-alpine" + make build IMAGE_TEMPLATE="8.2-fpm-alpine" + make build IMAGE_TEMPLATE="8.2-supervisord-alpine" + make build IMAGE_TEMPLATE="8.3-cli-alpine" + make build IMAGE_TEMPLATE="8.3-fpm-alpine" + make build IMAGE_TEMPLATE="8.3-supervisord-alpine" + ``` + + These commands will build all supported image variants.
## ๐Ÿ”ง Configuration -Ansible is used to generate distribution files, to add or remove PHP extensions, or configure project, see [group_vars/base.yml](https://github.com/wayofdev/docker-php-base/blob/master/src/group_vars/base.yml) +Ansible is used to generate distribution files. To add or remove PHP extensions, or configure the project, you can modify the [src/group_vars/base.yml](https://github.com/wayofdev/docker-php-base/blob/master/src/group_vars/base.yml) file. -**Default .ini settings for PHP:** +### โ†’ Default .ini settings for PHP + +You can adjust the following PHP and OPcache settings in the `group_vars/base.yml` file: ```yaml settings_opcache_ini: @@ -68,7 +228,9 @@ settings_php_ini: php_memory_limit: "256M" ``` -**Default extension configuration:** +### โ†’ PHP Extensions + +You can enable or disable PHP extensions by modifying the following sections in the `group_vars/base.yml` file: ```yaml ext_native_enabled: @@ -89,135 +251,121 @@ ext_pecl_enabled: - decimal - amqp - yaml + - grpc + - protobuf ``` -
+To add a new extension, simply add it to the appropriate list. To remove an extension, delete it from the list. -To generate dist files use ansible command: +After making changes to the `group_vars/base.yml` file, you need to regenerate the Dockerfiles: ```bash make generate ``` -
- -## โš™๏ธ Development - -To install dependencies and start development you can check contents of our `Makefile` - -### โ†’ Requirements - -For testing purposes we use **goss** and **dgoss**, follow installation instructions on [their official README](https://github.com/aelsabbahy/goss/blob/master/extras/dgoss/README.md) +This command will use Ansible to process the updated configuration and generate new Dockerfiles with your custom settings.
-### โ†’ Building locally +## ๐Ÿงช Testing -Generating distributable Dockerfiles from yaml source code: +This project uses a testing approach to ensure the quality and functionality of the Docker images. The primary testing tool is [dgoss](https://github.com/aelsabbahy/goss/tree/master/extras/dgoss), which allows for testing Docker containers. -```bash -make generate -``` +### โ†’ Running Tests -
+You can run tests using the following commands: -Building default image: +- Test the default image: -```bash -git clone git@github.com:wayofdev/docker-php-base.git -make build -``` + ```bash + make test + ``` -To **build** image, **test** it and then **clean** temporary files run: + This command tests the image specified by the `IMAGE_TEMPLATE` variable in the Makefile (default is `8.3-fpm-alpine`). -```bash -make -``` +- Test a specific image: -Building all images: + ```bash + make test IMAGE_TEMPLATE="8.3-fpm-alpine" + ``` -```bash -make build IMAGE_TEMPLATE="8.1-cli-alpine" -make build IMAGE_TEMPLATE="8.1-fpm-alpine" -make build IMAGE_TEMPLATE="8.1-supervisord-alpine" -make build IMAGE_TEMPLATE="8.2-cli-alpine" -make build IMAGE_TEMPLATE="8.2-fpm-alpine" -make build IMAGE_TEMPLATE="8.2-supervisord-alpine" -make build IMAGE_TEMPLATE="8.3-cli-alpine" -make build IMAGE_TEMPLATE="8.3-fpm-alpine" -make build IMAGE_TEMPLATE="8.3-supervisord-alpine" -``` + Replace `8.3-fpm-alpine` with your desired PHP version, type, and OS. -
+- Test all images: -## ๐Ÿงช Testing + ```bash + make test IMAGE_TEMPLATE="8.1-cli-alpine" + make test IMAGE_TEMPLATE="8.1-fpm-alpine" + make test IMAGE_TEMPLATE="8.1-supervisord-alpine" + make test IMAGE_TEMPLATE="8.2-cli-alpine" + make test IMAGE_TEMPLATE="8.2-fpm-alpine" + make test IMAGE_TEMPLATE="8.2-supervisord-alpine" + make test IMAGE_TEMPLATE="8.3-cli-alpine" + make test IMAGE_TEMPLATE="8.3-fpm-alpine" + make test IMAGE_TEMPLATE="8.3-supervisord-alpine" + ``` -You can check `Makefile` to get full list of commands for local testing. For testing, you can use these commands to test whole role or separate tasks: +### โ†’ Test Configuration -Testing default image: +The test configurations are defined in `goss.yaml` files, which are generated for each image variant. These files specify the tests to be run, including: -```bash -make test -``` +- File existence and permissions +- Process checks +- Port availability +- Package installations +- Command outputs +- PHP extension availability -To test all images: +### โ†’ Test Process -```bash -make test IMAGE_TEMPLATE="8.1-cli-alpine" -make test IMAGE_TEMPLATE="8.1-fpm-alpine" -make test IMAGE_TEMPLATE="8.1-supervisord-alpine" -make test IMAGE_TEMPLATE="8.2-cli-alpine" -make test IMAGE_TEMPLATE="8.2-fpm-alpine" -make test IMAGE_TEMPLATE="8.2-supervisord-alpine" -make test IMAGE_TEMPLATE="8.3-cli-alpine" -make test IMAGE_TEMPLATE="8.3-fpm-alpine" -make test IMAGE_TEMPLATE="8.3-supervisord-alpine" -``` +When you run the `make test` command, the following steps occur: + +1. The specified Docker image is built (if not already present). +2. dgoss runs the tests defined in the `goss.yaml` file against the Docker container. +3. The test results are displayed in the console.
-### โ†’ Code quality tools +## ๐Ÿ”’ Security Policy -Run **yamllint** to validate all yaml files in project: +This project has a [security policy](.github/SECURITY.md). -```bash -make lint-yaml -``` +
-Run hadolint to validate created Dockerfiles: +## ๐Ÿ™Œ Want to Contribute? -```bash -make lint-docker -``` +Thank you for considering contributing to the wayofdev community! We are open to all kinds of contributions. If you want to: -Run ansible-lint to validate ansible project files: +- ๐Ÿค” [Suggest a feature](https://github.com/wayofdev/docker-php-base/issues/new?assignees=&labels=type%3A+enhancement&projects=&template=2-feature-request.yml&title=%5BFeature%5D%3A+) +- ๐Ÿ› [Report an issue](https://github.com/wayofdev/docker-php-base/issues/new?assignees=&labels=type%3A+documentation%2Ctype%3A+maintenance&projects=&template=1-bug-report.yml&title=%5BBug%5D%3A+) +- ๐Ÿ“– [Improve documentation](https://github.com/wayofdev/docker-php-base/issues/new?assignees=&labels=type%3A+documentation%2Ctype%3A+maintenance&projects=&template=4-docs-bug-report.yml&title=%5BDocs%5D%3A+) +- ๐Ÿ‘จโ€๐Ÿ’ป [Contribute to the code](./github/CONTRIBUTING.md) -```bash -make lint-ansible -``` +You are more than welcome. Before contributing, kindly check our [contribution guidelines](.github/CONTRIBUTING.md). -Run [dive](https://github.com/wagoodman/dive) command to analyze image: - -```bash -make analyze -``` +[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=for-the-badge)](https://conventionalcommits.org)
-## ๐Ÿค License - -[![Licence](https://img.shields.io/github/license/wayofdev/docker-php-base?style=for-the-badge&color=blue)](./LICENSE) +## ๐Ÿซก Contributors +

+ +Contributors Badge +
+
+

-## ๐Ÿ™†๐Ÿผโ€โ™‚๏ธ Author Information +## ๐ŸŒ Social Links -This repository was created in **2022** by [lotyp / wayofdev](https://github.com/wayofdev). +- **Twitter:** Follow our organization [@wayofdev](https://twitter.com/intent/follow?screen_name=wayofdev) and the author [@wlotyp](https://twitter.com/intent/follow?screen_name=wlotyp). +- **Discord:** Join our community on [Discord](https://discord.gg/CE3TcCC5vr).
-## ๐Ÿซก Contributors +## โš–๏ธ License -Contributors +[![Licence](https://img.shields.io/github/license/wayofdev/docker-php-base?style=for-the-badge&color=blue)](./LICENSE.md)