feat: move application yaml to own topic

products/paas/shopware/fundamentals/application_yaml.md

@@ -0,0 +1,122 @@
+---
+nav:
+  title: Application YAML
+  position: 80
+---
+
+# Application YAML Configuration
+
+The `application.yaml` file is the central configuration file for your Shopware PaaS Native application. It is placed at the root of your project repository and defines the PHP version, environment variables, and services for your application.
+
+When you update the `application.yaml` and push the changes to your repository, apply them by running:
+
+```sh
+sw-paas application update
+```
+
+## Structure
+
+The file consists of two main sections:
+
+| Section    | Description                                                  |
+|------------|--------------------------------------------------------------|
+| `app`      | Application settings such as PHP version and environment variables |
+| `services` | Infrastructure services like MySQL and OpenSearch             |
+
+## Minimal example
+
+```yaml
+app:
+  php:
+    version: "8.3"
+  environment_variables: []
+services:
+  mysql:
+    version: "8.0"
+  opensearch:
+    enabled: false
+```
+
+## Full example
+
+```yaml
+app:
+  php:
+    version: "8.3"
+  environment_variables:
+    - name: INSTALL_LOCALE
+      value: fr-FR
+      scope: RUN
+    - name: MY_BUILDTIME_VARIABLE
+      value: bar
+      scope: BUILD
+services:
+  mysql:
+    version: "8.0"
+  opensearch:
+    enabled: true
+```
+
+## Reference
+
+### `app.php.version`
+
+The PHP version used by the application.
+
+```yaml
+app:
+  php:
+    version: "8.3"
+```
+
+### `app.environment_variables`
+
+A list of environment variables passed to the application. Each entry requires:
+
+| Field   | Description                          | Values         |
+|---------|--------------------------------------|----------------|
+| `name`  | The variable name                    | Any string     |
+| `scope` | When the variable is available       | `RUN`, `BUILD` |
+| `value` | The variable value                   | Any string     |
+
+- **`RUN`** -- available at runtime (passed to the Shopware application).
+- **`BUILD`** -- available during the build step.
+
+You can define the same variable name with different scopes to use different values at build-time and runtime.
+
+```yaml
+app:
+  environment_variables:
+    - name: MY_VARIABLE
+      value: runtime-value
+      scope: RUN
+    - name: MY_VARIABLE
+      value: build-value
+      scope: BUILD
+```
+
+For sensitive values, use [secrets](./secrets.md) instead of environment variables.
+
+For more details, see the [Environment variables](./environment-variables.md) page.
+
+### `services.mysql`
+
+Configures the managed MySQL database.
+
+```yaml
+services:
+  mysql:
+    version: "8.0"
+```
+
+### `services.opensearch`
+
+Enables or disables the managed OpenSearch service.
+
+```yaml
+services:
+  opensearch:
+    enabled: true
+```
+
+After enabling OpenSearch, update your application and reindex your data. See [How to set up OpenSearch](../guides/opensearch.md) for the full steps.

products/paas/shopware/fundamentals/environment-variables.md

@@ -8,67 +8,48 @@
 
 This page explains how to configure environment variables in Shopware PaaS Native.
 
-Please only use this to configure non-sensitive environment variables. For sensitive variables, please use [secrets](./secrets.md). There is a detailed guide [here](../guides/secrets-vault-guide.md).
+## Sources
+
+There are three ways to define environment variables, listed here from lowest to highest priority:
+
+| Source                                          | Description                                      |
+|-------------------------------------------------|--------------------------------------------------|
+| `.env` file                                     | Committed to your repository, lowest priority    |
+| [`application.yaml`](./application_yaml.md)     | Defined in `app.environment_variables`            |
+| [Vault secrets](./secrets.md)                   | Created via `sw-paas vault create`, highest priority |
+
+When the same variable is defined in multiple sources, the higher-priority source wins. For example, a variable set in `application.yaml` overwrites the same variable from `.env`, and a vault secret overwrites both.
+
+Use the `.env` file for defaults, `application.yaml` for non-sensitive per-environment configuration, and vault secrets for sensitive values like passwords or API tokens. There is a detailed guide for secrets [here](../guides/secrets-vault-guide.md).
 
 ## Configure environment variables
 
-Environment variables are defined in the `application.yaml` file, in the following array `app.environment_variables`.
+Environment variables are defined in the `app.environment_variables` array of your [`application.yaml`](./application_yaml.md) file.
 
-Environment variables need to be scoped, they can be configured either for `RUN` or `BUILD`
+Each variable needs a `name`, `value`, and `scope`:
 
 | Scope      | Description                                           |
 |------------|-------------------------------------------------------|
 | `RUN`      | The value is passed to Shopware application (runtime) |
 | `BUILD`    | Build-time environment variables                      |
 
-Once the `application.yaml` is updated as usual, run the following:
+You can define the same variable name with different scopes to use different values at build-time and runtime.
+
+Once the `application.yaml` is updated, apply the changes:
 
 ```sh
 sw-paas application update
 ```
 
-## Configure an environment variable for runtime
-
-Update the `application.yaml` file like this:
-
-```yaml
-app:
-  environment_variables:
-    - name: MY_RUNTIME_VARIABLE
-      value: my-value
-      scope: RUN
-```
-
-## Configure an environment variable for build-time
-
-Update the `application.yaml` file like this:
+## Example
 
 ```yaml
 app:
-  environment_variables:
-    - name: MY_BUILDTIME_VARIABLE
-      value: my-value
-      scope: BUILD
-```
-
-## Complete example
-
-Here is a full example of environment variables. They can be used for both build-time and runtime, and you can have multiple variables with the same name but different scopes.
-
-```yaml
-app:
-  # ... Other application settings
   environment_variables:
     - name: MY_BUILDTIME_VARIABLE
       value: bar
       scope: BUILD
     - name: MY_RUNTIME_VARIABLE
       value: foo
       scope: RUN
-    - name: MY_VARIABLE_WITH_THE_SAME_NAME
-      value: my-value
-      scope: RUN
-    - name: MY_VARIABLE_WITH_THE_SAME_NAME
-      value: my-value
-      scope: BUILD
 ```

products/paas/shopware/get-started/prepare-codebase.md

@@ -66,9 +66,7 @@ This package installs essential configuration files, including those required fo
 
 ### Create the `application.yaml` File
 
-At the root of your project, create a file named `application.yaml`. This file defines key deployment parameters, such as the PHP version and any environment-specific configuration needed for your shop.
-
-#### Basic Example
+At the root of your project, create a file named `application.yaml`. This file defines key deployment parameters such as the PHP version, environment variables, and services for your shop.
 
 ```yaml
 app:
@@ -82,22 +80,7 @@ services:
     enabled: false
 ```
 
-#### Advanced Example (with Custom Environment Variables)
-
-```yaml
-app:
-  php:
-    version: "8.3"
-  environment_variables:
-    - name: INSTALL_LOCALE
-      value: fr-FR
-      scope: RUN # Supports RUN or BUILD
-services:
-  mysql:
-    version: "8.0"
-  opensearch:
-    enabled: false
-```
+For the full configuration reference, see the [Application YAML Configuration](../fundamentals/application_yaml.md) page.
 
 ## Hooks Configuration
 

products/paas/shopware/guides/opensearch.md

@@ -6,31 +6,14 @@ nav:
 
 ## Enable OpenSearch
 
-To use OpenSearch with your Shopware instance, add the `opensearch` service to your `application.yaml` file as follows:
+To use OpenSearch with your Shopware instance, set `services.opensearch.enabled` to `true` in your [`application.yaml`](../fundamentals/application_yaml.md) file:
 
 ```yaml
 services:
   opensearch:
     enabled: true
 ```
 
-A complete example would look like this:
-
-```yaml
-app:
-  php:
-    version: "8.3"
-  environment_variables:
-    - name: INSTALL_LOCALE
-      value: fr-FR
-      scope: RUN # Supports RUN or BUILD
-services:
-  mysql:
-    version: "8.0"
-  opensearch:
-    enabled: true
-```
-
 Once that is done, commit this change and push it to your git repository. Now you need to update your application, see [here](../fundamentals/applications.md#update-your-application).
 
 ## Post-enablement actions