Updates for Cloud Docker 1.2.0 release (#8198)

* Updated Docker Quick reference

- Addedd new options to the magento-docker CLI
- Added listing that shows all available options for ece-docker
build:compose command
- Added intro to Docker Compose section

* MCLOUD-7809 Added instructions for building custom docker-compose.yaml file

* Improved instructions for using the init-docker.sh installation script

* Updates for Magento Cloud Docker 1.2.0 release notes

Co-authored-by: maeker12 <{ID}+{username}@users.noreply.github.com>

Author: meker12

src/_data/toc/cloud-guide.yml

@@ -215,14 +215,15 @@ pages:
               versionless: true
 
         - label: Launch Docker
-          children: 
-            - label: Developer mode
-              url: /cloud/docker/docker-mode-developer.html
-              versionless: true
 
+          children: 
             - label: Production mode
               url: /cloud/docker/docker-mode-production.html
               versionless: true
+ 
+            - label: Developer mode
+              url: /cloud/docker/docker-mode-developer.html
+              versionless: true
 
         - label: Functional Testing
           children:

src/_data/var.yml

@@ -21,7 +21,7 @@ mbi: Magento Business Intelligence
 # Cloud product name variables
 
 ece: Magento Commerce Cloud
-ece-release-date: August 5, 2020
+ece-release-date: November 9, 2020
 csuite: Magento Commerce Cloud Suite
 ct: ece-tools
 ct-repo: magento/ece-tools
@@ -31,7 +31,7 @@ mcp-package: magento/magento-cloud-patches
 mcp-release: 1.0.8
 mcd-package: magento/magento-cloud-docker
 mcd-prod: Magento Cloud Docker
-mcd-release: 1.1.2
+mcd-release: 1.2.0
 mcc-prod: Magento Cloud Components
 mcc-package: magento/magento-cloud-components
 mcc-release: 1.0.7

src/cloud/docker/docker-config.md

@@ -142,7 +142,7 @@ By default, MailHog listens on port 1025 for SMTP and port 8025 for the frontend
 
 After updating the configuration and restarting the Docker environment, you can connect to the MailHog service from `http://magento2.docker:8026`, and use port 1026 for SMTP communication.
 
-If you do not need the [MailHog] service, use the `--no-mailhog` option to generate the Docker compose configuration: 
+If you do not need the [MailHog] service, use the `--no-mailhog` option to generate the Docker compose configuration:
 
 ```bash
 ./vendor/bin/ece-docker build:compose --no-mailhog

src/cloud/docker/docker-containers-service.md

@@ -86,8 +86,8 @@ You can change the list of plugins to install by updating the configuration for
 services:
     elasticsearch:
         environment:
-          - 'ES_PLUGINS=analysis-stempel analysis-nori'   
-``` 
+          - 'ES_PLUGINS=analysis-stempel analysis-nori'
+```
 
 ### Troubleshooting
 

src/cloud/docker/docker-containers.md

@@ -54,7 +54,7 @@ The following table shows the options to customize service container configurati
 | [varnish][varnish-container] | Varnish | `--no-varnish` | 4, 6.2 | Varnish is provisioned by default. Use the `--no-varnish` option to skip Varnish service installation
 | [web][web-container] | NGINX | `--nginx` | 1.9, latest |
 
-Use the following command to view the available options for the `ece-docker build:compose` command:
+Use the following command to view all available options for the `ece-docker build:compose` command:
 
 ```bash
 ./vendor/bin/ece-docker build:compose --help

src/cloud/docker/docker-development-debug.md

@@ -25,9 +25,9 @@ If you use Microsoft Windows, take the following steps before continuing:
    ```bash
    vendor/bin/ece-docker build:compose --mode="developer" --sync-engine="mutagen" --with-xdebug
    ```
-   
+
    For Linux systems, you must use the `--set-docker-host` option to add the `host.docker.internal` entry to the `/etc/hosts` file for the `fpm_xdebug` container.
-   
+
       ```bash
       vendor/bin/ece-docker build:compose --mode="developer" --with-xdebug --set-docker-host
       ```

src/cloud/docker/docker-mode-developer.md

@@ -26,13 +26,15 @@ To launch the Docker environment in developer mode:
 1. Install the template dependencies, and add the default hostname to your `/etc/hosts` file.
 
    ```bash
-   curl https://raw.githubusercontent.com/magento/magento-cloud-docker/1.1.0/bin/init-docker.sh | bash
+   curl https://raw.githubusercontent.com/magento/magento-cloud-docker/<magento-cloud-docker-package-version>/bin/init-docker.sh | bash
    ```
 
-   If required, you can add options to the `init-docker.sh` initialization script to customize your Docker environment. Run the following command to see the available options:
+   For `<package-version>`, use the [latest release of the {{site.data.var.mcd-package}}].
+
+   You can customize the options for the `init-docker.sh` initialization script your Docker environment. For example, you can specify the PHP version (default is 7.2) and the [Docker image version] (default 1.1). We recommend using the latest version of the Magento Cloud Docker images. Run the following command to see the available options:
 
    ```bash
-   curl https://raw.githubusercontent.com/magento/magento-cloud-docker/1.1.0/bin/init-docker.sh | bash -s -- --help
+   curl https://raw.githubusercontent.com/magento/magento-cloud-docker/<magento-cloud-package-version>/bin/init-docker.sh | bash -s -- --help
    ```
 
 1. On macOS or Windows hosts, install the selected file synchronization tool:
@@ -129,11 +131,15 @@ To launch the Docker environment in developer mode:
 
    -  `https://magento2.docker`
 
-[Synchronizing data in Docker]: {{site.baseurl}}/cloud/docker/docker-syncing-data.html
+<!--Link definitioons-->
+
 [cloud-repo]: https://github.com/magento/magento-cloud
+[Docker image version]: https://hub.docker.com/r/magento/magento-cloud-docker-php/tags
+[dsync-install]: https://docker-sync.readthedocs.io/en/latest/getting-started/installation.html
+[latest release of the {{site.data.var.mcd-package}}]: https://github.com/magento/magento-cloud-docker/releases
 [magento-creds]: {{site.baseurl}}/guides/v2.3/install-gde/prereq/connect-auth.html
+[mutagen-install]: https://mutagen.io/documentation/introduction/installation/
 [services]: {{site.baseurl}}/cloud/docker/docker-containers.html#service-containers
-[xdebug]: {{site.baseurl}}/cloud/docker/docker-development-debug.html#configure-xdebug]
 [service keys]: {{site.baseurl}}/cloud/docker/docker-containers.html#service-configuration-options
-[dsync-install]: https://docker-sync.readthedocs.io/en/latest/getting-started/installation.html
-[mutagen-install]: https://mutagen.io/documentation/introduction/installation/
+[Synchronizing data in Docker]: {{site.baseurl}}/cloud/docker/docker-syncing-data.html
+[xdebug]: {{site.baseurl}}/cloud/docker/docker-development-debug.html#configure-xdebug]

src/cloud/docker/docker-mode-production.md

@@ -21,10 +21,12 @@ To launch the Docker environment in production mode:
 1. Install the template dependencies and add the default hostname to your `/etc/hosts` file, use the following command to run the Docker initialization script:
 
    ```bash
-   curl https://raw.githubusercontent.com/magento/magento-cloud-docker/1.1.0/bin/init-docker.sh | bash
+   curl https://raw.githubusercontent.com/magento/magento-cloud-docker/<package-version>/bin/init-docker.sh | bash
    ```
 
-   If required, you can add options to the `init-docker.sh` initialization script to customize your Docker environment. Run the following command to see the available options:
+   For `<package-version>`, use the [latest release of the {{site.data.var.mcd-package}}].
+
+   You can customize the options for the `init-docker.sh` initialization script your Docker environment. For example, you can specify the PHP version (default is 7.2) and the [Docker image version] (default 1.1). We recommend using the latest version of the Magento Cloud Docker images. Run the following command to see the available options:
 
    ```bash
    curl https://raw.githubusercontent.com/magento/magento-cloud-docker/1.1.0/bin/init-docker.sh | bash -s -- --help
@@ -97,6 +99,7 @@ To launch the Docker environment in production mode:
    -  [`https://magento2.docker`](https://magento2.docker)
 
 [cloud-repo]: https://github.com/magento/magento-cloud
+[Docker image version]: https://hub.docker.com/r/magento/magento-cloud-docker-php/tags
 [magento-creds]: {{site.baseurl}}/guides/v2.3/install-gde/prereq/connect-auth.html
 [services]: {{site.baseurl}}/cloud/docker/docker-containers.html#service-containers
 [configure Xdebug]: {{site.baseurl}}/cloud/docker/docker-development-debug.html#configure-xdebug

src/cloud/docker/docker-quick-reference.md

@@ -111,6 +111,204 @@ Options:
 {:.bs-callout-info}
 See [Service versions] for additional information about the service configuration options for the `ece-docker build:compose` command.
 
+### Build a custom Docker Compose configuration
+
+Instead of building the `docker-compose.yaml` file using the {{site.data.var.ece }} project configuration. You can use the `build:custom:compose` command to build a custom `docker-compose.yaml` file with the configuration you supply. You provide the configuration as a JSON array as shown in [Example 1](#example-1).
+
+For {{site.data.var.mcd-prod}} 1.2 and later, you have an additional option to specify custom images and image versions using the `ece-docker build:custom:compose` command as shown in [Example 2](#example-2).
+
+#### Example 1
+
+> Generate a custom `docker-compose.yaml` file
+
+```bash
+./vendor/bin/ece-docker build:custom:compose '{"name":"magento","system":{"mode":"production","host":"magento2.test","port":"8080","db":{"increment_increment":3,"increment_offset":2},"mailhog":{"smtp_port":"1026","http_port":"8026"}},"services":{"php":{"version":"7.4","enabled":true,"extensions":{"enabled":["xsl"]}},"mysql":{"version":"10.2","image":"mariadb","enabled":true}, "mailhog": {"enabled":true}}}'
+```
+
+This command generates the following `docker-compose.yaml` file:
+
+```terminal
+version: '2.1'
+services:
+  db:
+    hostname: db.magento2.test
+    image: 'mariadb:10.2'
+    environment:
+      - MYSQL_ROOT_PASSWORD=magento2
+      - MYSQL_DATABASE=magento2
+      - MYSQL_USER=magento2
+      - MYSQL_PASSWORD=magento2
+    ports:
+      - '3306'
+    volumes:
+      - '.docker/mnt:/mnt:rw,delegated'
+      - 'magento-magento-db:/var/lib/mysql'
+    healthcheck:
+      test: 'mysqladmin ping -h localhost -pmagento2'
+      interval: 30s
+      timeout: 30s
+      retries: 3
+    command: '--auto_increment_increment=3 --auto_increment_offset=2'
+    networks:
+      magento:
+        aliases:
+          - db.magento2.test
+  fpm:
+    hostname: fpm.magento2.test
+    image: 'magento/magento-cloud-docker-php:7.3-fpm-1.2.0'
+    extends: generic
+    volumes:
+      - '.:/app:ro,delegated'
+      - 'magento-vendor:/app/vendor:ro,delegated'
+      - 'magento-generated:/app/generated:ro,delegated'
+      - '.docker/mnt:/mnt:rw,delegated'
+    networks:
+      magento:
+        aliases:
+          - fpm.magento2.test
+    depends_on:
+      db:
+        condition: service_healthy
+  web:
+    hostname: web.magento2.test
+    image: 'magento/magento-cloud-docker-nginx:1.19-1.2.0'
+    extends: generic
+    volumes:
+      - '.:/app:ro,delegated'
+      - 'magento-vendor:/app/vendor:ro,delegated'
+      - 'magento-generated:/app/generated:ro,delegated'
+      - '.docker/mnt:/mnt:rw,delegated'
+    environment:
+      - WITH_XDEBUG=0
+    networks:
+      magento:
+        aliases:
+          - web.magento2.test
+    depends_on:
+      fpm:
+        condition: service_started
+  varnish:
+    hostname: varnish.magento2.test
+    image: 'magento/magento-cloud-docker-varnish:6.2-1.2.0'
+    networks:
+      magento:
+        aliases:
+          - varnish.magento2.test
+    depends_on:
+      web:
+        condition: service_started
+  tls:
+    hostname: tls.magento2.test
+    image: 'magento/magento-cloud-docker-nginx:1.19-1.2.0'
+    extends: generic
+    networks:
+      magento:
+        aliases:
+          - magento2.test
+    environment:
+      UPSTREAM_HOST: varnish
+    ports:
+      - '8080:80'
+      - '443:443'
+    depends_on:
+      varnish:
+        condition: service_started
+  generic:
+    hostname: generic.magento2.test
+    image: 'magento/magento-cloud-docker-php:7.3-cli-1.2.0'
+    env_file: ./.docker/config.env
+    environment:
+      - 'PHP_EXTENSIONS=bcmath bz2 calendar exif gd gettext intl mysqli pcntl pdo_mysql soap sockets sysvmsg sysvsem sysvshm opcache zip xsl'
+  build:
+    hostname: build.magento2.test
+    image: 'magento/magento-cloud-docker-php:7.3-cli-1.2.0'
+    extends: generic
+    volumes:
+      - '.:/app:rw,delegated'
+      - 'magento-vendor:/app/vendor:rw,delegated'
+      - 'magento-generated:/app/generated:rw,delegated'
+      - '~/.composer/cache:/root/.composer/cache:rw,delegated'
+    networks:
+      magento-build:
+        aliases:
+          - build.magento2.test
+    depends_on:
+      db:
+        condition: service_healthy
+  deploy:
+    hostname: deploy.magento2.test
+    image: 'magento/magento-cloud-docker-php:7.3-cli-1.2.0'
+    extends: generic
+    volumes:
+      - '.:/app:ro,delegated'
+      - 'magento-vendor:/app/vendor:ro,delegated'
+      - 'magento-generated:/app/generated:ro,delegated'
+      - '.docker/mnt:/mnt:rw,delegated'
+    networks:
+      magento:
+        aliases:
+          - deploy.magento2.test
+    depends_on:
+      db:
+        condition: service_healthy
+  mailhog:
+    hostname: mailhog.magento2.test
+    image: 'mailhog/mailhog:latest'
+    ports:
+      - '1026:1025'
+      - '8026:8025'
+    networks:
+      magento:
+        aliases:
+          - mailhog.magento2.test
+volumes:
+  magento-vendor: {  }
+  magento-generated: {  }
+  magento-magento-db: {  }
+networks:
+  magento:
+    driver: bridge
+  magento-build:
+    driver: bridge
+
+```
+
+For {{site.data.var.mcd-prod}} 1.2 and later, you have an additional option to specify custom images and image versions using the `ece-docker build:custom:compose` command.
+
+#### Example 2
+
+> Generate a custom `docker-compose.yaml` file with custom images and image versions
+
+```bash
+./vendor/bin/ece-docker build:custom:compose '{"name":"magento","system":{"mode":"production","host":"magento2.test","port":"8080","db":{"increment_increment":3,"increment_offset":2},"mailhog":{"smtp_port":"1026","http_port":"8026"}},"services":{"php":{"image":"php-v1","version":"7.4","enabled":true},"php-cli":{"image-pattern":"%s:%s-cli"},"php-fpm":{"image-pattern":"%s:%s-fpm"},"mysql":{"image":"mariadb-v1","version":"10.3","image-pattern":"%s:%s","enabled":true},"redis":{"image":"redis-v1","enabled":"true","version":"5"},"elasticsearch":{"image":"elasticsearch-v1","image-pattern":"%s:%s","enabled":true,"version":"7.6"},"varnish":{"image":"varnish-v1","image-pattern":"%s:%s","enabled":true,"version":"6.2"},"nginx":{"image":"nginx-v1","version":"1.19","image-pattern":"%s:%s","enabled":"true"},"test":{"enabled":true}},"mounts":{"var":{"path":"var"},"app-etc":{"path":"app\/etc"},"pub-media":{"path":"pub\/media"},"pub-static":{"path":"pub\/static"}}}'
+```
+
+This command generates the following images in the Docker environment:
+
+```conf
+services:
+  db:
+    image: 'mariadb-v1:10.3'
+  redis:
+    image: 'redis-v1:5'
+  fpm:
+    image: 'php-v1:7.4-fpm'
+  web:
+    image: 'nginx-v1:1.19'
+  varnish:
+    image: 'varnish-v1:6.2'
+  tls:
+    image: 'nginx-v1:1.19'
+  test:
+    image: 'php-v1:7.4-cli'
+  generic:
+    image: 'php-v1:7.4-cli'
+  build:
+    image: 'php-v1:7.4-cli'
+  deploy:
+    image: 'php-v1:7.4-cli'
+```
+
 ## Magento Cloud Docker CLI
 
 The `bin/magento-docker` commands simplify running docker-compose tasks. For example, instead of running a separate docker-compose command for the build, deploy, and post-deploy steps, you can _redeploy_ Magento in a Docker environment using the following command: