IBX-4004 Upgrade doc for 4.1 missing Fastly VCL changes needed for shielding support (#1878)

Author: MagdalenaZuba

docs/snippets/update/vcl_configuration_for_fastly.md renamed to docs/snippets/update/vcl_configuration_for_fastly_v3.md

@@ -0,0 +1,14 @@
+If you use Fastly, deploy the most up-to-date VCL configuration.
+
+Locate the `vendor/ibexa/fastly/fastly/ez_main.vcl` file,
+make sure that it has been updated with the following changes, and upload it to your Fastly:
+
+- Add the following lines:
+
+``` vcl
+if (req.restarts == 0 && resp.status == 301 && req.http.x-fos-original-url) {
+    set resp.http.location = regsub(resp.http.location, "/_fos_user_context_hash", req.http.x-fos-original-url);
+}
+```
+
+- Move the `#FASTLY recv` macro call to a new location, right after the `Preserve X-Forwarded-For in all requests` section.

docs/snippets/update/vcl_configuration_for_fastly_v4.md

@@ -886,7 +886,7 @@ You do this manually by following this procedure:
 
 ###### VCL configuration for Fastly
 
-[[% include 'snippets/update/vcl_configuration_for_fastly.md' %]]
+[[% include 'snippets/update/vcl_configuration_for_fastly.md_v3' %]]
 
 ##### Optimize workflow queries
 

docs/updating/from_1.x_2.x/update_db_to_2.5.md

@@ -43,7 +43,7 @@ You do this manually by following this procedure:
 
 #### VCL configuration for Fastly
 
-[[% include 'snippets/update/vcl_configuration_for_fastly.md' %]]
+[[% include 'snippets/update/vcl_configuration_for_fastly.md_v3' %]]
 
 #### Optimize workflow queries
 

docs/updating/from_2.5/to_3.3.latest.md

@@ -109,7 +109,7 @@ You do this manually by following this procedure:
 
 #### VCL configuration for Fastly
 
-[[% include 'snippets/update/vcl_configuration_for_fastly.md' %]]
+[[% include 'snippets/update/vcl_configuration_for_fastly.md_v3' %]]
 
 #### Optimize workflow queries
 

docs/updating/from_3.3/update_from_3.3.md

@@ -94,7 +94,6 @@ Next, run:
 composer run post-install-cmd
 ```
 
-
 ### Update the database
 
 [[% include 'snippets/update/db/db_backup_warning.md' %]]
@@ -162,6 +161,20 @@ Apply the following database update scripts:
     psql <database_name> < vendor/ibexa/installer/upgrade/db/postgresql/ibexa-4.1.0-to-4.1.1.sql
     ```
 
+### v4.1.6
+
+#### VCL configuration for Fastly
+
+The Fastly `.vcl` configuration files have changed.
+Follow the upgrade steps below to update them:
+
+1. Locate the `vendor/ibexa/fastly/fastly/ez_main.vcl` file and update your VCL file with the recent changes.
+2. Do the same with `vendor/ibexa/fastly/fastly/ez_user_hash.vcl`.
+3. Upload a new `snippet_re_enable_shielding.vcl` snippet file, based on `vendor/ibexa/fastly/fastly/snippet_re_enable_shielding.vcl`.
+
+Once the VCL configuration has been updated,
+you may enable [Fastly Shielding](https://docs.fastly.com/en/guides/shielding) if you prefer.
+
 ## Configure the product catalog
 
 !!! caution

docs/updating/from_4.0/to_4.1.md

@@ -32,6 +32,20 @@ Run:
     composer require ibexa/commerce:[[= latest_tag_4_1 =]] --with-all-dependencies --no-scripts
     ```
 
+### VCL configuration for Fastly
+
+You can omit this step if you already performed it during update to v4.1.6.
+
+The Fastly `.vcl` configuration files have changed.
+Follow the upgrade steps below to update them:
+
+1. Locate the `vendor/ibexa/fastly/fastly/ez_main.vcl` file and update your VCL file with the recent changes.
+2. Do the same with `vendor/ibexa/fastly/fastly/ez_user_hash.vcl`.
+3. Upload a new `snippet_re_enable_shielding.vcl` snippet file, based on `vendor/ibexa/fastly/fastly/snippet_re_enable_shielding.vcl`.
+
+Once the VCL configuration has been updated,
+you may enable [Fastly Shielding](https://docs.fastly.com/en/guides/shielding) if you prefer.
+
 ## Update from v4.1.latest to v4.2
 
 When you have the latest version of v4.1, you can update to v4.2.
@@ -131,4 +145,4 @@ otherwise you can encounter errors during compiling.
 ``` bash
 rm -Rf node_modules
 rm -Rf yarn.lock
-```
+```