From 1dd432d1e4af07d6e6f6cc1b6bb73fc20de97411 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Tue, 11 Feb 2020 15:13:40 -0600 Subject: [PATCH 1/3] Updated Cloud Guide navigation to make launch instructions more accessible: - Added the Docker Development > Launch Docker navigation heading - Changes the top-level navigation title from "Launch Docker" to "Configure and launch Docker" - Updated the Launch developer and Launch production topics to include links to the Docker configuration topics - Changed title of "Launch modes" subsection to add what launch modes are for --- src/_data/main-nav.yml | 2 +- src/_data/toc/cloud-guide.yml | 10 ++++++---- .../cloud/note-docker-config-reference-link.md | 2 ++ src/cloud/docker/docker-config.md | 2 +- src/cloud/docker/docker-development.md | 2 ++ src/cloud/docker/docker-mode-production.md | 2 ++ src/cloud/docker/docker-quick-reference.md | 8 ++++++-- src/cloud/reference/ece-tools-reference.md | 2 +- src/cloud/release-notes/cloud-release-archive.md | 2 +- 9 files changed, 22 insertions(+), 10 deletions(-) create mode 100644 src/_includes/cloud/note-docker-config-reference-link.md diff --git a/src/_data/main-nav.yml b/src/_data/main-nav.yml index 013cceb29d2..7937914a8e2 100644 --- a/src/_data/main-nav.yml +++ b/src/_data/main-nav.yml @@ -29,7 +29,7 @@ url: /cloud/docker/docker-development.html versionless: true - - label: Launch Docker + - label: Configure and launch Docker url: /cloud/docker/docker-config.html versionless: true diff --git a/src/_data/toc/cloud-guide.yml b/src/_data/toc/cloud-guide.yml index 696b1d904ee..e62e49183d0 100644 --- a/src/_data/toc/cloud-guide.yml +++ b/src/_data/toc/cloud-guide.yml @@ -144,7 +144,13 @@ pages: - label: Manage cron jobs url: /cloud/docker/docker-manage-cron-jobs.html versionless: true + + - label: Extend Docker + url: /cloud/docker/docker-extend.html + versionless: true + - label: Launch Docker + children: - label: Developer mode url: /cloud/docker/docker-mode-developer.html versionless: true @@ -152,10 +158,6 @@ pages: - label: Production mode url: /cloud/docker/docker-mode-production.html versionless: true - - - label: Extend Docker - url: /cloud/docker/docker-extend.html - versionless: true - label: Functional Testing children: diff --git a/src/_includes/cloud/note-docker-config-reference-link.md b/src/_includes/cloud/note-docker-config-reference-link.md new file mode 100644 index 00000000000..e6eea37f8f4 --- /dev/null +++ b/src/_includes/cloud/note-docker-config-reference-link.md @@ -0,0 +1,2 @@ +{:.bs-callout-info} +See [Configure Docker]({{site.baseurl}}/cloud/docker/docker-config.html) for additional information about Docker prerequisites and using the Magento Cloud Docker environment. \ No newline at end of file diff --git a/src/cloud/docker/docker-config.md b/src/cloud/docker/docker-config.md index 1e2c21d5d18..1985216bb03 100644 --- a/src/cloud/docker/docker-config.md +++ b/src/cloud/docker/docker-config.md @@ -51,7 +51,7 @@ The `ece-docker build:compose` command overwrites the existing `docker-compose.y 1. Optionally, [enable Xdebug]. -## Launch modes +## Launch modes for configuring the Docker environment _Mode_ is an additional configuration option for the Docker configuration generator (the `ece-docker build:compose` command). This mode option does not affect the Magento mode. It determines the {{site.data.var.ece}} file system installation and read-only or read-write behavior. diff --git a/src/cloud/docker/docker-development.md b/src/cloud/docker/docker-development.md index 7caf987f71d..b4b10badd34 100644 --- a/src/cloud/docker/docker-development.md +++ b/src/cloud/docker/docker-development.md @@ -9,6 +9,8 @@ functional_areas: {{site.data.var.ece}} provides a Docker environment option for those who use their local environment for development, test, or automation tasks. The {{site.data.var.ece}} Docker environment requires three, essential components: a {{site.data.var.ee}} v2 template, Docker Compose, and the {{site.data.var.ece}} `{{site.data.var.ct}}` package. +{%include cloud/note-docker-config-reference-link.md%} + ## Host Operating Systems The Cloud Docker environment supports Linux, macOS, and Windows operating systems. The containers should run on any Docker host, but some of the set up scripts require you to install PHP and Composer. diff --git a/src/cloud/docker/docker-mode-production.md b/src/cloud/docker/docker-mode-production.md index ef900c2a46d..2f401fbfdde 100644 --- a/src/cloud/docker/docker-mode-production.md +++ b/src/cloud/docker/docker-mode-production.md @@ -9,6 +9,8 @@ functional_areas: Production mode is the default configuration setting for launching the Docker environment with read-only filesystem permissions. This option builds the Docker environment in production mode and verifies configured service versions. +{%include cloud/note-docker-config-reference-link.md%} + {:.procedure} To launch the Docker environment in developer mode: diff --git a/src/cloud/docker/docker-quick-reference.md b/src/cloud/docker/docker-quick-reference.md index 304bc563415..e393868e1f6 100644 --- a/src/cloud/docker/docker-quick-reference.md +++ b/src/cloud/docker/docker-quick-reference.md @@ -6,6 +6,9 @@ functional_areas: - Docker --- +{:.bs-callout-info} +See [Configure Docker] for details on configuring and launching a {{site.data.var.mcd-prod}} environment. + ## docker-compose Action | Command @@ -39,8 +42,8 @@ docker-compose -f docker-compose.yml -f docker-compose-custom.yml [-f more-custo | Option | Key | Available values | ------------ | ---------------- | ------------------ -| [Mode]({{site.baseurl}}/cloud/docker/docker-config.html#launch-modes) | `--mode`, `-m` | production, developer -| [File synchronization engine]({{site.baseurl}}/cloud/docker/docker-config.html#launch-modes) | `--sync-engine` | native (default), docker-sync, mutagen +| [Mode]({{site.baseurl}}/cloud/docker/docker-config.html#launch-modes-for-configuring-the-docker-environment) | `--mode`, `-m` | production, developer +| [File synchronization engine]({{site.baseurl}}/cloud/docker/docker-config.html#launch-modes-for-configuring-the-docker-environment) | `--sync-engine` | native (default), docker-sync, mutagen {:.bs-callout-info} See [Service versions] for a list of the options to configure the software service version when building your {{site.data.var.mcd-prod}} environment. @@ -80,3 +83,4 @@ Destroy containers | `down` Destroy, re-create, and start containers | `up` [Service versions]: {{site.baseurl}}/cloud/docker/docker-containers.html#service-containers +[Configure Docker]: {{site.baseurl}}/cloud/docker/docker-config.html diff --git a/src/cloud/reference/ece-tools-reference.md b/src/cloud/reference/ece-tools-reference.md index 24ee0425351..3d584cd139d 100644 --- a/src/cloud/reference/ece-tools-reference.md +++ b/src/cloud/reference/ece-tools-reference.md @@ -127,7 +127,7 @@ Ideal state is configured The `{{site.data.var.ct}}` package includes a dependency for the [magento/magento-cloud-patches] package, which delivers Magento patches and hot fixes that improve the integration of all {{site.data.var.ee}} versions with Cloud environments and supports quick delivery of critical fixes. The `{{site.data.var.mcp}}` also delivers custom patches that you add to your {{site.data.var.ece}} project. See [Apply patches]. -[mode]: {{site.baseurl}}/cloud/docker/docker-config.html#launch-modes +[mode]: {{site.baseurl}}/cloud/docker/docker-config.html#launch-modes-for-configuring-the-docker-environment [hooks]: {{site.baseurl}}/cloud/project/project-conf-files_magento-app.html#hooks [cloudvar]: {{site.baseurl}}/cloud/env/variables-cloud.html [wizard]: {{site.baseurl}}/cloud/deploy/smart-wizards.html diff --git a/src/cloud/release-notes/cloud-release-archive.md b/src/cloud/release-notes/cloud-release-archive.md index 6bb1eee6dc5..68d33c0f35b 100644 --- a/src/cloud/release-notes/cloud-release-archive.md +++ b/src/cloud/release-notes/cloud-release-archive.md @@ -139,7 +139,7 @@ The `{{site.data.var.ct}}` 2002.0.22 release changes the structure of the `{{sit - {:.new}**New Docker Image**—Added a Node.js image to support Gulp and other capabilities, such as Jasmine JS Unit Testing. - - {:.new}**Docker build modes**—Now you can choose to launch the Docker environment in [Production mode or Developer mode]({{ site.baseurl }}/cloud/docker/docker-config.html#launch-modes). Developer mode supports active development with full, writable filesystem permissions. + - {:.new}**Docker build modes**—Now you can choose to launch the Docker environment in [Production mode or Developer mode]({{ site.baseurl }}/cloud/docker/docker-config.html#launch-modes-for-configuring-the-docker-environment). Developer mode supports active development with full, writable filesystem permissions. - {:.fix}Fixed an issue that caused Docker deploy to fail with a `Name or service not known` error if the cache is configured for a service that is not available. Now, you can remove a service from the [`.magento/services.yaml` file]({{ site.baseurl }}/cloud/project/project-conf-files_services.html). The Docker configuration generator updates the service in the `docker/config.php.dist` file automatically. From 00cdca594105465101c9f16fcaa266cd6a71560d Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Tue, 11 Feb 2020 15:56:08 -0600 Subject: [PATCH 2/3] Updated the `Backward incompatible changes` topic in the _ Cloud Guide_ to include new requirement to specify `--with-cron` option to build a Magento Cloud Docker environment that includes a Cron container. --- src/cloud/release-notes/backward-incompatible-changes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/cloud/release-notes/backward-incompatible-changes.md b/src/cloud/release-notes/backward-incompatible-changes.md index 153aa969d3c..4773e1a49f8 100644 --- a/src/cloud/release-notes/backward-incompatible-changes.md +++ b/src/cloud/release-notes/backward-incompatible-changes.md @@ -73,6 +73,10 @@ In earlier {{ site.data.var.ct }} releases, you could use the `m2-ece-build` and - **Updating the Magento Cloud docker-compose commands**–We renamed the path to the command file from `./bin/docker` to `./bin/magento-docker`. Update your scripts and commands to use the new path. + - **Cron container no longer included in default Docker configuration**–Now, you must add the `--with-cron` option to the `ece-docker build:compose` command to include the Cron container in the Docker environment configuration. See [Manage cron jobs]({{site.baseurl}}/cloud/docker/docker-manage-cron-jobs.html). + + Any scripts that previously generated containers with crons will now be lacking crons. + - **Using temporary containers**–In previous versions, the containers created by `bin/magento-docker` command operations were not removed, so you could use them for other operations. Now, the `magento-docker` commands remove any containers they create after the command completes. If you want to keep a container created by a docker-compose operation, use the `docker-compose run` command instead of the `bin/magento-docker` command. From 784402c67ab8906430a1e0a0c7d5425c29114616 Mon Sep 17 00:00:00 2001 From: Margaret Eker Date: Wed, 12 Feb 2020 16:41:35 -0600 Subject: [PATCH 3/3] Updates based on review feedback --- src/cloud/docker/docker-config.md | 17 +++++++++-------- src/cloud/docker/docker-quick-reference.md | 7 +++---- src/cloud/reference/ece-tools-reference.md | 2 +- .../release-notes/cloud-release-archive.md | 4 ++-- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/src/cloud/docker/docker-config.md b/src/cloud/docker/docker-config.md index 1985216bb03..5e217d5b46e 100644 --- a/src/cloud/docker/docker-config.md +++ b/src/cloud/docker/docker-config.md @@ -51,14 +51,12 @@ The `ece-docker build:compose` command overwrites the existing `docker-compose.y 1. Optionally, [enable Xdebug]. -## Launch modes for configuring the Docker environment +## Set the launch mode -_Mode_ is an additional configuration option for the Docker configuration generator (the `ece-docker build:compose` command). This mode option does not affect the Magento mode. It determines the {{site.data.var.ece}} file system installation and read-only or read-write behavior. +You can launch a Docker environment in production or developer mode by setting the `mode` option on the `ece-docker build:compose` command: -You can launch your Docker environment in one of the following modes: - -- [**production**][prod-mode]—Production mode is the default configuration setting for launching the Docker environment with read-only filesystem permissions. This option builds the Docker environment in production mode and verifies configured service versions. -- [**developer**][dev-mode]—Developer mode supports an active development environment with full, writable filesystem permissions. This option builds the Docker environment in developer mode and verifies configured service versions. System performance is slower in developer mode because of additional file synchronization operations. +- **Production mode**—The `--mode="production"` setting supports an active production environment with read-only filesystem permissions. This is the default configuration setting for launching a Docker environment. Selecting this option builds the Docker environment in production mode and verifies configured service versions. See [Production mode launch instructions][prod-mode]. +- **Developer mode**—The `--mode="developer"` setting supports an active development environment with full, writable filesystem permissions. Selecting this option builds the Docker environment in developer mode and verifies configured service versions. System performance is slower in developer mode because of additional file synchronization operations. See [Developer mode launch instructions][dev-mode]. For example, the following command starts the Docker configuration generator for the developer mode: @@ -68,6 +66,9 @@ For example, the following command starts the Docker configuration generator for To skip the interactive mode, use the `-n, --no-interaction` option. +{:.bs-callout-info} +The mode option for the `ece-docker build:compose` command does not affect the Magento mode. It determines the {{site.data.var.ece}} file system installation and read-only or read-write behavior. + ## Stop and start containers You can stop containers and restore them afterwards using the following methods. @@ -89,7 +90,7 @@ Use the following command to stop and remove the Docker configuration: {: .bs-callout-warning} This command removes all components of your local Docker instance including containers, networks, volumes, and images except for the persistent database and the `magento-sync` volume. See [Rebuild a clean environment][refresh]. -## Running Composer with Docker +## Run Composer with Docker You can run composer using the `docker` command before you create the container instance. This technique is useful to create an application instance during the CI/CD build process, or even during first time Magento set up. @@ -101,7 +102,7 @@ docker run -it -v $(pwd):/app/ -v ~/.composer/:/root/.composer/ magento/magento This command passes in the current working directory as `/app/`, includes composer from `~/.composer/`, and runs the `composer install` command in the container. After this set up, the command fixes the permissions on the files that have been added or changed. -## Sendmail service +## Set up email Send emails from your Docker environment by adding the following configuration to the `docker-compose.yml` configuration file: diff --git a/src/cloud/docker/docker-quick-reference.md b/src/cloud/docker/docker-quick-reference.md index e393868e1f6..baa0e24887a 100644 --- a/src/cloud/docker/docker-quick-reference.md +++ b/src/cloud/docker/docker-quick-reference.md @@ -6,8 +6,7 @@ functional_areas: - Docker --- -{:.bs-callout-info} -See [Configure Docker] for details on configuring and launching a {{site.data.var.mcd-prod}} environment. +{%include cloud/note-docker-config-reference-link.md%} ## docker-compose @@ -42,8 +41,8 @@ docker-compose -f docker-compose.yml -f docker-compose-custom.yml [-f more-custo | Option | Key | Available values | ------------ | ---------------- | ------------------ -| [Mode]({{site.baseurl}}/cloud/docker/docker-config.html#launch-modes-for-configuring-the-docker-environment) | `--mode`, `-m` | production, developer -| [File synchronization engine]({{site.baseurl}}/cloud/docker/docker-config.html#launch-modes-for-configuring-the-docker-environment) | `--sync-engine` | native (default), docker-sync, mutagen +| [Mode]({{site.baseurl}}/cloud/docker/docker-config.html#set-the-launch-mode) | `--mode`, `-m` | production, developer +| [File synchronization engine]({{site.baseurl}}/cloud/docker/docker-syncing-data.html) | `--sync-engine` | native (default), docker-sync, mutagen {:.bs-callout-info} See [Service versions] for a list of the options to configure the software service version when building your {{site.data.var.mcd-prod}} environment. diff --git a/src/cloud/reference/ece-tools-reference.md b/src/cloud/reference/ece-tools-reference.md index 3d584cd139d..c2ccdff6a9c 100644 --- a/src/cloud/reference/ece-tools-reference.md +++ b/src/cloud/reference/ece-tools-reference.md @@ -127,7 +127,7 @@ Ideal state is configured The `{{site.data.var.ct}}` package includes a dependency for the [magento/magento-cloud-patches] package, which delivers Magento patches and hot fixes that improve the integration of all {{site.data.var.ee}} versions with Cloud environments and supports quick delivery of critical fixes. The `{{site.data.var.mcp}}` also delivers custom patches that you add to your {{site.data.var.ece}} project. See [Apply patches]. -[mode]: {{site.baseurl}}/cloud/docker/docker-config.html#launch-modes-for-configuring-the-docker-environment +[mode]: {{site.baseurl}}/cloud/docker/docker-config.html#set-the-launch-mode [hooks]: {{site.baseurl}}/cloud/project/project-conf-files_magento-app.html#hooks [cloudvar]: {{site.baseurl}}/cloud/env/variables-cloud.html [wizard]: {{site.baseurl}}/cloud/deploy/smart-wizards.html diff --git a/src/cloud/release-notes/cloud-release-archive.md b/src/cloud/release-notes/cloud-release-archive.md index 68d33c0f35b..cc83bbcb483 100644 --- a/src/cloud/release-notes/cloud-release-archive.md +++ b/src/cloud/release-notes/cloud-release-archive.md @@ -139,7 +139,7 @@ The `{{site.data.var.ct}}` 2002.0.22 release changes the structure of the `{{sit - {:.new}**New Docker Image**—Added a Node.js image to support Gulp and other capabilities, such as Jasmine JS Unit Testing. - - {:.new}**Docker build modes**—Now you can choose to launch the Docker environment in [Production mode or Developer mode]({{ site.baseurl }}/cloud/docker/docker-config.html#launch-modes-for-configuring-the-docker-environment). Developer mode supports active development with full, writable filesystem permissions. + - {:.new}**Docker build modes**—Now you can choose to launch the Docker environment in [Production mode or Developer mode]({{ site.baseurl }}/cloud/docker/docker-config.html#set-the-launch-mode). Developer mode supports active development with full, writable filesystem permissions. - {:.fix}Fixed an issue that caused Docker deploy to fail with a `Name or service not known` error if the cache is configured for a service that is not available. Now, you can remove a service from the [`.magento/services.yaml` file]({{ site.baseurl }}/cloud/project/project-conf-files_services.html). The Docker configuration generator updates the service in the `docker/config.php.dist` file automatically. @@ -198,7 +198,7 @@ The `{{site.data.var.ct}}` version 2002.0.17 includes an important security patc - Now, the default service configuration generated in the Docker environment is the same as the default configuration in the Cloud template. - - You can send mail from your Docker environment using the [`sendmail` service]({{ site.baseurl }}/cloud/docker/docker-config.html#sendmail-service). + - You can send mail from your Docker environment using the [`sendmail` service]({{ site.baseurl }}/cloud/docker/docker-config.html#set-up-email). - Added the ability to [configure Xdebug]({{ site.baseurl }}/cloud/docker/docker-development-debug.html) to debug in the Cloud Docker environment.