From b9741c187b0228ca8f0827c25b5f98bd7c233c70 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Tue, 27 Jan 2026 09:56:07 +0300 Subject: [PATCH] feat: moving staging mode --- .gitbook.yaml | 1 + .../configurations/shopware/staging.md | 215 ---------------- .../creating-a-staging-instance.md | 234 ++++++++++++++++++ 3 files changed, 235 insertions(+), 215 deletions(-) delete mode 100644 guides/hosting/configurations/shopware/staging.md create mode 100644 guides/hosting/installation-updates/creating-a-staging-instance.md diff --git a/.gitbook.yaml b/.gitbook.yaml index 81ec21a93..e9e50e0fb 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -1,4 +1,5 @@ redirects: + guides/hosting/configurations/shopware/staging.html: guides/hosting/creating-a-staging-instance.html developers-guide/plugin-guidelines/: https://developers.shopware.com/developers-guide/plugin-guidelines/ guides/plugins/apps/platform-sh-template.html: guides/plugins/apps/app-base-guide.html guides/integrations-api/store-api-guide.html: guides/integrations-api/ diff --git a/guides/hosting/configurations/shopware/staging.md b/guides/hosting/configurations/shopware/staging.md deleted file mode 100644 index d767366cf..000000000 --- a/guides/hosting/configurations/shopware/staging.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -nav: - title: Staging - position: 10 - ---- - -# 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. - -## 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 the files. It only changes the data inside the Shopware instance. - -So, the real-world use case would be something like this: - -### Creating the second Shopware instance - -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. - -An alternative way would be to copy the files from the live environment to the staging environment. - -### Copying the database - -::: info -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 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](../../../../products/cli/installation) 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 anonymize 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`. This file allows you to specify tables that should be skipped, define additional fields for anonymization, and more. Check out the [CLI](../../../../products/cli/project-commands/mysql-dump) for more information. - -### Configuration - -::: info -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 - -After the database is imported and the configuration is done, you can activate the staging mode. This can be done using: - -```bash -./bin/console system:setup:staging -``` - -This command will modify the database to be used in a staging environment. You can pass `--no-interaction --force` to the command to avoid the interactive questions. - -### Protecting the staging environment - -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 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: - -```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/zero-trust/products/access/) -- [Azure Application Gateway](https://azure.microsoft.com/en-us/products/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 staging mode does? - -- 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 not? - -- Doesn't duplicate the current installation. -- Doesn't copy database or files. -- Doesn't modify the live environment. - -### Configuration - -The staging mode is fully configurable with `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 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`) - -```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. For example, `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, `https://my-live-store.com` will be replaced with `http://my-live-store.local`. - -### Usage of apps - -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 - -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: - -```php - 'onSetupStaging' - ]; - } - - public function onSetupStaging(SetupStagingEvent $event): void - { - // modify the database to turn on the test mode - } -} -``` diff --git a/guides/hosting/installation-updates/creating-a-staging-instance.md b/guides/hosting/installation-updates/creating-a-staging-instance.md new file mode 100644 index 000000000..d68bd3d9d --- /dev/null +++ b/guides/hosting/installation-updates/creating-a-staging-instance.md @@ -0,0 +1,234 @@ +--- +nav: + title: Creating a Staging Instance + position: 30 + +--- + +# Creating a Staging Instance + +This guide covers the complete workflow of creating a staging installation. + +## Overview + +Creating a staging environment allows you to test changes, updates, and new features without affecting your live shop. This process involves: + +1. Setting up a separate Shopware instance +2. Duplicating the database from your live environment +3. Configuring the staging instance +4. Activating staging mode to prepare the environment for testing + +## Creating the staging instance + +### Setting up the seperate Shopware installation + +The recommended way to create a staging instance is to deploy from your Git repository to the new environment. This ensures the codebase matches your live environment exactly. + +Alternatively, you can copy the files from the live environment to the staging environment. + +It's highly recommended to use a separate Domain or Subdomain for the staging instance to avoid conflicts with the live environment. After changing the domain, make sure you have updated `APP_URL` in the `.env` file to reflect the new URL. + +::: info +You should still use your **live domain** in Shopware Account > License Domain to avoid licensing issues. +::: + +### Copying the database + +To make your staging environment similar to the live environment, duplicate the database. + +::: info +Ensure that the `mysqldump` and `mysql` binaries are from the same major version and vendor. If you use `mysqldump` from MariaDB, use `mysql` from MariaDB. The same applies to MySQL. +::: + +We recommend using `shopware-cli project dump` to create a database dump and import it with the regular mysql command. The CLI also includes an anonymization flag to ensure no personal data is in the staging environment. + +::: info +`shopware-cli` is a separate Go command line application with many useful commands for Shopware. [Learn how to install it](../../../../products/cli/installation). +::: + +```bash +# Creating a regular dump (the clean parameter excludes cart table data) +shopware-cli project dump --clean --host localhost --username db_user --password db_pass --output shop.sql shopware + +# Creating a dump with anonymized data +shopware-cli project dump --clean --anonymize --host localhost --username db_user --password db_pass --output shop.sql shopware +``` + +Configure the dump command with `.shopware-project.yml` to specify tables to skip, additional anonymization fields, and more. See the [CLI documentation](../../../../products/cli/project-commands/mysql-dump) for details. + +## Configuring the staging instance + +::: info +Do not share resources like MySQL, Redis, or ElasticSearch/OpenSearch between live and staging environments. This can lead to data corruption and performance issues for your live environment. +::: + +After importing the database, modify the `.env` file to use the staging database. If you use ElasticSearch/OpenSearch, set a `SHOPWARE_ES_INDEX_PREFIX` to avoid conflicts with the live environment. + +::: warning +If you don't use the included Staging Mode, make sure to disable email sending in the staging environment to avoid sending test emails to real customers and that you reset the app system by deleting "core.app.shopId" from the `system_config` table to avoid leaks of data between live and staging environments. +::: + +## Setting up staging mode + +Staging mode prepares the Shopware instance for safe testing by modifying the database to prevent unintended operations on the live environment. + +### Activating staging mode + +After the database is imported and configured, activate staging mode: + +```bash +./bin/console system:setup:staging +``` + +This command modifies the database for staging use. Pass `--no-interaction --force` to avoid interactive questions. + +### What staging mode does + +The staging command makes the following changes to your instance: + +- Deletes all apps with active connections to external services and their integrations +- Resets the instance ID used for app registration +- Disables email sending +- Rewrites URLs to the staging domain (if configured) +- Verifies that ElasticSearch/OpenSearch indices do not exist +- Displays a banner in the administration and storefront to indicate staging mode + +### What staging mode does not do + +- Does not duplicate the current installation +- Does not copy the database or files +- Does not modify the live environment + +### Configuring staging mode + +Staging mode is fully configurable with `config/packages/staging.yaml`: + +```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 +``` + +### URL rewriting + +The `domain_rewrite` option allows you to rewrite URLs to the staging domain. This supports three methods: + +**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 +``` + +Compares Sales Channel URLs. When equal to `https://my-live-store.com`, it's replaced with `https://my-staging-store.com`. + +**Prefix replacement (`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 +``` + +Replaces URLs starting with `https://my-live-store.com`. For example, `https://my-live-store.com/en` becomes `https://my-staging-store.com/en`. + +**Regex replacement (`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 +``` + +Uses regular expressions for advanced URL rewriting. In this example, `https://my-live-store.com` becomes `http://my-live-store.local`. + +### App handling + +The staging command deletes all apps with active external connections to prevent data corruption or leaks in the live environment. Since the staging instance is a copy of the live environment, apps would retain their original connections. After executing the command, reinstall apps to create new instance IDs, making the app installation completely isolated from the live environment. + +## Protecting the staging environment + +Protect your staging environment from unauthorized access using password protection, IP restriction, or OAuth authentication. + +The simplest method uses `.htaccess` for Apache or `auth_basic` for Nginx. You can also use a firewall to restrict access based on IP addresses. + +**Apache example:** + +```apache +# /public/.htaccess +SetEnvIf Request_URI /api noauth=1 + +Require env noauth +Require env REDIRECT_noauth +Require valid-user + +``` + +Alternative application proxy solutions: + +- [Cloudflare Access](https://www.cloudflare.com/zero-trust/products/access/) +- [Azure Application Gateway](https://azure.microsoft.com/en-us/products/application-gateway/) +- [Generic oauth2 proxy](https://oauth2-proxy.github.io/oauth2-proxy/) + +## Integration into plugins + +The `system:setup:staging` command dispatches a `Shopware\Core\Maintenance\Staging\Event\SetupStagingEvent` event that plugins can subscribe to modify the database for staging mode. + +**Example subscriber for a payment provider:** + +```php + 'onSetupStaging' + ]; + } + + public function onSetupStaging(SetupStagingEvent $event): void + { + // modify the database to turn on the test mode + } +} +```