From ec2cce196fcae79f5e94ef612ab232ebb6c17b0c Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Tue, 5 Mar 2024 14:28:47 +0100 Subject: [PATCH 1/9] NEXT-33729 - Add staging mode --- .../configurations/shopware/staging.md | 186 ++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 guides/hosting/configurations/shopware/staging.md diff --git a/guides/hosting/configurations/shopware/staging.md b/guides/hosting/configurations/shopware/staging.md new file mode 100644 index 0000000000..5d7e1f0d08 --- /dev/null +++ b/guides/hosting/configurations/shopware/staging.md @@ -0,0 +1,186 @@ +--- +nav: + title: Staging + position: 10 + +--- + +# Staging + +Since Shopware 6.6.1.0, Shopware has a integrated Staging Mode. This mode prepares the Shop to be used in a staging environment. This means that the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. + +## The workflow + +The staging mode is designed, to only modify data inside the Shopware instance. This means, the Staging mode does not duplicate the current Installation, copy Database or Files. It only modifies the data inside the Shopware instance. + +So the real world use-case would be kinda like this: + +### Creating the second Shopware instance + +The recommanded way would to deploy from your Git repository to the new environment. This way, you make sure that the codebase is equal to the live environment. The alternative way would be to copy the files from the live environment to the staging environment. + +### Copying the Database + +::: info +You should make sure that the `mysqldump` and the `mysql` binary is from the same major version and vendor. This means, if you use `mysqldump` from MariaDB, you should also use `mysql` from MariaDB. The same applies to MySQL. +::: + +To have the Staging environment similar as possible to the live environment, it's recommanded to duplicate the database. For this you can use the `mysqldump` command to export the database and import it into the staging environment. + +Our recommandation would be to use `shopware-cli project dump` to create a dump of the database and import it with the regular mysql command. Shopware cli does also have a flag to anonymize the data, so you can be sure that no personal data is in the staging environment. + +```bash +# creating a regular dump, the clean parameter will not dump the data of cart table +shopware-cli project dump --clean --host localhost --username db_user --password db_pass --output shop.sql shopware + +# create a dump with anonymized data +shopware-cli project dump --clean --anonymize --host localhost --username db_user --password db_pass --output shop.sql shopware +``` + +You can configure the dump command with a `.shopware-project.yml` which tables should be skipped, which additional fields should be anonymized and more. Checkout the [CLI documentation](https://sw-cli.fos.gg/commands/project/#shopware-cli-project-dump-database) for more information. + +### Configuration + +::: info +Generally it's not recommanded to share any resources like MySQL, Redis, ElasticSearch/OpenSearch between the live and staging environment. This could lead to data corruption when the configuration is not done correctly. Also the performance of the live environment could be affected by the staging environment. +::: + +After the database is imported, you should modify the `.env` to use the staging database. If you use ElasticSearch/OpenSearch, you should set a `SHOPWARE_ES_INDEX_PREFIX` to avoid conflicts with the live environment. + +### Activate the Staging Mode + +After the database is imported and the configuration is done, you can activate the Staging Mode. This can be done using the command `./bin/console system:setup:staging`. This command will modify the database to be used in a staging environment. You can pass `--no-interaction` to the command to avoid the interactive questions. + +## Staging Mode + +The Staging Mode is designed to be used in a test environment. This means, that the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. + +### What does the staging mode? + +The staging mode does the following: + +- Deletes all apps which have an active connection to an external service and the integrations in Shopware +- Reset the instance id used for registration of Apps +- It disables the sending of mails +- Rewrites the URLs to the staging domain (if configured) +- Checks that the ElasticSearch/OpenSearch indices are not existing yet +- Shows a banner in the administration and storefront to indicate that the shop is in staging mode + +### What does the staging mode not? + +The staging mode does not: + +- Duplicate the current Installation +- Copy Database or Files +- Modify the live environment + +### Configuration + +The staging mode is fully configureable with a `config/packages/staging.yaml`. You can configure the following options: + +```yaml +# /config/packages/staging.yaml +shopware: + staging: + mailing: + # Disables the sending of mails (default: true) + disable_delivery: true + storefront: + # Shows a banner in the storefront when staging mode is active (default: true) + show_banner: true + administration: + # Shows a banner in the administration when staging mode is active (default: true) + show_banner: true + sales_channel: + domain_rewrite: + # See below for more information + elasticsearch: + # Checks that no indices are existing yet (default: true) + check_for_existence: true +``` + +One of the most important options is the `domain_rewrite`. This option allows you to rewrite the URLs to the staging domain. This allows multiple ways to rewrite the URLs: + +Using direct match (`equal`) + +```yaml +# /config/packages/staging.yaml +shopware: + staging: + sales_channel: + domain_rewrite: + - type: equal + match: https://my-live-store.com + replace: https://my-staging-store.com + - # ... second rule +``` + +This goes and compares the Sales Channel URL and when it's equal to `https://my-live-store.com` it will be replaced with `https://my-staging-store.com`. + +Replace using prefix (`prefix`) + +```yaml +# /config/packages/staging.yaml +shopware: + staging: + sales_channel: + domain_rewrite: + - type: prefix + match: https://my-live-store.com + replace: https://my-staging-store.com + - # ... second rule +``` + +The difference here to the `equal` type is, that it will only replace the URL when it starts with `https://my-live-store.com`, so all paths to that beginning will be replaced. + +`https://my-live-store.com/en` will be replaced with `https://my-staging-store.com/en` + +Replace using regex (`regex`) + +```yaml +# /config/packages/staging.yaml +shopware: + staging: + sales_channel: + domain_rewrite: + - type: regex + match: '/https?:\/\/(\w+)\.(\w+)$/m' + replace: 'http://$1-$2.local' + - # ... second rule +``` + +This will use the regex to replace the URL. The match and replace are regular expressions. In this example a `https://my-live-store.com` will be replaced with `http://my-live-store.local`. + +### Usage of Apps + +The staging command will delete all apps which have an active connection to an external service and the integrations in Shopware. This means, that the apps are not available in the staging environment. This is done to avoid any data corruption or data leaks to the live environment. After the execution of the command, you can install the apps again in the staging environment. This will not affect the live environment, as the instance id is different. + +## Integration into Plugins + +The `system:setup:staging` is dispatching a Event which all plugins can subscribe to `Shopware\Core\Maintenance\Staging\Event\SetupStagingEvent` and modify the database for them to be in staging mode. + +Example of a subscriber for a payment provider to turn on the test mode: + +```php + 'onSetupStaging' + ]; + } + + public function onSetupStaging(SetupStagingEvent $event): void + { + // modify the database to turn on the test mode + } +} +``` + From b07edac40729bbe228db8516f97d4a432f1fac62 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Tue, 5 Mar 2024 15:29:54 +0100 Subject: [PATCH 2/9] fix a lot of typos --- .../configurations/shopware/staging.md | 46 +++++++++---------- 1 file changed, 22 insertions(+), 24 deletions(-) diff --git a/guides/hosting/configurations/shopware/staging.md b/guides/hosting/configurations/shopware/staging.md index 5d7e1f0d08..e89ae6b879 100644 --- a/guides/hosting/configurations/shopware/staging.md +++ b/guides/hosting/configurations/shopware/staging.md @@ -7,27 +7,25 @@ nav: # Staging -Since Shopware 6.6.1.0, Shopware has a integrated Staging Mode. This mode prepares the Shop to be used in a staging environment. This means that the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. +Since Shopware 6.6.1.0, Shopware has an integrated Staging Mode. This mode prepares the Shop to be used in a staging environment. This means the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. ## The workflow -The staging mode is designed, to only modify data inside the Shopware instance. This means, the Staging mode does not duplicate the current Installation, copy Database or Files. It only modifies the data inside the Shopware instance. +The staging mode is designed to modify data only inside the Shopware instance. This means the Staging mode does not duplicate the current Installation, copy the Database, or copy Files. It only changes the data inside the Shopware instance. -So the real world use-case would be kinda like this: +So, the real-world use case would be kind of like this: ### Creating the second Shopware instance -The recommanded way would to deploy from your Git repository to the new environment. This way, you make sure that the codebase is equal to the live environment. The alternative way would be to copy the files from the live environment to the staging environment. +The recommended way would be to deploy from your Git repository to the new environment. This way, you ensure the codebase is equal to the live environment. The alternative way would be to copy the files from the live environment to the staging environment. ### Copying the Database - ::: info -You should make sure that the `mysqldump` and the `mysql` binary is from the same major version and vendor. This means, if you use `mysqldump` from MariaDB, you should also use `mysql` from MariaDB. The same applies to MySQL. +You should ensure that the `mysqldump` and `mysql` binary are from the same major version and vendor. If you use `mysqldump` from MariaDB, you should also use `mysql` from MariaDB. The same applies to MySQL. ::: -To have the Staging environment similar as possible to the live environment, it's recommanded to duplicate the database. For this you can use the `mysqldump` command to export the database and import it into the staging environment. - -Our recommandation would be to use `shopware-cli project dump` to create a dump of the database and import it with the regular mysql command. Shopware cli does also have a flag to anonymize the data, so you can be sure that no personal data is in the staging environment. +To have the Staging environment similar as possible to the live environment, it's recommended to duplicate the database. You can use the `mysqldump` command to export the database and import it into the staging environment. +We recommend using `shopware-cli project dump` to create a dump of the database and import it with the regular mysql command. Shopware cli also has a flag to anonymize the data, so you can be sure that no personal data is in the staging environment. ```bash # creating a regular dump, the clean parameter will not dump the data of cart table @@ -37,15 +35,14 @@ shopware-cli project dump --clean --host localhost --username db_user --password shopware-cli project dump --clean --anonymize --host localhost --username db_user --password db_pass --output shop.sql shopware ``` -You can configure the dump command with a `.shopware-project.yml` which tables should be skipped, which additional fields should be anonymized and more. Checkout the [CLI documentation](https://sw-cli.fos.gg/commands/project/#shopware-cli-project-dump-database) for more information. +You can configure the dump command with a `.shopware-project.yml`, which tables should be skipped, which additional fields should be anonymized, and more. Check out the [CLI](https://sw-cli.fos.gg/commands/project/#shopware-cli-project-dump-database) for more information. ### Configuration - ::: info -Generally it's not recommanded to share any resources like MySQL, Redis, ElasticSearch/OpenSearch between the live and staging environment. This could lead to data corruption when the configuration is not done correctly. Also the performance of the live environment could be affected by the staging environment. +Generally, sharing resources like MySQL, Redis, ElasticSearch/OpenSearch between the live and staging environments is not recommended. This could lead to data corruption when the configuration is not done correctly. The staging environment could also affect the performance of the live environment. ::: -After the database is imported, you should modify the `.env` to use the staging database. If you use ElasticSearch/OpenSearch, you should set a `SHOPWARE_ES_INDEX_PREFIX` to avoid conflicts with the live environment. +After importing the database, you should modify the `.env` to use the staging database. If you use ElasticSearch/OpenSearch, you should set a `SHOPWARE_ES_INDEX_PREFIX` to avoid conflicts with the live environment. ### Activate the Staging Mode @@ -53,17 +50,17 @@ After the database is imported and the configuration is done, you can activate t ## Staging Mode -The Staging Mode is designed to be used in a test environment. This means, that the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. +The Staging Mode is designed to be used in a test environment. This means the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. -### What does the staging mode? +### What is the staging mode? The staging mode does the following: -- Deletes all apps which have an active connection to an external service and the integrations in Shopware -- Reset the instance id used for registration of Apps -- It disables the sending of mails +- Deletes all apps that have an active connection to an external service and the integrations in Shopware +- Resets the instance ID used for registration of Apps +- It turns off the sending of emails - Rewrites the URLs to the staging domain (if configured) -- Checks that the ElasticSearch/OpenSearch indices are not existing yet +- Checks that the ElasticSearch/OpenSearch indices do not existing yet - Shows a banner in the administration and storefront to indicate that the shop is in staging mode ### What does the staging mode not? @@ -76,7 +73,7 @@ The staging mode does not: ### Configuration -The staging mode is fully configureable with a `config/packages/staging.yaml`. You can configure the following options: +The staging mode is fully configurable with a `config/packages/staging.yaml`. You can configure the following options: ```yaml # /config/packages/staging.yaml @@ -103,6 +100,7 @@ One of the most important options is the `domain_rewrite`. This option allows yo Using direct match (`equal`) + ```yaml # /config/packages/staging.yaml shopware: @@ -115,7 +113,7 @@ shopware: - # ... second rule ``` -This goes and compares the Sales Channel URL and when it's equal to `https://my-live-store.com` it will be replaced with `https://my-staging-store.com`. +This compares the Sales Channel URL, and when it's equal to `https://my-live-store.com`, it will be replaced with `https://my-staging-store.com`. Replace using prefix (`prefix`) @@ -131,7 +129,7 @@ shopware: - # ... second rule ``` -The difference here to the `equal` type is, that it will only replace the URL when it starts with `https://my-live-store.com`, so all paths to that beginning will be replaced. +The difference here to the `equal` type is that it will only replace the URL when it starts with `https://my-live-store.com`, so all paths to that beginning will be replaced. `https://my-live-store.com/en` will be replaced with `https://my-staging-store.com/en` @@ -153,11 +151,11 @@ This will use the regex to replace the URL. The match and replace are regular ex ### Usage of Apps -The staging command will delete all apps which have an active connection to an external service and the integrations in Shopware. This means, that the apps are not available in the staging environment. This is done to avoid any data corruption or data leaks to the live environment. After the execution of the command, you can install the apps again in the staging environment. This will not affect the live environment, as the instance id is different. +The staging command will delete all apps that have an active connection to an external service and the integrations in Shopware. This means that the apps are not available in the staging environment. This is done to avoid data corruption or leaks to the live environment. After executing the command, you can install the apps again in the staging environment. This will not affect the live environment, as the instance id is different. ## Integration into Plugins -The `system:setup:staging` is dispatching a Event which all plugins can subscribe to `Shopware\Core\Maintenance\Staging\Event\SetupStagingEvent` and modify the database for them to be in staging mode. +The `system:setup:staging` is dispatching an Event which all plugins can subscribe to `Shopware\Core\Maintenance\Staging\Event\SetupStagingEvent` and modify the database to be in staging mode. Example of a subscriber for a payment provider to turn on the test mode: From 6d07e08c7b5310b35b78e0b0381db65358db2047 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Tue, 5 Mar 2024 15:55:32 +0100 Subject: [PATCH 3/9] add shopware-cli install info --- guides/hosting/configurations/shopware/staging.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/guides/hosting/configurations/shopware/staging.md b/guides/hosting/configurations/shopware/staging.md index e89ae6b879..50f6ab4c38 100644 --- a/guides/hosting/configurations/shopware/staging.md +++ b/guides/hosting/configurations/shopware/staging.md @@ -25,13 +25,18 @@ You should ensure that the `mysqldump` and `mysql` binary are from the same majo ::: To have the Staging environment similar as possible to the live environment, it's recommended to duplicate the database. You can use the `mysqldump` command to export the database and import it into the staging environment. + +::: info +`shopware-cli` is a separate Go command line application that contains a lot of useful commands for Shopware. [Checkout the docs](https://sw-cli.fos.gg/install/) to learn how to install it. +::: + We recommend using `shopware-cli project dump` to create a dump of the database and import it with the regular mysql command. Shopware cli also has a flag to anonymize the data, so you can be sure that no personal data is in the staging environment. ```bash # creating a regular dump, the clean parameter will not dump the data of cart table shopware-cli project dump --clean --host localhost --username db_user --password db_pass --output shop.sql shopware -# create a dump with anonymized data +# create a dump with anonymize data shopware-cli project dump --clean --anonymize --host localhost --username db_user --password db_pass --output shop.sql shopware ``` @@ -151,7 +156,7 @@ This will use the regex to replace the URL. The match and replace are regular ex ### Usage of Apps -The staging command will delete all apps that have an active connection to an external service and the integrations in Shopware. This means that the apps are not available in the staging environment. This is done to avoid data corruption or leaks to the live environment. After executing the command, you can install the apps again in the staging environment. This will not affect the live environment, as the instance id is different. +The staging command will delete all apps with an active connection to an external service. This will be done to avoid data corruption or leaks in the live environment, as the staging environment is a copy of the live environment, so they keep a connection. After executing the command, you can install the App again, creating a new instance ID so the app will think it's an entirely different shop. In that way, the app installation is completely isolated from the live environment. ## Integration into Plugins From 1a53ca61b2445ba297fc44e8b17000d259578031 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Tue, 5 Mar 2024 16:12:33 +0100 Subject: [PATCH 4/9] add info about protecting the webpage --- .../configurations/shopware/staging.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/guides/hosting/configurations/shopware/staging.md b/guides/hosting/configurations/shopware/staging.md index 50f6ab4c38..c883eac7a2 100644 --- a/guides/hosting/configurations/shopware/staging.md +++ b/guides/hosting/configurations/shopware/staging.md @@ -53,6 +53,30 @@ After importing the database, you should modify the `.env` to use the staging da After the database is imported and the configuration is done, you can activate the Staging Mode. This can be done using the command `./bin/console system:setup:staging`. This command will modify the database to be used in a staging environment. You can pass `--no-interaction` to the command to avoid the interactive questions. +### Protecting the Staging Environment + +The Staging environment should be protected from unauthorized access. It would help if you covered the staging environment with a password / IP restriction / oauth authentification. + +The simplest way to protect the staging environment is to use the `.htaccess` if you use Apache or `auth_basic` if you use Nginx. You can also use a firewall to restrict access to the staging environment based on IP addresses. + +Example configuration for Apache: + +```apache +# /public/.htaccess +SetEnvIf Request_URI /api noauth=1 + +Require env noauth +Require env REDIRECT_noauth +Require valid-user + +``` + +An alternative way could be to use an Application Proxy before the staging environment like: + +- [Cloudflare Access](https://www.cloudflare.com/teams/access/) +- [Azure Application Gateway](https://azure.microsoft.com/en-us/services/application-gateway/) +- [Generic oauth2 proxy](https://oauth2-proxy.github.io/oauth2-proxy/) + ## Staging Mode The Staging Mode is designed to be used in a test environment. This means the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. From 44d44d4190303c45d3cb2ea8f0d1fa95d5092452 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Tue, 5 Mar 2024 16:17:45 +0100 Subject: [PATCH 5/9] add words for typo checker --- .wordlist.txt | 3 +++ guides/hosting/configurations/shopware/staging.md | 4 ++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index 92bbb34400..16708e5116 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1633,3 +1633,6 @@ YYYY zlib zsh ZSH +anonymize +anonymized +Cloudflare \ No newline at end of file diff --git a/guides/hosting/configurations/shopware/staging.md b/guides/hosting/configurations/shopware/staging.md index c883eac7a2..42a0434f5d 100644 --- a/guides/hosting/configurations/shopware/staging.md +++ b/guides/hosting/configurations/shopware/staging.md @@ -44,7 +44,7 @@ You can configure the dump command with a `.shopware-project.yml`, which tables ### Configuration ::: info -Generally, sharing resources like MySQL, Redis, ElasticSearch/OpenSearch between the live and staging environments is not recommended. This could lead to data corruption when the configuration is not done correctly. The staging environment could also affect the performance of the live environment. +It's not recommended to share resources like MySQL, Redis, ElasticSearch/OpenSearch between the live and staging environments. This could lead to data corruption when the configuration is not done correctly. Also, the performance of the live environment could be affected by the staging environment. ::: After importing the database, you should modify the `.env` to use the staging database. If you use ElasticSearch/OpenSearch, you should set a `SHOPWARE_ES_INDEX_PREFIX` to avoid conflicts with the live environment. @@ -184,7 +184,7 @@ The staging command will delete all apps with an active connection to an externa ## Integration into Plugins -The `system:setup:staging` is dispatching an Event which all plugins can subscribe to `Shopware\Core\Maintenance\Staging\Event\SetupStagingEvent` and modify the database to be in staging mode. +The `system:setup:staging` is dispatching an Event which all plugins can subscribe to `Shopware\Core\Maintenance\Staging\Event\SetupStagingEvent` and modify the database for them to be in staging mode. Example of a subscriber for a payment provider to turn on the test mode: From be76389c5d1fccd1cd7173ee7fe9eef27bdf9ce6 Mon Sep 17 00:00:00 2001 From: Bojan Rajh <117360292+bojanrajh@users.noreply.github.com> Date: Thu, 7 Mar 2024 09:07:14 +0100 Subject: [PATCH 6/9] Apply suggestions from code review --- guides/hosting/configurations/shopware/staging.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guides/hosting/configurations/shopware/staging.md b/guides/hosting/configurations/shopware/staging.md index 42a0434f5d..44e64853aa 100644 --- a/guides/hosting/configurations/shopware/staging.md +++ b/guides/hosting/configurations/shopware/staging.md @@ -55,7 +55,7 @@ After the database is imported and the configuration is done, you can activate t ### Protecting the Staging Environment -The Staging environment should be protected from unauthorized access. It would help if you covered the staging environment with a password / IP restriction / oauth authentification. +The Staging environment should be protected from unauthorized access. It would help if you covered the staging environment with a password / IP restriction / oauth authentication. The simplest way to protect the staging environment is to use the `.htaccess` if you use Apache or `auth_basic` if you use Nginx. You can also use a firewall to restrict access to the staging environment based on IP addresses. @@ -89,7 +89,7 @@ The staging mode does the following: - Resets the instance ID used for registration of Apps - It turns off the sending of emails - Rewrites the URLs to the staging domain (if configured) -- Checks that the ElasticSearch/OpenSearch indices do not existing yet +- Checks that the ElasticSearch/OpenSearch indices do not exist yet - Shows a banner in the administration and storefront to indicate that the shop is in staging mode ### What does the staging mode not? @@ -180,7 +180,7 @@ This will use the regex to replace the URL. The match and replace are regular ex ### Usage of Apps -The staging command will delete all apps with an active connection to an external service. This will be done to avoid data corruption or leaks in the live environment, as the staging environment is a copy of the live environment, so they keep a connection. After executing the command, you can install the App again, creating a new instance ID so the app will think it's an entirely different shop. In that way, the app installation is completely isolated from the live environment. +The staging command will delete all apps with an active connection to an external service. This will be done to avoid data corruption or leaks in the live environment, as the staging environment is a copy of the live environment, so they keep a connection. After executing the command, you can install the App again, creating a new instance ID, so the app will think it's an entirely different shop. In that way, the app installation is completely isolated from the live environment. ## Integration into Plugins From ea97a7f1bb25268c0bcbb339c7e04eb8b8686348 Mon Sep 17 00:00:00 2001 From: su Date: Wed, 3 Apr 2024 15:52:12 +0200 Subject: [PATCH 7/9] Update text as per style guide --- .../configurations/shopware/staging.md | 87 ++++++++++--------- 1 file changed, 45 insertions(+), 42 deletions(-) diff --git a/guides/hosting/configurations/shopware/staging.md b/guides/hosting/configurations/shopware/staging.md index 44e64853aa..0628f7e387 100644 --- a/guides/hosting/configurations/shopware/staging.md +++ b/guides/hosting/configurations/shopware/staging.md @@ -7,24 +7,26 @@ nav: # Staging -Since Shopware 6.6.1.0, Shopware has an integrated Staging Mode. This mode prepares the Shop to be used in a staging environment. This means the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. +Since Shopware 6.6.1.0, Shopware has an integrated staging mode. This mode prepares the shop to be used in a staging environment. This means the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. ## The workflow -The staging mode is designed to modify data only inside the Shopware instance. This means the Staging mode does not duplicate the current Installation, copy the Database, or copy Files. It only changes the data inside the Shopware instance. +The staging mode is designed to modify data only inside the Shopware instance. This means the staging mode does not duplicate the current installation, copy the database, or copy the files. It only changes the data inside the Shopware instance. -So, the real-world use case would be kind of like this: +So, the real-world use case would be something like this: ### Creating the second Shopware instance -The recommended way would be to deploy from your Git repository to the new environment. This way, you ensure the codebase is equal to the live environment. The alternative way would be to copy the files from the live environment to the staging environment. +The recommended way to create a second Shopware instance would be to deploy from your Git repository to the new environment. This way, you ensure the codebase is equal to the live environment. -### Copying the Database +An alternative way would be to copy the files from the live environment to the staging environment. + +### Copying the database ::: info -You should ensure that the `mysqldump` and `mysql` binary are from the same major version and vendor. If you use `mysqldump` from MariaDB, you should also use `mysql` from MariaDB. The same applies to MySQL. +Ensure that the `mysqldump` and `mysql` binary are from the same major version and vendor. If you use `mysqldump` from MariaDB, you should also use `mysql` from MariaDB. The same applies to MySQL. ::: -To have the Staging environment similar as possible to the live environment, it's recommended to duplicate the database. You can use the `mysqldump` command to export the database and import it into the staging environment. +To have the staging environment similar to the live environment, it's recommended that the database be duplicated. You can use the `mysqldump` command to export the database and import it into the staging environment. ::: info `shopware-cli` is a separate Go command line application that contains a lot of useful commands for Shopware. [Checkout the docs](https://sw-cli.fos.gg/install/) to learn how to install it. @@ -40,24 +42,30 @@ shopware-cli project dump --clean --host localhost --username db_user --password shopware-cli project dump --clean --anonymize --host localhost --username db_user --password db_pass --output shop.sql shopware ``` -You can configure the dump command with a `.shopware-project.yml`, which tables should be skipped, which additional fields should be anonymized, and more. Check out the [CLI](https://sw-cli.fos.gg/commands/project/#shopware-cli-project-dump-database) for more information. +You can configure the dump command with a `.shopware-project.yml`. This file allows you to specify tables that should be skipped, define additional fields for anonymization, and more. Check out the [CLI](https://sw-cli.fos.gg/commands/project/#shopware-cli-project-dump-database) for more information. ### Configuration ::: info -It's not recommended to share resources like MySQL, Redis, ElasticSearch/OpenSearch between the live and staging environments. This could lead to data corruption when the configuration is not done correctly. Also, the performance of the live environment could be affected by the staging environment. +It is not recommended to share resources like MySQL, Redis, ElasticSearch/OpenSearch between the live and staging environments. This could lead to data corruption when the configuration is not done correctly. Also, the performance of the live environment could be affected by the staging environment. ::: After importing the database, you should modify the `.env` to use the staging database. If you use ElasticSearch/OpenSearch, you should set a `SHOPWARE_ES_INDEX_PREFIX` to avoid conflicts with the live environment. -### Activate the Staging Mode +### Activate the staging mode + +After the database is imported and the configuration is done, you can activate the staging mode. This can be done using: -After the database is imported and the configuration is done, you can activate the Staging Mode. This can be done using the command `./bin/console system:setup:staging`. This command will modify the database to be used in a staging environment. You can pass `--no-interaction` to the command to avoid the interactive questions. +```bash +./bin/console system:setup:staging +``` + +This command will modify the database to be used in a staging environment. You can pass `--no-interaction` to the command to avoid the interactive questions. -### Protecting the Staging Environment +### Protecting the staging environment -The Staging environment should be protected from unauthorized access. It would help if you covered the staging environment with a password / IP restriction / oauth authentication. +The staging environment should be protected from unauthorized access. It is advisable to employ protective measures like password protection, IP restriction, or OAuth authentication. -The simplest way to protect the staging environment is to use the `.htaccess` if you use Apache or `auth_basic` if you use Nginx. You can also use a firewall to restrict access to the staging environment based on IP addresses. +The simplest way to protect the staging environment is utilizing `.htaccess` for Apache or `auth_basic` for Nginx. You can also use a firewall to restrict access to the staging environment based on IP addresses. Example configuration for Apache: @@ -77,32 +85,29 @@ An alternative way could be to use an Application Proxy before the staging envir - [Azure Application Gateway](https://azure.microsoft.com/en-us/services/application-gateway/) - [Generic oauth2 proxy](https://oauth2-proxy.github.io/oauth2-proxy/) -## Staging Mode - -The Staging Mode is designed to be used in a test environment. This means the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. -### What is the staging mode? +## Staging mode -The staging mode does the following: +The staging mode is designed to be used in a test environment. This means the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. -- Deletes all apps that have an active connection to an external service and the integrations in Shopware -- Resets the instance ID used for registration of Apps -- It turns off the sending of emails -- Rewrites the URLs to the staging domain (if configured) -- Checks that the ElasticSearch/OpenSearch indices do not exist yet -- Shows a banner in the administration and storefront to indicate that the shop is in staging mode +### What staging mode does? -### What does the staging mode not? +- Deletes all apps that have an active connection to an external service and the integrations in Shopware. +- Resets the instance ID used for registration of apps. +- It turns off the sending of emails. +- Rewrites the URLs to the staging domain (if configured). +- Checks that the ElasticSearch/OpenSearch indices do not exist yet. +- Shows a banner in the administration and storefront to indicate that the shop is in staging mode. -The staging mode does not: +### What staging mode does not? -- Duplicate the current Installation -- Copy Database or Files -- Modify the live environment +- Does'nt duplicate the current installation. +- Does'nt copy database or files. +- Does'nt modify the live environment. ### Configuration -The staging mode is fully configurable with a `config/packages/staging.yaml`. You can configure the following options: +The staging mode is fully configurable with `config/packages/staging.yaml`. You can configure the following options: ```yaml # /config/packages/staging.yaml @@ -127,7 +132,7 @@ shopware: One of the most important options is the `domain_rewrite`. This option allows you to rewrite the URLs to the staging domain. This allows multiple ways to rewrite the URLs: -Using direct match (`equal`) +- Using direct match (`equal`) ```yaml @@ -142,9 +147,9 @@ shopware: - # ... second rule ``` -This compares the Sales Channel URL, and when it's equal to `https://my-live-store.com`, it will be replaced with `https://my-staging-store.com`. +This compares the Sales Channel URLs. When it's equal to `https://my-live-store.com`, it will be replaced with `https://my-staging-store.com`. -Replace using prefix (`prefix`) +- Replace using prefix (`prefix`) ```yaml # /config/packages/staging.yaml @@ -158,11 +163,9 @@ shopware: - # ... second rule ``` -The difference here to the `equal` type is that it will only replace the URL when it starts with `https://my-live-store.com`, so all paths to that beginning will be replaced. - -`https://my-live-store.com/en` will be replaced with `https://my-staging-store.com/en` +The difference here to the `equal` type is that it will only replace the URL when it starts with `https://my-live-store.com`, so all paths to that beginning will be replaced. For example, `https://my-live-store.com/en` will be replaced with `https://my-staging-store.com/en` -Replace using regex (`regex`) +- Replace using regex (`regex`) ```yaml # /config/packages/staging.yaml @@ -176,13 +179,13 @@ shopware: - # ... second rule ``` -This will use the regex to replace the URL. The match and replace are regular expressions. In this example a `https://my-live-store.com` will be replaced with `http://my-live-store.local`. +This will use the regex to replace the URL. The match and replace are regular expressions. In this example, `https://my-live-store.com` will be replaced with `http://my-live-store.local`. -### Usage of Apps +### Usage of apps -The staging command will delete all apps with an active connection to an external service. This will be done to avoid data corruption or leaks in the live environment, as the staging environment is a copy of the live environment, so they keep a connection. After executing the command, you can install the App again, creating a new instance ID, so the app will think it's an entirely different shop. In that way, the app installation is completely isolated from the live environment. +The staging command will delete all apps that have an active connection to an external service. This will be done to avoid data corruption or leaks in the live environment, as the staging environment is a copy of the live environment, so they keep a connection. After executing the command, you can install the app again, creating a new instance ID, so the app will think it's an entirely different shop. In this way, the app installation is completely isolated from the live environment. -## Integration into Plugins +## Integration into plugins The `system:setup:staging` is dispatching an Event which all plugins can subscribe to `Shopware\Core\Maintenance\Staging\Event\SetupStagingEvent` and modify the database for them to be in staging mode. From 289ec459a6fed7850b9c53bf4fa69cc5da5f86c4 Mon Sep 17 00:00:00 2001 From: su Date: Wed, 3 Apr 2024 15:52:17 +0200 Subject: [PATCH 8/9] Update test as per style guide --- .../hosting/performance/performance-tweaks.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/guides/hosting/performance/performance-tweaks.md b/guides/hosting/performance/performance-tweaks.md index 000e16767b..d182e851e4 100644 --- a/guides/hosting/performance/performance-tweaks.md +++ b/guides/hosting/performance/performance-tweaks.md @@ -7,7 +7,7 @@ nav: # Performance Tweaks -Shopware is a platform for many different projects. It needs to handle a broad range of load characteristics and environments. That means that the default configuration is optimized for the best out-of-the-box experience. But there are many opportunities to increase the performance by fitting the configuration to your needs. +Shopware is a platform for many different projects. It needs to handle a broad range of load characteristics and environments. It means that the default configuration is optimized for the best out-of-the-box experience. However, there are many opportunities to increase the performance by fitting the configuration to your needs. ## HTTP cache @@ -35,7 +35,7 @@ shopware: ### Delayed invalidation -A delay for the cache invalidation can be activated for systems with a high update frequency for the inventory (products, categories). Once the instruction to delete the cache entries for a specific product or category occurs, they are not deleted instantly but processed by a background task afterwards. Thus, if two processes invalidate the cache in quick succession, the timer for the invalidation of this cache entry will only reset. +A delay for cache invalidation can be activated for systems with a high update frequency for the inventory (products, categories). Once the instruction to delete the cache entries for a specific product or category occurs, they are not deleted instantly but processed by a background task later. Thus, if two processes invalidate the cache in quick succession, the timer for the invalidation of this cache entry will only reset. ```yaml # config/packages/prod/shopware.yaml @@ -64,7 +64,7 @@ and then you can set `SQL_SET_DEFAULT_SESSION_VARIABLES=0` to your `.env` file ## SQL is faster than DAL -We designed the DAL (Data Abstraction Layer) to provide developers a flexible and extensible data management. However, features in such a system come at the cost of performance. Therefore, using DBAL (plain SQL) is much faster than using the DAL in many scenarios, especially when it comes to internal processes, where often only one ID of an entity is needed. +DAL(Data Abstraction Layer) has been designed suitably to provide developers with a flexible and extensible data management. However, features in such a system come at the cost of performance. Therefore, using DBAL (plain SQL) is much faster than using the DAL in many scenarios, especially when it comes to internal processes, where often only one ID of an entity is needed. Refer to this article to know more on [when to use plain SQL and DAL](../../../resources/references/adr/2021-05-14-when-to-use-plain-sql-or-dal). @@ -93,7 +93,7 @@ shopware: update_mail_variables_on_send: false ``` -If you wonder, why it is in `prod`, have a look into the [Symfony configuration about configuration environments](https://symfony.com/doc/current/configuration.html#configuration-environments). +If you ever wonder why it is in `prod`, take a look into the [Symfony configuration environments](https://symfony.com/doc/current/configuration.html#configuration-environments). ## Increment storage @@ -115,7 +115,7 @@ shopware: url: 'redis://host:port/dbindex' ``` -If you don't need such functionality, it is highly recommended to disable this behavior by using `array` as a type. +If you don't need such functionality, it is highly recommended that you disable this behavior by using `array` as a type. ## Lock storage @@ -135,7 +135,7 @@ The generation of the number ranges is an **atomic** operation, which guarantees By default, the number range states are stored in the database. In scenarios where high throughput is required (e.g., thousands of orders per minute), the database can become a performance bottleneck because of the requirement for atomicity. -Redis offers better support for atomic increments than the database. Therefore the number ranges should be stored in Redis in such scenarios. +Redis offers better support for atomic increments than the database. Therefore, the number ranges should be stored in Redis in such scenarios. ```yaml # config/packages/prod/shopware.yaml @@ -163,14 +163,14 @@ framework: zend.assertions=-1 # cache file_exists,is_file -# WARNING: this will lead to thrown errors after clearing cache, while it tries to access cached Shopware_Core_KernelProdDebugContainer.php +# WARNING: this will lead to thrown errors after clearing cache while it tries to access cached Shopware_Core_KernelProdDebugContainer.php opcache.enable_file_override=1 # increase opcache string buffer as shopware has many files opcache.interned_strings_buffer=20 # disables opcache validation for timestamp for reinvalidation of the cache -# WARNING: you need to clear on deployments the opcache by reloadding php-fpm or cachetool (https://github.com/gordalina/cachetool) +# WARNING: you need to clear on deployments the opcache by reloading php-fpm or cachetool (https://github.com/gordalina/cachetool) opcache.validate_timestamps=0 # disable check for BOM @@ -190,7 +190,7 @@ For an additional 2-5% performance improvement, it is possible to provide a prel - Each cache clear requires a PHP-FPM restart - Each file change requires a PHP-FPM restart -- Extension Manager does not work +- The Extension Manager does not work The PHP configuration would look like: @@ -201,7 +201,7 @@ opcache.preload_user=nginx ## Cache ID -The Shopware cache has a global cache id to clear the cache faster and work in a cluster setup. This cache id is saved in the database and will only be changed when the cache is cleared. This ensures that the new cache is used and the message queue can clean the old folder. If this functionality is not used, this cache id can also be hardcoded `SHOPWARE_CACHE_ID=foo` in the `.env` to save one SQL query on each request. +The Shopware cache has a global cache ID to clear the cache faster and work in a cluster setup. This cache ID is saved in the database and will only be changed when the cache is cleared. This ensures that the new cache is used and the message queue can clean the old folder. If this functionality is not used, this cache ID can also be hardcoded `SHOPWARE_CACHE_ID=foo` in the `.env` to save one SQL query on each request. ## .env.local.php @@ -234,7 +234,7 @@ The `business_event_handler_buffer` handler logs flow. Setting it to `error` wil ## Disable App URL external check -On any Administration load Shopware tries to request himself to test that the configured `APP_URL` inside `.env` is correct. +On any Administration load, Shopware tries to request itself to test that the configured `APP_URL` inside `.env` is correct. If your `APP_URL` is correct, you can disable this behavior with an environment variable `APP_URL_CHECK_DISABLED=1`. ## Disable fine-grained caching From 0d8e117964fc1675898237aa9bf3c056f9c9ba3e Mon Sep 17 00:00:00 2001 From: su Date: Wed, 3 Apr 2024 15:57:51 +0200 Subject: [PATCH 9/9] Add spellings --- .wordlist.txt | 1 + guides/hosting/configurations/shopware/staging.md | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index 16708e5116..c9612d64fc 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -47,6 +47,7 @@ amqp AndRule antipattern Analytics +anonymization api ApiAware ApiController diff --git a/guides/hosting/configurations/shopware/staging.md b/guides/hosting/configurations/shopware/staging.md index 0628f7e387..de0349f40a 100644 --- a/guides/hosting/configurations/shopware/staging.md +++ b/guides/hosting/configurations/shopware/staging.md @@ -101,9 +101,9 @@ The staging mode is designed to be used in a test environment. This means the sh ### What staging mode does not? -- Does'nt duplicate the current installation. -- Does'nt copy database or files. -- Does'nt modify the live environment. +- Doesn't duplicate the current installation. +- Doesn't copy database or files. +- Doesn't modify the live environment. ### Configuration