From 9957e6359e6076da92c41c8329a729e5e9374497 Mon Sep 17 00:00:00 2001 From: Heather Guthrie Date: Thu, 15 Oct 2020 16:55:03 -0500 Subject: [PATCH 1/4] Fix issue #8021 update key value list for web locations --- src/cloud/project/magento-app-properties.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/src/cloud/project/magento-app-properties.md b/src/cloud/project/magento-app-properties.md index 0bc3e405050..938b818323c 100644 --- a/src/cloud/project/magento-app-properties.md +++ b/src/cloud/project/magento-app-properties.md @@ -75,18 +75,20 @@ See [Services]({{ site.baseurl }}/cloud/project/services.html) for a full list o The `web` property defines how your application is exposed to the web (in HTTP). It determines how the web application serves content— from the front-controller script to a non-static request to an `index.php` file on the root. We support any directory structure so the static file can be in a sub directory, and the `index.php` file can be further down. -You can specify the following attributes for the `web` property: +You can specify the following key values for the `web` property _locations_: Attribute | Description --------- | ----------- +`allow` | Serve files that do not match a rule. Default value = `true` +`blacklist` | Files that should never be served. Has no effect on static files. +`expires` | The number of seconds to cache `whitelist` content in the browser. This attribute enables the `cache-control` and `expires` headers for static content. If this value is not set, the `expires` directive and resulting headers are not included when serving static content files. +`index` | Static files to serve your application, such as the `index.html` file. This key expects a collection. You must include the static file(s) in the `whitelist` as an index file: `- \.html$` +`passthru` | The URL used in the event that a static file or PHP file cannot be found. Typically, this URL is the front controller for your applications, such as `/index.php` or `/app.php`. `root` | The path relative to the root of the application that is exposed on the web. Typical values include `/public` and `/web`. -`passthru` | The URL used in the event that a static file or PHP file cannot be found. This URL is typically the front controller for your applications, often `/index.php` or `/app.php`. -`index` | Static files, such as `index.html`, to serve your application. This key expects a collection. You must include the static file(s) in the whitelist as an index file, like `- \.html$`. -`blacklist` | A list of files that should never be executed. Has no effect on static files. -`whitelist` | A list of static files (as regular expressions) that can be served. Dynamic files (for example, PHP files) are treated as static files and have their source code served, but they are not executed. -`expires` | The number of seconds to cache whitelisted content in the browser. This attribute enables the cache-control and expires headers for static content. If this value is not set, the `expires` directive and resulting headers are not included when serving static content files. +`scripts` | Allow loading scripts in this location. Set the value to `true` to allow scripts. +`whitelist` | A list of static files that can be served. Dynamic files, such as PHP files, are treated as static files, where the source code is served and not run. -Contrary to standard `.htaccess` approaches that accept a _blacklist_ and allow access to everything not on a specific list, we accept a _whitelist_, which means that any request that does not match triggers a 404 error and passes through to the URL specified by the `passthru` attribute. +Contrary to standard `.htaccess` approaches that accept a _blacklist_ and allow access to everything not on a specific list, we accept a _whitelist_, which means that any request that does not match triggers a 404 error and passes through to the URL specified by the `passthru` attribute. Our default configuration allows the following: From d9627dad06e96de440e3153068a4d77f01f1df83 Mon Sep 17 00:00:00 2001 From: Heather Guthrie Date: Wed, 21 Oct 2020 12:23:29 -0500 Subject: [PATCH 2/4] Update magento-app-properties.md --- src/cloud/project/magento-app-properties.md | 26 ++++++++++++--------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/src/cloud/project/magento-app-properties.md b/src/cloud/project/magento-app-properties.md index 938b818323c..5178a99d7db 100644 --- a/src/cloud/project/magento-app-properties.md +++ b/src/cloud/project/magento-app-properties.md @@ -73,22 +73,26 @@ See [Services]({{ site.baseurl }}/cloud/project/services.html) for a full list o ### `web` -The `web` property defines how your application is exposed to the web (in HTTP). It determines how the web application serves content— from the front-controller script to a non-static request to an `index.php` file on the root. We support any directory structure so the static file can be in a sub directory, and the `index.php` file can be further down. +The `web` property defines how your application is exposed to the web (in HTTP), determines how the web application serves content, and controls how the application container responds to incoming requests by setting rules in each location _block_. A block represents an absolute path leading with a forward slash (`/`). -You can specify the following key values for the `web` property _locations_: +```yaml +web: + locations: + "/": + # The public directory of the app, relative to its root. +``` + +You can specify the following key values for each `locations` block: Attribute | Description --------- | ----------- -`allow` | Serve files that do not match a rule. Default value = `true` -`blacklist` | Files that should never be served. Has no effect on static files. -`expires` | The number of seconds to cache `whitelist` content in the browser. This attribute enables the `cache-control` and `expires` headers for static content. If this value is not set, the `expires` directive and resulting headers are not included when serving static content files. -`index` | Static files to serve your application, such as the `index.html` file. This key expects a collection. You must include the static file(s) in the `whitelist` as an index file: `- \.html$` -`passthru` | The URL used in the event that a static file or PHP file cannot be found. Typically, this URL is the front controller for your applications, such as `/index.php` or `/app.php`. -`root` | The path relative to the root of the application that is exposed on the web. Typical values include `/public` and `/web`. +`allow` | Serve files that do not match "rules". Default value = `true` +`expires` | Set the number of seconds to cache content in the browser. This key enables the `cache-control` and `expires` headers for static content. If this value is not set, the `expires` directive and resulting headers are not included when serving static content files. A negative 1 (`-1`) value results in no caching and is the default value. You can express time value with the following units: `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `M` (months, 30d), or `y` (years, 365d) +`index` | List the static files to serve your application, such as the `index.html` file. This key expects a collection. This only works if access to the file or files is "allowed" by the `allow` or `rules` key for this location. +`rules` | Specify overrides for a location. Use a regular expression to match a request. If an incoming request matches the rule, then regular handling of the request is overridden by the keys used in the rule. +`passthru` | Set the URL used in the event that a static file or PHP file cannot be found. Typically, this URL is the front controller for your applications, such as `/index.php` or `/app.php`. +`root` | Set the path relative to the root of the application that is exposed on the web. Typical values include `/public` and `/web`. `scripts` | Allow loading scripts in this location. Set the value to `true` to allow scripts. -`whitelist` | A list of static files that can be served. Dynamic files, such as PHP files, are treated as static files, where the source code is served and not run. - -Contrary to standard `.htaccess` approaches that accept a _blacklist_ and allow access to everything not on a specific list, we accept a _whitelist_, which means that any request that does not match triggers a 404 error and passes through to the URL specified by the `passthru` attribute. Our default configuration allows the following: From 135531317250581ad9340a63d2cc08d89fbe8d0d Mon Sep 17 00:00:00 2001 From: Heather Guthrie Date: Wed, 21 Oct 2020 12:38:32 -0500 Subject: [PATCH 3/4] fix table comment --- src/cloud/project/magento-app-properties.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/cloud/project/magento-app-properties.md b/src/cloud/project/magento-app-properties.md index 5178a99d7db..541eb8a1252 100644 --- a/src/cloud/project/magento-app-properties.md +++ b/src/cloud/project/magento-app-properties.md @@ -82,7 +82,7 @@ web: # The public directory of the app, relative to its root. ``` -You can specify the following key values for each `locations` block: +You can fine-tune your `locations` configuration using the following key values for each `locations` block: Attribute | Description --------- | ----------- From f49314c1806b5a1d64f17aa613be6ab2f7204be1 Mon Sep 17 00:00:00 2001 From: Heather Guthrie Date: Wed, 21 Oct 2020 14:10:50 -0500 Subject: [PATCH 4/4] Update from technical feedback --- src/cloud/project/magento-app-properties.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/cloud/project/magento-app-properties.md b/src/cloud/project/magento-app-properties.md index 541eb8a1252..e6fdf861e93 100644 --- a/src/cloud/project/magento-app-properties.md +++ b/src/cloud/project/magento-app-properties.md @@ -91,7 +91,7 @@ Attribute | Description `index` | List the static files to serve your application, such as the `index.html` file. This key expects a collection. This only works if access to the file or files is "allowed" by the `allow` or `rules` key for this location. `rules` | Specify overrides for a location. Use a regular expression to match a request. If an incoming request matches the rule, then regular handling of the request is overridden by the keys used in the rule. `passthru` | Set the URL used in the event that a static file or PHP file cannot be found. Typically, this URL is the front controller for your applications, such as `/index.php` or `/app.php`. -`root` | Set the path relative to the root of the application that is exposed on the web. Typical values include `/public` and `/web`. +`root` | Set the path relative to the root of the application that is exposed on the web. The public directory (location "/") for a Cloud project is set to "pub" by default. `scripts` | Allow loading scripts in this location. Set the value to `true` to allow scripts. Our default configuration allows the following: