From 2595b439c456e754953f9e9129f90f139cf40ff1 Mon Sep 17 00:00:00 2001 From: Andrei Adam Date: Fri, 23 Jan 2026 16:24:43 +0200 Subject: [PATCH 01/11] feat: extend pass vault guide for secrets --- .../shopware/guides/secrets-vault-guide.md | 206 ++++++++++++++++++ 1 file changed, 206 insertions(+) diff --git a/products/paas/shopware/guides/secrets-vault-guide.md b/products/paas/shopware/guides/secrets-vault-guide.md index cdfb66f3a..10e0dafb7 100644 --- a/products/paas/shopware/guides/secrets-vault-guide.md +++ b/products/paas/shopware/guides/secrets-vault-guide.md @@ -101,3 +101,209 @@ sw-paas vault get --secret-id ssh-abc123xyz ```sh sw-paas vault delete --secret-id ssh-abc123xyz ``` + +## Default Secrets & Ownership + +The Shopware PaaS Vault contains both system-managed and user-managed secrets. Understanding the difference helps you identify which secrets you can manage and which are maintained by the platform. + +### System-Managed vs. User-Managed Secrets + +**System-managed secrets** are automatically created and maintained by Shopware PaaS for internal operations. While these secrets are visible when you run `sw-paas vault list`, they should not be modified or deleted as they are critical for platform functionality. + +**User-managed secrets** are created by you for your application's specific needs, such as API tokens, database credentials, or SSH keys for private repositories. + +### Common Secrets Reference + +| Secret Name | Description | Managed By | Editable by User | Notes | +|-------------|-------------|------------|------------------|-------| +| `STOREFRONT_CREDENTIALS` | Internal storefront credentials | System | No | **Do not delete** - Required for storefront functionality | +| `GRAFANA_CREDENTIALS` | Grafana dashboard login credentials | System | No | **Do not delete** - Needed for `sw-paas open grafana` | +| `NATS_USER_CREDENTIALS` | NATS messaging user credentials | System | No | **Do not delete** - Required for internal messaging | +| `STOREFRONT_PROXY_KEY` | Storefront proxy authentication | System | No | **Do not delete** - Required for routing | +| `SSH_PRIVATE_KEY` | Deploy SSH key for repository access | User | Yes | See [SSH key workflow](#example-workflow-using-ssh-keys) | +| `SHOPWARE_PACKAGES_TOKEN` | Token for accessing Shopware packages | User | Yes | Check for legacy typos (e.g., `SHOPWAREPACKAGES_TOKEN`) | +| Custom `env` secrets | Application-specific environment variables | User | Yes | Created via `sw-paas vault create --type env` | +| Custom `buildenv` secrets | Build-time environment variables | User | Yes | Created via `sw-paas vault create --type buildenv` | + +::: info +System-managed secrets use the same retrieval mechanism as user-managed secrets, which is why they appear in your vault list. This is intentional to provide transparency into the credentials your environment is using. +::: + +### Filtering Secrets by Application + +By default, `sw-paas vault list` shows secrets across all applications in your organization, which can lead to duplicate entries if multiple apps use the same secret names. + +To view secrets for a specific application: + +```sh +sw-paas vault list --application-id YOUR-APP-ID +``` + +To find your application ID: + +```sh +sw-paas application list +``` + +## Permissions & Behavior + +::: danger +**Do not delete system-managed secrets.** Deleting secrets like `STOREFRONT_CREDENTIALS`, `GRAFANA_CREDENTIALS`, `NATS_USER_CREDENTIALS`, or `STOREFRONT_PROXY_KEY` will cause platform outages and break critical functionality. +::: + +### System-Managed Secret Restrictions + +System-managed secrets are read-only and should not be modified or deleted. They are essential for: + +- Storefront operations and routing +- Monitoring and observability (Grafana) +- Internal messaging and communication (NATS) +- Platform infrastructure + +If you believe a system-managed secret is incorrect or causing issues: + +1. **Do not delete or modify the secret** +2. Document the issue, including the secret name and observed behavior +3. Contact Shopware PaaS support immediately +4. Do not attempt to work around system secrets by creating duplicates + +### Secret History & Rollback + +::: warning Important +Shopware PaaS does not maintain version history for secrets. Once a secret is modified or deleted, the previous value cannot be recovered through the platform. +::: + +Always back up critical secret values locally before making changes: + +```sh +# Retrieve and save a secret locally before modifying +sw-paas vault get --secret-id SECRET-ID > backup-secret.txt +``` + +## Housekeeping & Legacy Secrets + +### Identifying Legacy or Typo Secrets + +Over time, your Vault may accumulate outdated or incorrectly-named secrets. Common issues include: + +- **Typo secrets**: e.g. `SHOPWAREPACKAGES_TOKEN` instead of `SHOPWARE_PACKAGES_TOKEN` +- **Deprecated secrets**: No longer used by current application versions +- **Duplicate secrets**: Same secret created multiple times with different IDs + +### Recommended Cleanup Process + +1. **Audit your secrets**: + ```sh + sw-paas vault list --application-id YOUR-APP-ID + ``` + +2. **Identify unused secrets**: Review each secret and confirm whether it's actively used by your application + +3. **Back up before deletion**: + ```sh + sw-paas vault get --secret-id SECRET-ID > backup-SECRET-NAME.txt + ``` + +4. **Delete unused secrets**: + ```sh + sw-paas vault delete --secret-id SECRET-ID + ``` + +5. **Document the cleanup**: Keep a record of what was deleted and when for future reference + +### Dealing with Typo Secrets + +If you discover a secret with a typo in its name, you have two options: + +**Option 1: Edit the existing secret (faster)** + +1. Edit the secret to correct its name or value: + ```sh + sw-paas vault edit + ``` + +2. Select the secret from the list and update its value as needed + +3. Update your application to use the corrected secret name if it changed + +4. Test thoroughly to ensure the updated secret works + +**Option 2: Create a new secret and delete the old one** + +1. Back up the typo secret's value: + ```sh + sw-paas vault get --secret-id TYPO-SECRET-ID > backup-typo-secret.txt + ``` + +2. Create a correctly-named secret: + ```sh + sw-paas vault create + ``` + +3. Update your application to use the correct secret + +4. Test thoroughly to ensure it works + +5. Delete the typo secret: + ```sh + sw-paas vault delete --secret-id TYPO-SECRET-ID + ``` + + +### Regular Maintenance + +Establish a periodic review process: + +- **Quarterly audit**: Review all user-managed secrets for relevance +- **Document ownership**: Maintain a record of which secrets are used by which applications + +## Safety & Recovery + +### Best Practices + +1. **Always back up before deletion**: + ```sh + sw-paas vault get --secret-id SECRET-ID > $(date +%Y%m%d)-SECRET-NAME-backup.txt + ``` + +2. **Rotate sensitive credentials regularly** (e.g., every 90 days): + - Update API tokens and authentication credentials on a scheduled basis + - Use the `sw-paas vault edit` command to quickly update credential values + - Create new secrets and deprecate old ones for non-editable secret types + +3. **Test changes in non-production environments first** + +4. **Document secret purposes**: Add comments or maintain an external inventory + +5. **Use descriptive names**: Choose clear, consistent naming conventions for your secrets + +6. **Limit access**: Only share vault access with team members who need it + +### What to Do If You Accidentally Delete a Secret + +Since there is no built-in recovery mechanism: + +1. **Check local backups** you may have created before deletion + +2. **Review your application's configuration files** (if the secret was stored there temporarily during development) + +3. **Regenerate the secret** if it's a token or credential that can be recreated: + - For API tokens: Generate a new token from the service provider + - For SSH keys: Create a new key pair and update deployment keys + +4. **Contact support** if the deleted secret was critical and you have no backup + +### Support Escalation + +If you encounter issues that cannot be resolved with the above troubleshooting steps: + +1. **Gather information**: + - Secret name and ID + - Application ID + - Error messages or unexpected behavior + - Steps to reproduce the issue + +2. **Check system status**: Verify there are no ongoing PaaS incidents + +3. **Contact Shopware PaaS support** with the gathered information + From 677d7ed9eb7d8b509ef0f0c89e40487fc45f6c57 Mon Sep 17 00:00:00 2001 From: Andrei Adam Date: Fri, 23 Jan 2026 16:29:32 +0200 Subject: [PATCH 02/11] fix: update doc --- products/paas/shopware/guides/secrets-vault-guide.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/products/paas/shopware/guides/secrets-vault-guide.md b/products/paas/shopware/guides/secrets-vault-guide.md index 10e0dafb7..9f1315ed2 100644 --- a/products/paas/shopware/guides/secrets-vault-guide.md +++ b/products/paas/shopware/guides/secrets-vault-guide.md @@ -122,8 +122,6 @@ The Shopware PaaS Vault contains both system-managed and user-managed secrets. U | `STOREFRONT_PROXY_KEY` | Storefront proxy authentication | System | No | **Do not delete** - Required for routing | | `SSH_PRIVATE_KEY` | Deploy SSH key for repository access | User | Yes | See [SSH key workflow](#example-workflow-using-ssh-keys) | | `SHOPWARE_PACKAGES_TOKEN` | Token for accessing Shopware packages | User | Yes | Check for legacy typos (e.g., `SHOPWAREPACKAGES_TOKEN`) | -| Custom `env` secrets | Application-specific environment variables | User | Yes | Created via `sw-paas vault create --type env` | -| Custom `buildenv` secrets | Build-time environment variables | User | Yes | Created via `sw-paas vault create --type buildenv` | ::: info System-managed secrets use the same retrieval mechanism as user-managed secrets, which is why they appear in your vault list. This is intentional to provide transparency into the credentials your environment is using. From 6ab4b039fdcca74b71e9e9a723af35b5d7fb00a4 Mon Sep 17 00:00:00 2001 From: Andrei Adam Date: Mon, 26 Jan 2026 10:41:53 +0200 Subject: [PATCH 03/11] fix: add NATS to wordlist and fix description for an element --- .wordlist.txt | 1 + products/paas/shopware/guides/secrets-vault-guide.md | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index c7266f824..b53771281 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -585,6 +585,7 @@ MyExtension MyPlugin MyTestClass MyTestInterface +NATS NPM NUR NVDA diff --git a/products/paas/shopware/guides/secrets-vault-guide.md b/products/paas/shopware/guides/secrets-vault-guide.md index 9f1315ed2..adfdeac72 100644 --- a/products/paas/shopware/guides/secrets-vault-guide.md +++ b/products/paas/shopware/guides/secrets-vault-guide.md @@ -121,7 +121,7 @@ The Shopware PaaS Vault contains both system-managed and user-managed secrets. U | `NATS_USER_CREDENTIALS` | NATS messaging user credentials | System | No | **Do not delete** - Required for internal messaging | | `STOREFRONT_PROXY_KEY` | Storefront proxy authentication | System | No | **Do not delete** - Required for routing | | `SSH_PRIVATE_KEY` | Deploy SSH key for repository access | User | Yes | See [SSH key workflow](#example-workflow-using-ssh-keys) | -| `SHOPWARE_PACKAGES_TOKEN` | Token for accessing Shopware packages | User | Yes | Check for legacy typos (e.g., `SHOPWAREPACKAGES_TOKEN`) | +| `SHOPWARE_PACKAGES_TOKEN` | Token for accessing Shopware packages | User | Yes | Watch for typo variants (e.g. missing underscore: `SHOPWAREPACKAGES_TOKEN`) | ::: info System-managed secrets use the same retrieval mechanism as user-managed secrets, which is why they appear in your vault list. This is intentional to provide transparency into the credentials your environment is using. @@ -175,7 +175,7 @@ Always back up critical secret values locally before making changes: ```sh # Retrieve and save a secret locally before modifying -sw-paas vault get --secret-id SECRET-ID > backup-secret.txt +sw-paas vault get --secret-id SECRET-ID > backup-SECRET-NAME.txt ``` ## Housekeeping & Legacy Secrets @@ -230,7 +230,7 @@ If you discover a secret with a typo in its name, you have two options: 1. Back up the typo secret's value: ```sh - sw-paas vault get --secret-id TYPO-SECRET-ID > backup-typo-secret.txt + sw-paas vault get --secret-id TYPO-SECRET-ID > backup-typo-SECRET-NAME.txt ``` 2. Create a correctly-named secret: From a6b7587771bcef489596b1abd9d305babeea1a9b Mon Sep 17 00:00:00 2001 From: Andrei Adam Date: Mon, 26 Jan 2026 10:46:33 +0200 Subject: [PATCH 04/11] fix: remove double whitespace --- products/paas/shopware/guides/secrets-vault-guide.md | 1 - 1 file changed, 1 deletion(-) diff --git a/products/paas/shopware/guides/secrets-vault-guide.md b/products/paas/shopware/guides/secrets-vault-guide.md index adfdeac72..2de6cdf3f 100644 --- a/products/paas/shopware/guides/secrets-vault-guide.md +++ b/products/paas/shopware/guides/secrets-vault-guide.md @@ -247,7 +247,6 @@ If you discover a secret with a typo in its name, you have two options: sw-paas vault delete --secret-id TYPO-SECRET-ID ``` - ### Regular Maintenance Establish a periodic review process: From 6d7703cb592d36cdbef2802b17493661d76d94ee Mon Sep 17 00:00:00 2001 From: Andrei Adam Date: Mon, 26 Jan 2026 10:51:59 +0200 Subject: [PATCH 05/11] fix: remove ending double whitespace --- products/paas/shopware/guides/secrets-vault-guide.md | 1 - 1 file changed, 1 deletion(-) diff --git a/products/paas/shopware/guides/secrets-vault-guide.md b/products/paas/shopware/guides/secrets-vault-guide.md index 2de6cdf3f..10b01e7ef 100644 --- a/products/paas/shopware/guides/secrets-vault-guide.md +++ b/products/paas/shopware/guides/secrets-vault-guide.md @@ -303,4 +303,3 @@ If you encounter issues that cannot be resolved with the above troubleshooting s 2. **Check system status**: Verify there are no ongoing PaaS incidents 3. **Contact Shopware PaaS support** with the gathered information - From 350b5a3b74de1d009c2ea9e683c868f146659c8a Mon Sep 17 00:00:00 2001 From: Andrei Adam Date: Mon, 26 Jan 2026 10:55:06 +0200 Subject: [PATCH 06/11] fix: linting --- products/paas/shopware/guides/secrets-vault-guide.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/products/paas/shopware/guides/secrets-vault-guide.md b/products/paas/shopware/guides/secrets-vault-guide.md index 10b01e7ef..8f1701d6e 100644 --- a/products/paas/shopware/guides/secrets-vault-guide.md +++ b/products/paas/shopware/guides/secrets-vault-guide.md @@ -191,6 +191,7 @@ Over time, your Vault may accumulate outdated or incorrectly-named secrets. Comm ### Recommended Cleanup Process 1. **Audit your secrets**: + ```sh sw-paas vault list --application-id YOUR-APP-ID ``` @@ -198,11 +199,13 @@ Over time, your Vault may accumulate outdated or incorrectly-named secrets. Comm 2. **Identify unused secrets**: Review each secret and confirm whether it's actively used by your application 3. **Back up before deletion**: + ```sh sw-paas vault get --secret-id SECRET-ID > backup-SECRET-NAME.txt ``` 4. **Delete unused secrets**: + ```sh sw-paas vault delete --secret-id SECRET-ID ``` @@ -216,6 +219,7 @@ If you discover a secret with a typo in its name, you have two options: **Option 1: Edit the existing secret (faster)** 1. Edit the secret to correct its name or value: + ```sh sw-paas vault edit ``` @@ -229,11 +233,13 @@ If you discover a secret with a typo in its name, you have two options: **Option 2: Create a new secret and delete the old one** 1. Back up the typo secret's value: + ```sh sw-paas vault get --secret-id TYPO-SECRET-ID > backup-typo-SECRET-NAME.txt ``` 2. Create a correctly-named secret: + ```sh sw-paas vault create ``` @@ -243,6 +249,7 @@ If you discover a secret with a typo in its name, you have two options: 4. Test thoroughly to ensure it works 5. Delete the typo secret: + ```sh sw-paas vault delete --secret-id TYPO-SECRET-ID ``` @@ -259,6 +266,7 @@ Establish a periodic review process: ### Best Practices 1. **Always back up before deletion**: + ```sh sw-paas vault get --secret-id SECRET-ID > $(date +%Y%m%d)-SECRET-NAME-backup.txt ``` From 24c334e7f2b23fd1a2f5c0e13bbc6e3429f40044 Mon Sep 17 00:00:00 2001 From: Andrei Adam <159128004+aadam-shopware@users.noreply.github.com> Date: Tue, 3 Feb 2026 10:28:13 +0200 Subject: [PATCH 07/11] Update products/paas/shopware/guides/secrets-vault-guide.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- products/paas/shopware/guides/secrets-vault-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/products/paas/shopware/guides/secrets-vault-guide.md b/products/paas/shopware/guides/secrets-vault-guide.md index 8f1701d6e..224872bae 100644 --- a/products/paas/shopware/guides/secrets-vault-guide.md +++ b/products/paas/shopware/guides/secrets-vault-guide.md @@ -167,8 +167,8 @@ If you believe a system-managed secret is incorrect or causing issues: ### Secret History & Rollback -::: warning Important -Shopware PaaS does not maintain version history for secrets. Once a secret is modified or deleted, the previous value cannot be recovered through the platform. +::: warning +**Important:** Shopware PaaS does not maintain version history for secrets. Once a secret is modified or deleted, the previous value cannot be recovered through the platform. ::: Always back up critical secret values locally before making changes: From 29a581ac7adace0b0d59e29447895311ee18e899 Mon Sep 17 00:00:00 2001 From: Andrei Adam Date: Tue, 3 Feb 2026 13:46:39 +0200 Subject: [PATCH 08/11] fix: update doc --- products/paas/shopware/guides/secrets-vault-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/products/paas/shopware/guides/secrets-vault-guide.md b/products/paas/shopware/guides/secrets-vault-guide.md index 224872bae..a977c1eee 100644 --- a/products/paas/shopware/guides/secrets-vault-guide.md +++ b/products/paas/shopware/guides/secrets-vault-guide.md @@ -151,7 +151,7 @@ sw-paas application list ### System-Managed Secret Restrictions -System-managed secrets are read-only and should not be modified or deleted. They are essential for: +System-managed secrets must be treated as read-only and must not be modified or deleted. The platform does not technically prevent you from changing or removing these secrets, but doing so is unsupported and will break critical platform functionality. They are essential for: - Storefront operations and routing - Monitoring and observability (Grafana) From a6c2e9d507305e86505529e9ee030955949fe83b Mon Sep 17 00:00:00 2001 From: Andrei Adam <159128004+aadam-shopware@users.noreply.github.com> Date: Tue, 3 Feb 2026 13:50:21 +0200 Subject: [PATCH 09/11] fix: update Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../paas/shopware/guides/secrets-vault-guide.md | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/products/paas/shopware/guides/secrets-vault-guide.md b/products/paas/shopware/guides/secrets-vault-guide.md index a977c1eee..a1968db93 100644 --- a/products/paas/shopware/guides/secrets-vault-guide.md +++ b/products/paas/shopware/guides/secrets-vault-guide.md @@ -127,22 +127,13 @@ The Shopware PaaS Vault contains both system-managed and user-managed secrets. U System-managed secrets use the same retrieval mechanism as user-managed secrets, which is why they appear in your vault list. This is intentional to provide transparency into the credentials your environment is using. ::: -### Filtering Secrets by Application +### Understanding Organization-wide Secrets -By default, `sw-paas vault list` shows secrets across all applications in your organization, which can lead to duplicate entries if multiple apps use the same secret names. +The `sw-paas vault list` command shows all secrets stored in your organization’s Vault. Because secrets are organization-global and reusable, the same secret values can be referenced by multiple applications using the same secret name. -To view secrets for a specific application: - -```sh -sw-paas vault list --application-id YOUR-APP-ID -``` - -To find your application ID: - -```sh -sw-paas application list -``` +If multiple applications in your organization use a secret with the same name, they are all referring to the same underlying Vault secret, not separate per-application copies. +This means you manage each secret once at the organization level, and then reference it from the applications that need it. ## Permissions & Behavior ::: danger From 47a9180db9ddd4c103c81cd87a8b167d74c4e284 Mon Sep 17 00:00:00 2001 From: Andrei Adam Date: Tue, 3 Feb 2026 13:51:36 +0200 Subject: [PATCH 10/11] fix: update header space --- products/paas/shopware/guides/secrets-vault-guide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/products/paas/shopware/guides/secrets-vault-guide.md b/products/paas/shopware/guides/secrets-vault-guide.md index a1968db93..6ba70a93e 100644 --- a/products/paas/shopware/guides/secrets-vault-guide.md +++ b/products/paas/shopware/guides/secrets-vault-guide.md @@ -134,6 +134,7 @@ The `sw-paas vault list` command shows all secrets stored in your organization If multiple applications in your organization use a secret with the same name, they are all referring to the same underlying Vault secret, not separate per-application copies. This means you manage each secret once at the organization level, and then reference it from the applications that need it. + ## Permissions & Behavior ::: danger From 84c0b7c38aca75083d0a1d360b0feea64c330b0d Mon Sep 17 00:00:00 2001 From: Micha Date: Wed, 4 Feb 2026 14:34:06 +0100 Subject: [PATCH 11/11] chore/small-grammar-fixes --- products/paas/shopware/guides/secrets-vault-guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/products/paas/shopware/guides/secrets-vault-guide.md b/products/paas/shopware/guides/secrets-vault-guide.md index 6ba70a93e..e1bf78cf9 100644 --- a/products/paas/shopware/guides/secrets-vault-guide.md +++ b/products/paas/shopware/guides/secrets-vault-guide.md @@ -133,7 +133,7 @@ The `sw-paas vault list` command shows all secrets stored in your organization If multiple applications in your organization use a secret with the same name, they are all referring to the same underlying Vault secret, not separate per-application copies. -This means you manage each secret once at the organization level, and then reference it from the applications that need it. +This means you manage each secret once at the organization level and then reference it from the applications that need it. ## Permissions & Behavior @@ -174,7 +174,7 @@ sw-paas vault get --secret-id SECRET-ID > backup-SECRET-NAME.txt ### Identifying Legacy or Typo Secrets -Over time, your Vault may accumulate outdated or incorrectly-named secrets. Common issues include: +Over time, your Vault may accumulate outdated or incorrectly named secrets. Common issues include: - **Typo secrets**: e.g. `SHOPWAREPACKAGES_TOKEN` instead of `SHOPWARE_PACKAGES_TOKEN` - **Deprecated secrets**: No longer used by current application versions @@ -230,7 +230,7 @@ If you discover a secret with a typo in its name, you have two options: sw-paas vault get --secret-id TYPO-SECRET-ID > backup-typo-SECRET-NAME.txt ``` -2. Create a correctly-named secret: +2. Create a correctly named secret: ```sh sw-paas vault create