Merge origin/main into feat/cli-dev-environment-docs

Author: shyim

.wordlist.txt

@@ -143,6 +143,7 @@ CSP
 CSPs
 CSRF
 CSV
+CVEs
 CacheClearCommand
 CacheInvalidator
 CacheInvalidatorS
@@ -417,6 +418,7 @@ ExtensionAPI
 FLAC
 FPM
 FQCN
+FQDN
 FastRoute
 Fastly
 Fastly's
@@ -470,6 +472,7 @@ GoogleReCaptchaV
 Grafana
 Grantable
 GridHelper
+Grype
 GuestWishlistPage
 GuestWishlistPagelet
 HMAC
@@ -676,6 +679,7 @@ Nvidia
 OAuth
 OData
 OIDC
+OOM
 OPENSEARCH
 ORM
 ORMs
@@ -1059,6 +1063,7 @@ TreePath
 TreePathField
 TreeSelect
 TriggerReload
+Trivy
 TwigJS
 TypeDetector
 TypeError
@@ -1456,6 +1461,7 @@ eslintrc
 et
 eu
 everytime
+evictable
 evolvability
 exampler
 explainer

guides/hosting/index.md

@@ -8,6 +8,10 @@ nav:
 
 Setting up an operating environment for Shopware can be hard, but it doesn't have to be if you follow some general guidelines in the subsequent sections.
 
+:::info
+This page covers the recommended application stack and supported versions. For the physical machine requirements of your workstation or server, see the [system requirements](../installation/system-requirements.md) guide.
+:::
+
 ## Recommended stack and supported versions
 
 The following versions and configurations are officially supported for Shopware 6 development:

guides/hosting/infrastructure/rate-limiter.md

@@ -15,6 +15,31 @@ This functionality is available starting with Shopware 6.4.6.0.
 
 Shopware 6 provides certain rate limits by default that reduces the risk of brute-force attacks for pages like login or password reset.
 
+These rate limiters are always active. You do not need to add the `shopware.api.rate_limiter` map to your `shopware.yml` for them to work. The core already ships with the defaults documented below, and the `shopware.yml` is only used to override them (for example, to raise a limit or disable a limiter).
+
+## Default rate limiters
+
+The following limiters are enabled by default. The values listed here reflect the current Shopware core configuration and may change between versions. When in doubt, the source of truth is `src/Core/Framework/Resources/config/packages/shopware.yaml` in the version you are running.
+
+| Limiter                       | Protects                                                            | Since    | Policy           | Reset    | Limits                                                     |
+|-------------------------------|---------------------------------------------------------------------|----------|------------------|----------|------------------------------------------------------------|
+| `login`                       | Storefront / Store-API customer authentication                      | 6.4.6.0  | `time_backoff`   | 24 hours | 10 / 10s, 15 / 30s, 20 / 60s                               |
+| `guest_login`                 | Storefront / Store-API after-order guest authentication             | 6.4.6.0  | `time_backoff`   | 24 hours | 10 / 10s, 15 / 30s, 20 / 60s                               |
+| `oauth`                       | API OAuth authentication / Administration login                     | 6.4.6.0  | `time_backoff`   | 24 hours | 10 / 10s, 15 / 30s, 20 / 60s                               |
+| `reset_password`              | Storefront / Store-API customer password reset                      | 6.4.6.0  | `time_backoff`   | 24 hours | 3 / 30s, 5 / 60s, 10 / 90s                                 |
+| `user_recovery`               | Administration user password recovery                               | 6.4.6.0  | `time_backoff`   | 24 hours | 3 / 30s, 5 / 60s, 10 / 90s                                 |
+| `contact_form`                | Storefront / Store-API contact form                                 | 6.4.6.0  | `time_backoff`   | 24 hours | 3 / 30s, 5 / 60s, 10 / 90s                                 |
+| `notification`                | Store-API notification endpoint                                     | 6.4.8.0  | `time_backoff`   | 24 hours | 10 / 10s, 15 / 30s, 20 / 60s                               |
+| `newsletter_form`             | Store-API newsletter registration                                   | 6.4.16.0 | `time_backoff`   | 24 hours | 3 / 30s, 5 / 60s, 10 / 90s                                 |
+| `cart_add_line_item`          | Adding line items to the cart                                       | 6.4.18.0 | `system_config`  | 1 hour   | Limit read from `core.cart.lineItemAddLimit`, interval 60s |
+| `revocation_request_form`     | Store-API revocation request form                                   | 6.7.9.0  | `time_backoff`   | 24 hours | 3 / 30s, 5 / 60s, 10 / 90s                                 |
+| `newsletter_unsubscribe_form` | Store-API newsletter unsubscribe                                    | 6.7.9.0  | `time_backoff`   | 24 hours | 3 / 30s, 5 / 60s, 10 / 90s                                 |
+| `app_shop_verify`             | App shop registration verification                                  | 6.7.9.0  | `sliding_window` | n/a      | 60 / 60min                                                 |
+| `mcp_admin_api`               | MCP server Admin API access (keyed per OAuth token)                 | 6.8.0.0  | `time_backoff`   | 1 hour   | 300 / 60s, 1000 / 10min                                    |
+| `mcp_store_api`               | MCP server Store API access (keyed per sales-channel context token) | 6.8.0.0  | `time_backoff`   | 1 hour   | 120 / 60s, 600 / 10min                                     |
+
+In the table above, `Limits` uses the `limit / interval` notation, and `s` / `min` are seconds / minutes. When you add a new default limiter to the core, add a row here with its introduction version so this table stays complete.
+
 ## Configuration
 
 The configuration for the rate limiter of Shopware 6 resides in the general bundle configuration:
@@ -26,19 +51,13 @@ The configuration for the rate limiter of Shopware 6 resides in the general bund
       └── shopware.yml
 ```
 
-To configure the default rate limiters for your shop, you need to add the `shopware.api.rate_limiter` map to the `shopware.yml`. Under this key, you can separately define the rate limiters.
+To override the [default rate limiters](#default-rate-limiters) for your shop, you need to add the `shopware.api.rate_limiter` map to the `shopware.yml`. Under this key, you can separately define each rate limiter. Any key you set is merged into the defaults, so you only need to configure the values you want to change.
 
-In the following, you can find a list of the default limiters:
+The following example disables the `login` limiter and overrides the `oauth` limiter:
 
-- `login`: Storefront / Store-API customer authentication.
-- `guest_login`: Storefront / Store-API after order guest authentication.
-- `oauth`: API oauth authentication / Administration login.
-- `reset_password`: Storefront / Store-API customer password reset.
-- `user_recovery`: Administration user password recovery.
-- `contact_form`: Storefront / Store-API contact form.
+::: code-group
 
-```yaml
-// <shop root>/config/packages/shopware.yaml
+```yaml [SHOP_ROOT/config/packages/shopware.yaml]
 shopware:
   api:
     rate_limiter:
@@ -55,6 +74,8 @@ shopware:
             interval: '60 seconds'
 ```
 
+:::
+
 ::: info
 The following optional limiters are available starting with Shopware 6.7.10.0.
 :::
@@ -70,8 +91,9 @@ The `time_backoff` policy is built by Shopware itself. It enables you to throttl
 Below you can find an example which throttles the request for 10 seconds after 3 requests and starting from 5 requests it always
 throttles for 60 seconds. If there are no more requests, it will be reset after 24 hours.
 
-```yaml
-// <plugin root>/src/Resources/config/rate_limiter.yaml
+::: code-group
+
+```yaml [PLUGIN_ROOT/src/Resources/config/rate_limiter.yaml]
 example_route:
     enabled: true
     policy: 'time_backoff'
@@ -82,3 +104,5 @@ example_route:
         - limit: 5
           interval: '60 seconds'
 ```
+
+:::

guides/hosting/infrastructure/redis.md

@@ -7,7 +7,7 @@ nav:
 
 # Redis
 
-[Redis](https://redis.io/docs/latest/get-started/) is an in-memory data storage, that offers high performance and can be used as a cache, message broker, and database. It is a key-value store that supports various data structures like strings, hashes, lists, sets, and sorted sets.
+[Redis](https://redis.io/docs/latest/get-started/) is an in-memory data storage that offers high performance and can be used as a cache, message broker, and database. It is a key-value store that supports various data structures like strings, hashes, lists, sets, and sorted sets.
 Especially in high-performance and high-throughput scenarios it can give better results, than relying on a traditional relational database.
 Therefore, multiple adapter exists in shopware, to offload some tasks from the DB to Redis.
 
@@ -16,8 +16,8 @@ However, as the data that is stored in Redis differs and also the access pattern
 The data stored in Redis can be roughly classified into those three categories:
 
 1. Ephemeral data: This data is not critical and can be easily recreated when lost, e.g., caches.
-2. Durable, but "aging" data: This data is important and cannot easily be recreated, but the relevance of the data decreases over time, e.g. sessions.
-3. Durable and critical data: This data is important and cannot easily be recreated, e.g. carts, number ranges.
+2. Durable, but "aging" data: This data is important and cannot easily be recreated, but the relevance of the data decreases over time, e.g., sessions.
+3. Durable and critical data: This data is important and cannot easily be recreated, e.g., carts, number ranges.
 
 Please note that in current Redis versions, it is not possible to use different eviction policies for different databases in the same Redis instance. Therefore, it is recommended to use separate Redis instances for different types of data.
 
@@ -30,29 +30,33 @@ For key eviction policy you should use `volatile-lru`, which only automatically
 
 The caching data (HTTP-Cache & Object cache) is what should be stored in this instance.
 
+::: warning
+A cache Redis reaching its memory limit is normal — `volatile-lru` keeps evicting least recently used keys that have a TTL set to make room. The problem is having too many keys **without** a TTL: `volatile-lru` can only evict keys that have one. Symfony's tag-aware cache adapter stores tag-index sets without a TTL, and they accumulate orphaned entries over time. If they are never pruned, they leave Redis with too little evictable data, and it runs out of memory. See [Cache tags and keys without a TTL](../performance/caches#cache-tags-and-keys-without-a-ttl) for how to detect and prune them.
+:::
+
 <PageRef page="../performance/caches" />
 
 ## Durable, but "aging" data
 
-As the data stored here is durable and should be persistent, even in the case of a Redis restart, it is recommended to configure the used Redis instance that it will not just keep the data in memory, but also store it on the disk. This can be done by using snapshots (RDB) and Append Only Files (AOF), refer to the [Redis docs](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) for details.
+As the data stored here is durable and should be persistent, even in the case of a Redis restart, it is recommended to configure the used Redis instance that it will not just keep the data in memory but also store it on the disk. This can be done by using snapshots (RDB) and Append Only Files (AOF), refer to the [Redis docs](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) for details.
 
-`allkeys-lru` should be used as key eviction policy here, as by default more recent data is more important than older data, therefore the oldest values should be discarded, when Redis reach the max memory.
+`allkeys-lru` should be used as key eviction policy here, as by default more recent data is more important than older data, therefore, the oldest values should be discarded, when Redis reach the max memory.
 
 The session data is what should be stored in this instance.
 
 <PageRef page="../performance/session" />
 
 ## Durable and critical data
 
-Again this is durable data, that can not easily be recreated, therefore it should be persisted as well.
+Again, this is durable data that cannot easily be recreated, therefore, it should be persisted as well.
 
 As the data is critical, it is important to use a key eviction policy that will not delete data that is not expired, therefore `volatile-lru` should be used.
 
-The cart, number range, lock store and increment data is what should be stored in this instance.
+The cart, number range, lock store, and increment data are what should be stored in this instance.
 
 ## Configuration
 
-Starting with v6.6.8.0 Shopware supports configuring different reusable Redis connections in the`config/packages/shopware.yaml` file under the `shopware` section:
+Starting with v6.6.8.0, Shopware supports configuring different reusable Redis connections in the`config/packages/shopware.yaml` file under the `shopware` section:
 
 ```yaml
 shopware:

guides/hosting/installation-updates/deployments/build-w-o-db.md

@@ -1,11 +1,11 @@
 ---
 nav:
   title: Building Without Database
-  position: 20
+  position: 25
 
 ---
 
-# Building Assets of Administration and Storefront without a Database
+# Building Administration and Storefront Assets Without a Database
 
 It is common to prebuild assets in professional deployments to deploy the build artifact assets to the production environment. This task is mostly done by a CI job that doesn't have access to the production database. Shopware needs access to the database to look up the installed extensions/load the configured theme variables. To be able to build the assets without a database, we can use static dumped files. All extensions need to be required by Composer to be able to be loaded by the `ComposerPluginLoader`.
 

guides/hosting/installation-updates/deployments/deployment-helper-troubleshooting.md

@@ -0,0 +1,106 @@
+---
+nav:
+  title: Deployment Helper Troubleshooting
+  position: 20
+
+---
+
+# Deployment Helper Troubleshooting
+
+This page highlights common failures when running `vendor/bin/shopware-deployment-helper run`, and provides guidance for resolving them. For the full command, configuration, and environment-variable reference, see [Deployment Helper](deployment-helper.md).
+
+## Getting more detail
+
+`run` returns a non-zero exit code on failure and prints each step's output. Read the output above the failure to find the failing command, and re-run that Shopware console command directly (for example, `bin/console system:update:finish`) to see its full error.
+
+## The deploy fails to reach the database
+
+**Symptom:** the run ends with a database connection error, or `Could not connect to database`.
+
+The helper waits for the database, retrying up to 10 times with a one-second pause between attempts. If it still cannot connect, it fails.
+
+Check if:
+
+- `DATABASE_URL` is correct and reachable from the deploy environment (host, port, credentials).
+- the database service is actually up before the helper runs. In container setups, order startup so the database is ready, or add your own wait.
+- TLS is required, and `DATABASE_SSL_CA` / `DATABASE_SSL_CERT` / `DATABASE_SSL_KEY` are set. To bypass server-certificate verification (non-production only), set `DATABASE_SSL_DONT_VERIFY_SERVER_CERT`. See [Environment variables](deployment-helper.md#environment-variables).
+
+## A step times out on a large shop
+
+**Symptom:** a step is killed after 300 seconds.
+
+Each step has a timeout (default 300s). Raise or disable it:
+
+```bash
+vendor/bin/shopware-deployment-helper run --timeout=900
+# or disable entirely:
+vendor/bin/shopware-deployment-helper run --timeout=null
+```
+
+You can also set `SHOPWARE_DEPLOYMENT_TIMEOUT` in the environment. The `--timeout` option takes precedence.
+
+## Theme and assets were not pre-built in CI/CD
+
+The deployment artifact must already contain the compiled theme and installed assets. In CI/CD, build the artifact with `shopware-cli project ci` and deploy that output.
+
+At deploy time, run Deployment Helper with the theme and asset steps skipped so it only consumes the pre-built artifact:
+
+```bash
+vendor/bin/shopware-deployment-helper run --skip-theme-compile --skip-assets-install
+```
+
+If the Storefront is missing assets after deployment, fix the CI build artifact or upload step. Do not compensate by compiling the theme or installing assets during deployment.
+
+## An update ran, but `system:update:finish` did not
+
+This is expected. The update-finish/migration step runs only when the Shopware version actually changed. If you redeploy the same version, that step is skipped by design. To force it, deploy an actual version change.
+
+## A one-time task keeps running every deploy
+
+A one-time task is only recorded as done after it succeeds. If it keeps running, it is failing partway through. Check the deploy output for its error:
+
+- Inspect state: `one-time-task:list`.
+- If the task's effect is already applied and you want to stop it: `one-time-task:mark <id>`.
+- To force a rerun: `one-time-task:unmark <id>`.
+
+## A config setting seems to have no effect
+
+Deployment Helper provides a configuration schema for `.shopware-project.yml`. Use it in your editor to validate the file while editing, so misspelled or misplaced keys are reported before deployment.
+
+Check if:
+
+- Your editor is using the schema and does not report any validation errors.
+- The key is nested under the correct section, for example `deployment:`.
+- You are editing the file the helper actually loads. If `SHOPWARE_PROJECT_CONFIG_FILE` or `--project-config` is set, that file wins over the auto-discovered one.
+- A `.shopware-project.local.yml` is overriding your value. Local files merge on top of the base file. See [Local configuration overrides](deployment-helper.md#local-configuration-overrides).
+
+## Extensions aren't being installed or updated as expected
+
+- Confirm `deployment.extension-management.enabled` is `true`.
+- Check the extension isn't listed under `exclude`, or set to `state: ignore` / `inactive` in `overrides`.
+- If extensions are managed by the Store or Administration instead, extension management may be intentionally disabled — reconcile the two so they don't fight. Prefer managing extensions from code (via Composer) or via the helper, not both. See [Extension management and Store-installed plugins](deployment-helper.md#extension-management-and-store-installed-plugins).
+
+## Store login or license refresh fails
+
+App installation and license refresh need valid Store credentials and a license domain. Verify:
+
+- `SHOPWARE_STORE_ACCOUNT_EMAIL` and `SHOPWARE_STORE_ACCOUNT_PASSWORD` (or `SHOPWARE_STORE_SHOP_SECRET`) are set.
+- A license domain is set, via `deployment.store.license-domain` or `SHOPWARE_STORE_LICENSE_DOMAIN`.
+
+## Fastly snippets aren't updating
+
+Automatic snippet deployment during `run` only happens when:
+
+- A `config/fastly` directory exists in the project, and
+- `FASTLY_API_TOKEN` and `FASTLY_SERVICE_ID` are set, and
+- `FASTLY_DISABLE_SNIPPET_UPDATE` is **not** set to `1`.
+
+To manage snippets manually, use the `fastly:snippet:*` commands. See [Fastly integration](deployment-helper.md#fastly-integration).
+
+## Need to completely reinstall
+
+If an environment is broken beyond repair, force a clean `install` from scratch.
+
+:::warning
+Setting `SHOPWARE_DEPLOYMENT_FORCE_REINSTALL=1` triggers a fresh `install` with `--drop-database`. This destroys existing data! Only use it in disposable environments, never in production.
+:::