diff --git a/guides/v2.2/cloud/project/project-routes-more-cache.md b/guides/v2.2/cloud/project/project-routes-more-cache.md index 0ad7a16a25b..668cb9644d2 100644 --- a/guides/v2.2/cloud/project/project-routes-more-cache.md +++ b/guides/v2.2/cloud/project/project-routes-more-cache.md @@ -8,6 +8,8 @@ functional_areas: {{site.data.var.ee}} enables you to use caching in your environment. If you disable caching, {{site.data.var.ee}} directly serves the files. +{% include cloud/note-route-all-placeholder.md %} + ## Set up caching {#cloud-cache-setup} Enable caching in your Magento application's `.magento/routes.yaml` as follows: diff --git a/guides/v2.2/cloud/project/project-routes-more-ssi.md b/guides/v2.2/cloud/project/project-routes-more-ssi.md index e79bec190b2..e5210eb69ef 100644 --- a/guides/v2.2/cloud/project/project-routes-more-ssi.md +++ b/guides/v2.2/cloud/project/project-routes-more-ssi.md @@ -6,9 +6,7 @@ functional_areas: - Setup --- -[Server side includes](http://httpd.apache.org/docs/current/howto/ssi.html){:target="_site"} (SSI) are directives in [HTML](https://glossary.magento.com/html) pages that get evaluated on the server while the pages are being rendered. Use of [server side](https://glossary.magento.com/server-side) includes enables you to add dynamically generated content to an existing HTML page without having to serve the entire page. - -More information about [nginx SSI](http://nginx.org/en/docs/http/ngx_http_ssi_module.html). +[Server side includes](http://nginx.org/en/docs/http/ngx_http_ssi_module.html) (SSI) are directives in [HTML](https://glossary.magento.com/html) pages that get evaluated on the server while the pages are being rendered. Use of [server side](https://glossary.magento.com/server-side) includes enables you to add dynamically generated content to an existing HTML page without having to serve the entire page. You can activate or deactivate SSI on a per-route basis in your `.magento/routes.yaml`; for example: diff --git a/guides/v2.3/cloud/project/project-conf-files_routes.md b/guides/v2.3/cloud/project/project-conf-files_routes.md index a93073d449a..d21620a2517 100644 --- a/guides/v2.3/cloud/project/project-conf-files_routes.md +++ b/guides/v2.3/cloud/project/project-conf-files_routes.md @@ -6,15 +6,15 @@ functional_areas: - Setup --- -{{site.data.var.ee}} processes an incoming URL using a *route*. The `routes.yaml` file—located at `.magento/routes.yaml` in your project—defines routes for the Integration environment. The deploy script uses values defined in the configuration files in the `.magento` directory and deletes the directory after deployment. Your local workspace is not affected. +The `routes.yaml` file in the `.magento/routes.yaml` directory defines routes for your {{ site.data.var.ece }} Integration, Staging, and Production environments. Routes determine how Magento processes incoming HTTP requests. -{% include cloud/note-pro-using-yaml-support.md %} +{% include cloud/note-pro-missing-self-service-options.md %} -The following is the default `routes.yaml` file: +The default `routes.yaml` file contains the following code: ```yaml "http://{default}/": - type: upstream + type: upstream upstream: "mymagento:php" ``` @@ -31,26 +31,58 @@ magento-cloud environment:routes | http://{default}/ | upstream | mymagento:php | +-------------------+----------+---------------+ ``` +{: .no-copy} ## Route templates -The `routes.yaml` file is a list of templated routes and their configurations. A route template looks similar to this: `http://www.{default}/` or `https://{default}/blog`, where `{default}` is the qualified domain name configured for the project. For example, the routes for `example.com` domain resolve to the following: +The `routes.yaml` file is a list of templated routes and their configurations. You can use the following placeholders in route templates: -- `http://www.example.com/` -- `https://example.com/blog` +- `{default}` represents the qualified domain name configured as the default for the project. For example, if you have a project with the default domain `example.com`, the route templates `http://www.{default}/` and `https://{default}/blog` resolve to the following URLs in a production environment: -{{site.data.var.ee}} also generates URLs for every active environment, so you can test that system. In a test system, `{default}` is replaced with the following: + ```text + http://www.example.com/ -``` + http://www.example.com/blog + ``` + {: .no-copy} + + In a non-production branch, the project ID and environment ID replace the `{default}` placeholder when the project is deployed. + +- `{all}` represents all the domain names configured for the project. For example, if you have a project with `example.com` and `example1.com` domains, the route templates `http://www.{all}/` and `https://{all}/blog` resolve to routes for all domains in the project: + + ```text + http://www.example.com/ + + http://www.example.com/blog + + http://www.example1.com/ + + http://www.example1.com/blog + ``` + {: .no-copy} + + The `{all}` placeholder is useful for projects configured for multiple domains. In a non-production branch `{all}` is replaced with the project ID and environment ID for each domain. + + If a project does not have any domains configured, which is common during development, the `{all}` placeholder behaves in the same way as the `{default}` placeholder. + +{{site.data.var.ee}} also generates URLs for every active environment, so you can test that system. In a test system, `{default}` is replaced with the following domain name: + +```text [branch]-[project-id].[region].magentosite.cloud ``` +{: .no-copy} + +For example, the `refactorcss` branch for the `mswy7hzcuhcjw` project hosted in the `us` cluster has the following the domains: -For example, if the project ID is `mswy7hzcuhcjw` on a branch called `refactorcss` hosted in the `us` cluster, the domains are: +```text +http://www-refactorcss-mswy7hzcuhcjw.us.magentosite.cloud/ -- `http://www-refactorcss-mswy7hzcuhcjw.us.magentosite.cloud/` -- `https://refactorcss-mswy7hzcuhcjw.us.magentosite.cloud/blog` +https://refactorcss-mswy7hzcuhcjw.us.magentosite.cloud/blog +``` + {: .no-copy} - +{:.bs-callout-info} +{{site.data.var.ece}} also supports [multiple applications]({{ page.baseurl }}/cloud/project/project-multi-sites.html) per project. Each project has a single `routes.yaml` file that defines which request is routed to which application. ## Route options @@ -64,10 +96,10 @@ Property | Description `redirects:` | Controls [redirect rules]({{ page.baseurl }}/cloud/project/project-routes-more-redir.html). `ssi:` | Controls enabling of [Server Side Includes]({{ page.baseurl }}/cloud/project/project-routes-more-ssi.html). - ## Simple routes -The following sample routes the apex domain and the `www` subdomain to the `frontend`application. This route does not redirect HTTPS: +The following sample routes the apex domain and the `www` subdomain to the `frontend`application. This route does not redirect HTTPS requests: + ```yaml "http://{default}/": @@ -119,10 +151,13 @@ If you examine the routes of this sample application, you see: ```bash echo $MAGENTO_CLOUD_RELATIONSHIPS | base64 --decode | json_pp ``` +{: .no-copy} ```terminal https://*.add-theme-projectID.us.magentosite.cloud/ ``` +{: .no-copy} + {: .bs-callout .bs-callout-info} Some projects provisioned before December 8, 2017, use the triple dash (\-\-\-) as a separator for the subdomain. diff --git a/guides/v2.3/cloud/project/project-routes-more-cache.md b/guides/v2.3/cloud/project/project-routes-more-cache.md index 0ad7a16a25b..668cb9644d2 100644 --- a/guides/v2.3/cloud/project/project-routes-more-cache.md +++ b/guides/v2.3/cloud/project/project-routes-more-cache.md @@ -8,6 +8,8 @@ functional_areas: {{site.data.var.ee}} enables you to use caching in your environment. If you disable caching, {{site.data.var.ee}} directly serves the files. +{% include cloud/note-route-all-placeholder.md %} + ## Set up caching {#cloud-cache-setup} Enable caching in your Magento application's `.magento/routes.yaml` as follows: diff --git a/guides/v2.3/cloud/project/project-routes-more-redir.md b/guides/v2.3/cloud/project/project-routes-more-redir.md index ac9052df44d..542f0a69f50 100644 --- a/guides/v2.3/cloud/project/project-routes-more-redir.md +++ b/guides/v2.3/cloud/project/project-routes-more-redir.md @@ -6,13 +6,15 @@ functional_areas: - Setup --- -Managing redirection rules is a common requirement for web applications, especially in cases where you do not want to lose incoming links that have changed or been removed over time. The following demonstrates how to manage redirection rules on your {{site.data.var.ece}} projects. +Managing redirection rules is a common requirement for web applications, especially in cases where you do not want to lose incoming links that have changed or been removed over time. -If the redirection methods discussed in this topic do not work for you, you can use caching headers to do the same thing. +The following demonstrates how to manage redirection rules on your {{site.data.var.ece}} projects using the `routes.yaml` configuration file. If the redirection methods discussed in this topic do not work for you, you can use caching headers to do the same thing. + +{% include cloud/note-route-all-placeholder.md %} ## Whole-route redirects {#cloud-route-whole} -Using whole-route redirects, you can define very basic routes using the `routes.yaml` file. For example, you can redirect from a naked domain to a `www` subdomain as follows: +Using whole-route redirects, you can define simple routes using the `routes.yaml` file. For example, you can redirect from an apex domain to a `www` subdomain as follows: ```yaml http://{default}/: @@ -20,128 +22,111 @@ http://{default}/: to: http://www.{default}/ ``` -## Partial redirects {#cloud-route-partial} +## Partial-route redirects {#cloud-route-partial} -In the [`.magento/routes.yaml`]({{ page.baseurl }}/cloud/project/project-conf-files_routes.html) file you can also add partial [redirect](https://glossary.magento.com/redirect) rules -to existing routes: +In the [`.magento/routes.yaml`]({{ page.baseurl }}/cloud/project/project-conf-files_routes.html) file, you can also add partial redirect rules to existing routes based on pattern matching: ```yaml http://{default}/: redirects: expires: 1d paths: - "/from": { "to": "http://example.com/" } - "/regexp/(.*)/matching": { "to": "http://example.com/$1", regexp: true } + "/from": { to: "http://example.com/" } + "/regexp/(.*)/matching": { to: "http://example.com/$1", regexp: true } ``` -This format is more rich and works with any type of route, including routes served directly by the application. +Partial redirects work with any type of route, including routes served directly by the application. Two keys are available under `redirects`: -- `expires`: Optional, the duration that the redirect is cached. - Examples of valid values include `3600s`, `1d`, `2w`, `3m`. - -- `paths`: The paths to apply the redirects to. - -The following defines each rule under `paths`: - -- A key that describes the expression to match against the request path -- A value object describing both the destination to redirect to with detail on how to handle the redirection. +- **expires**—Optional, specifies the amount of time to cache the redirect in the browser. Examples of valid values include `3600s`, `1d`, `2w`, `3m`. -The value object is defined with the following keys: +- **paths**—One or more key-value pairs that specify the configuration for partial-route redirect rules. -- [`to`](#cloud-route-partial-to) -- [`regexp`](#cloud-route-partial-regexp) -- [`prefix`](#cloud-route-partial-prefix) -- [`append_suffix`](#cloud-route-partial-append) -- [`code`](#cloud-route-partial-code) + For each redirect rule, the key is an expression to filter request paths for redirection. The value is an object that specifies the target destination for the redirect and options for processing the redirect. -### `to` {#cloud-route-partial-to} + The value object has the following properties: -Required, a partial (`"/destination"` or `"//destination"`) or full URL (`"http://example.com/"`). + Property | Description + ----------| ----------- + `to` | Required, a partial absolute path, URL with protocol and host, or pattern that specifies the target destination for the redirect rule. + `regexp`| Optional, defaults to `false`. Specifies whether the path key should be interpreted as a PCRE regular expression. + `prefix` | Specifies whether the redirect applies to both the path and all its children, or just the path itself. Defaults to `true`. This value is not supported if `regexp` is `true`. + `append_suffix`| Determines if the suffix is carried over with the redirect. Defaults to `true`. This value is not supported if the `regexp` key is `true` *or* if the `prefix` key is `false`. + `code` | Specifies the HTTP status code. Valid status codes are [`301` (Moved Permanently)](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2), [`302`](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3), [`307`](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8), and [`308`](https://tools.ietf.org/html/rfc7238). Defaults to `302`. + `expires`| Optional, specifies the amount of time to cache the redirect in the browser. Defaults to the `expires` value defined directly under the `redirects` key, but at this level you can fine-tune the cache expiration for individual partial redirects. -### `regexp` {#cloud-route-partial-regexp} +### Examples -Optional, defaults to `false`. Specifies whether the path key should be interpreted asa PCRE regular expression. +The following examples show how to specify partial-route redirects in the `routes.yaml` file using various `paths` configuration options. -{% collapsible Click to show/hide content %} +#### Regular expression pattern matching {#redirect-with-regex} -In the following example, a request to `http://example.com/regexp/a/b/c/match` redirects to `http://example.com/a/b/c`: +Use the following format to configure redirect requests based on a regular expression. ```yaml http://{default}/: type: upstream redirects: - paths: - "/regexp/(.*)/match": - to: "http://example.com/$1" - regexp: true + paths: + "/regexp/(.*)/match": { to: "http://example.com/$1", regexp: true } ``` -{% endcollapsible %} - -### `prefix` {#cloud-route-partial-prefix} -Specifies whether or not to redirect both the path and all its children or just the path itself. Defaults to `true`, but is not supported if `regexp` is `true`. +This configuration filters request paths against a regular expression and redirects matching requests to `https://example.com`. For example, a request to `https://example.com/regexp/a/b/c/match` redirects to `https://example.com/a/b/c`. -{% collapsible Click to show/hide content %} +#### Prefix pattern matching {#redirect-with-prefix} -For example, +Use the following format to configure redirect requests for paths that begin with a specified prefix pattern. ```yaml http://{default}/: type: upstream redirects: - paths: - "/from": - to: "http://{default}/to" - prefix: true + paths: + "/from": { to: "https://{default}/to", prefix: true } ``` -In the preceding example, if `prefix` is set to `true`, `/from` redirects to `/to` and `/from/another/path` will redirect to `/to/another/path` +This configuration works as follows: -If `prefix` is set to `false`, `/from` triggers a redirect, but `/from/another/path` does not. +- Redirects requests that match the pattern `/from` to the path `http://{default}/to`. -{% endcollapsible %} +- Redirects requests that match the pattern `/from/another/path` to `https://{default}/to/another/path`. -### `append_suffix` {#cloud-route-partial-append} -Determines if the suffix is carried over with the redirect. Defaults to `true`, but not supported if `regexp` is `true` *or* if `prefix` is `false`. +- If you change the `prefix` property to `false`, requests that match the pattern `/from` trigger a redirect, but requests that match the pattern `/from/another/path` does not. -{% collapsible Click to show/hide content %} +#### Suffix pattern matching {#redirect-with-suffix} -For example, +Use the following format to configure redirect requests which append the path suffix from the request to the target destination. ```yaml http://{default}/: type: upstream redirects: - paths: - "/from": - to: "http://{default}/to" - append_suffix: false + paths: { "/from": { to: "https://{default}/to", append_suffix: false } ``` -The preceding example results in `/from/path/suffix` redirecting to just `/to`. +This configuration works as follows: -If `append_suffix` is set to its default value of `true`, `/from/path/suffix` redirects to `/to/path/suffix`. +- Redirects requests that match the pattern `/from/path/suffix` to the path `https://{default}/to`. -{% endcollapsible %} +- If you change the `append_suffix` property to `true`, then requests that match `/from/path/suffix` redirect to the path `https://{default}/to/path/suffix`. -### `code` {#cloud-route-partial-code} +#### Path-specific cache configuration {#redirect-with-custom-cache} -Specifies the HTTP status code. Valid status codes are [`301` (Moved Permanently)](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2), [`302`](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3), [`307`](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8), and [`308`](https://tools.ietf.org/html/rfc7238). Defaults to `302`. - -### `expires` {#cloud-route-partial-expires} - -Optional, the duration to cache redirect. Defaults to the `expires` value defined directly under the `redirects` key, but at this level you can fine-tune the expiration of individual partial redirects: + Use the following format to customize the time to cache a redirect from a specific path: ```yaml http://{default}/: type: upstream redirects: - expires: 1d - paths: - "/from": { "to": "http://example.com/" } - "/here": { "to": "http://example.com/there", "expires": "2w" } -``` + expires: 1d + paths: + "/from": { to: "https://example.com/" } + "/here": { to: "https://example.com/there", expires: "2w" } + ``` + +This configuration works as follows: + +- Redirects from the first path (`/from`) are cached for 1 day. -In the preceding example, redirects from `/from` expire in one day, but redirects from `/here` expire in two weeks. +- Redirects from the second path (`/here`) are cached for 2 weeks. diff --git a/guides/v2.3/cloud/project/project-routes-more-ssi.md b/guides/v2.3/cloud/project/project-routes-more-ssi.md index e79bec190b2..e5210eb69ef 100644 --- a/guides/v2.3/cloud/project/project-routes-more-ssi.md +++ b/guides/v2.3/cloud/project/project-routes-more-ssi.md @@ -6,9 +6,7 @@ functional_areas: - Setup --- -[Server side includes](http://httpd.apache.org/docs/current/howto/ssi.html){:target="_site"} (SSI) are directives in [HTML](https://glossary.magento.com/html) pages that get evaluated on the server while the pages are being rendered. Use of [server side](https://glossary.magento.com/server-side) includes enables you to add dynamically generated content to an existing HTML page without having to serve the entire page. - -More information about [nginx SSI](http://nginx.org/en/docs/http/ngx_http_ssi_module.html). +[Server side includes](http://nginx.org/en/docs/http/ngx_http_ssi_module.html) (SSI) are directives in [HTML](https://glossary.magento.com/html) pages that get evaluated on the server while the pages are being rendered. Use of [server side](https://glossary.magento.com/server-side) includes enables you to add dynamically generated content to an existing HTML page without having to serve the entire page. You can activate or deactivate SSI on a per-route basis in your `.magento/routes.yaml`; for example: