diff --git a/src/cloud/docker/docker-extend.md b/src/cloud/docker/docker-extend.md index 67dd31aa8e7..10d0b0a0ea3 100644 --- a/src/cloud/docker/docker-extend.md +++ b/src/cloud/docker/docker-extend.md @@ -11,19 +11,19 @@ You can use the built-in extension mechanism of Docker to specify [multiple comp 1. Create a `docker-compose-dev.yml` file inside your project root directory and add the following content: - ```yaml - version: '2' - services: - deploy: + ```yaml + version: '2' + services: + deploy: environment: - - ENABLE_SENDMAIL=false + - ENABLE_SENDMAIL=false ``` 1. Pass both configuration files while executing your commands. For example: - ```bash - docker-compose -f docker-compose.yml -f docker-compose-dev.yml run deploy bash - ``` + ```bash + docker-compose -f docker-compose.yml -f docker-compose-dev.yml run deploy bash + ``` ## Specify Docker build sources @@ -32,34 +32,34 @@ by adding the `build:context` configuration to the `docker-compose.override.yml` The following example defines the build context for the Web container. You can use the same technique to build from any of the images in the `vendor/magento/magento-cloud-docker` directory or any other Docker image, including local images that are resourced outside the project. -```yaml -version: '2.1' -services: - web: - build: - context: ./vendor/magento/magento-cloud-docker/images/nginx/1.9/ -``` + ```yaml + version: '2.1' + services: + web: + build: + context: ./vendor/magento/magento-cloud-docker/images/nginx/1.9/ + ``` To update the container configuration and test iteratively, use the `--force-recreate` option to refresh the container build: -```bash -docker-compose up -d --force-recreate --build -``` + ```bash + docker-compose up -d --force-recreate --build + ``` ## Add a new version of existing service -In {{site.data.var.mcd}} package the available [service versions] are determined by the Docker service images configured in the {{site.data.var.mcd}} `images` directory. You can add a new service version by creating a directory for the version and adding a `Dockerfile` and other files to configure the new version. +In the `{{site.data.var.mcd-package}}` package the available [service versions] are determined by the Docker service images configured in the `{{site.data.var.mcd-package}}` `images` directory. You can add a new service version by creating a directory for the version and adding a `Dockerfile` and other files to configure the new version. {:.procedure} To add a new service version using a `Dockerfile`: -1. Clone the `{{site.data.var.mcd}}` project to your local environment if necessary. +1. Clone the `{{site.data.var.mcd-package}}` project to your local environment if necessary. 1. On the command line, change to the directory that contains the existing service version configurations. - ```bash - cd magento-cloud-docker/images/ - ``` + ```bash + cd magento-cloud-docker/images/ + ``` 1. Create a directory for the new version. @@ -71,8 +71,10 @@ To add a new service version using a `Dockerfile`: 1. Run the following command to build the image. - `docker build -t test/:` - + ```bash + docker build -t test/: + ``` + 1. Once the build succeeds, test the changes by specifying the [Docker build sources]. ## Add a new PHP extension @@ -82,26 +84,151 @@ In addition to built-in extensions, you can add PHP extensions to the PHP contai {:.procedure} To add a new PHP extension: -1. Clone the `{{site.data.var.mcd}}` project to your local environment if necessary. +1. Clone the `{{site.data.var.mcd-package}}` project to your local environment if necessary. 1. On the command line, navigate to the PHP directory. - ```bash - cd magento-cloud-docker/src/Compose/Php - -1. Open the `ExtensionResolver.php` file, define the required extension inside the `getConfig` method by specifying the extension type and dependency. - - For instance the following block adds the GNUPG extension: - - ```php?start_inline=1 + ```shell script + cd magento-cloud-docker/src/Compose/Php + ``` + +1. Add one or more extensions: to the `ExtensionResolver.php` file: + + - Open the `ExtensionResolver.php` file for editing. + + - Define the required extension in the `getConfig` method by specifying the extension type and dependency. + + We have divided the extensions into three conditional groups: + 1. `EXTENSION_TYPE_CORE` - Extension that exists in the `docker-php-source`. More details can be found at [https://hub.docker.com/_/php][PHP, Docker Official Images], in the "How to install more PHP extensions" section. + 1. `EXTENSION_TYPE_PECL` - Extensions that can be installed from [https://pecl.php.net/][PECL]. More details can be found at [https://hub.docker.com/_/php][PHP, Docker Official Images], in the "PECL extensions" section. + 1. `EXTENSION_TYPE_INSTALLATION_SCRIPT` - For extensions that can be installed by running a number commands. More details can be found at [https://hub.docker.com/_/php][PHP, Docker Official Images], in the "Other extensions" section. + + For instance, the following block adds the `bcmath` extension: + + ```php?start_inline=1 + 'bcmath' => [ + '>=7.0' => [self::EXTENSION_TYPE => self::EXTENSION_TYPE_CORE], + ], + ``` + + In this case, the `bcmath` extension installs from `docker-php-source` for all `PHP` versions starting from `7.0`. + + In the case of installing an extension from `PECL` which has a dependency on a specific package: + ```php?start_inline=1 'gnupg' => [ '>=7.0' => [ - self::EXTENSION_TYPE => self::EXTENSION_TYPE_PECL, - self::EXTENSION_OS_DEPENDENCIES => ['libgpgme11-dev'], - ],], - ``` - - The extension type can be either CORE or PECL, which are defined as `EXTENSION_TYPE_PECL` or `EXTENSION_TYPE_CORE` respectively. + self::EXTENSION_TYPE => self::EXTENSION_TYPE_PECL, + self::EXTENSION_OS_DEPENDENCIES => ['libgpgme11-dev'], + ], + ], + ``` + For extension types `EXTENSION_TYPE_PECL`\\`EXTENSION_TYPE_PECL`, the following configuration pattern is valid: + + ```php?start_inline=1 + '' => [ // Name to identify the extension among other PHP extensions. + '' => [ // Specifies which PHP versions this configuration applies to + self::EXTENSION_TYPE => self::EXTENSION_TYPE_CORE // or self::EXTENSION_TYPE_PECL + self::EXTENSION_OS_DEPENDENCIES => ['', , ... ] // Specifies Linux package dependencies. These packages install in the order listed before installing the extension. + self::EXTENSION_PACKAGE_NAME => '', // if this parameter exists, then this value will be used when generating the installation command + self::EXTENSION_CONFIGURE_OPTIONS => [ // options to be applied when configuring a PHP extension using the command `docker-php-ext-configure`. See the the "PHP Core Extensions" section in the [https://hub.docker.com/_/php][PHP, Docker Official Images] documentation. + '--option1', + '--option2', + ... + ] + ], + '' => [ + .... + ] + ``` + + Configuration for extensions `gd`, `geoip` are good examples: + + ```php?start_inline=1 + 'gd' => [ + '>=7.0 <=7.3' => [ + self::EXTENSION_TYPE => self::EXTENSION_TYPE_CORE, + self::EXTENSION_OS_DEPENDENCIES => ['libjpeg62-turbo-dev', 'libpng-dev', 'libfreetype6-dev'], + self::EXTENSION_CONFIGURE_OPTIONS => [ + '--with-freetype-dir=/usr/include/', + '--with-jpeg-dir=/usr/include/' + ], + ], + '>=7.4' => [ + self::EXTENSION_TYPE => self::EXTENSION_TYPE_CORE, + self::EXTENSION_OS_DEPENDENCIES => ['libjpeg62-turbo-dev', 'libpng-dev', 'libfreetype6-dev'], + self::EXTENSION_CONFIGURE_OPTIONS => [ + '--with-freetype=/usr/include/', + '--with-jpeg=/usr/include/' + ], + ], + + ], + 'geoip' => [ + '>=7.0' => [ + self::EXTENSION_TYPE => self::EXTENSION_TYPE_PECL, + self::EXTENSION_OS_DEPENDENCIES => ['libgeoip-dev', 'wget'], + self::EXTENSION_PACKAGE_NAME => 'geoip-1.1.1', + ], + ], + ``` + + If the installation requires multi-step command processing, use the `EXTENSION_TYPE_INSTALLATION_SCRIPT` type. + The template for this type: + + ```php?start_inline=1 + 'extension name' => [ + 'php version constraint' => [ + self::EXTENSION_TYPE => self::EXTENSION_TYPE_INSTALLATION_SCRIPT, + self::EXTENSION_INSTALLATION_SCRIPT => <<< BASH + + BASH + ], + ``` + + Usage example: + ```php?start_inline=1 + 'ioncube' => [ + '>=7.0 <=7.3' => [ + self::EXTENSION_TYPE => self::EXTENSION_TYPE_INSTALLATION_SCRIPT, + self::EXTENSION_INSTALLATION_SCRIPT => <<< BASH + cd /tmp + curl -O https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz + tar zxvf ioncube_loaders_lin_x86-64.tar.gz + export PHP_VERSION=$(php -r "echo PHP_MAJOR_VERSION.'.'.PHP_MINOR_VERSION;") + export PHP_EXT_DIR=$(php-config --extension-dir) + cp "./ioncube/ioncube_loader_lin_\${PHP_VERSION}.so" "\${PHP_EXT_DIR}/ioncube.so" + rm -rf ./ioncube + rm ioncube_loaders_lin_x86-64.tar.gz + BASH + ], + ``` +1. If you want the extension to be enabled by default, then add it to the array `DEFAULT_PHP_EXTENSIONS` + +```php?start_inline=1 + /** + * Extensions which should be installed by default + */ + public const DEFAULT_PHP_EXTENSIONS = [ + 'bcmath', + 'bz2', + 'calendar', + 'exif', + 'gd', + 'gettext', + 'intl', + 'mysqli', + 'pcntl', + 'pdo_mysql', + 'soap', + 'sockets', + 'sysvmsg', + 'sysvsem', + 'sysvshm', + 'opcache', + 'zip', + ]; +``` +Otherwise, to enable an extension, you must specify the name of the extension in the `.magento.app.yaml` for your Cloud project, regenerate the Docker compose configuration file, and restart the Docker container. 1. Add any required `.ini` files to the PHP FPM container configuration.