Skip to content

chore: adjust shopware-cli and deployment-helper configuration file locations #2521

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Malte Janz (MalteJanz) wants to merge 5 commits into
base: main
Choose a base branch
from
Open

chore: adjust shopware-cli and deployment-helper configuration file locations #2521

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
71646fe
chore: adjust shopware-cli and deployment-helper configuration file
MalteJanz Sep 17, 2026
d430a6e
fix: clarify project configuration file paths in documentation
MalteJanz Sep 17, 2026
ffb7e3f
fix: remove appending to config shell script recommendation to be more
MalteJanz Sep 17, 2026
e6d0a4c
fix: codestyle
MalteJanz Sep 17, 2026
835dfb0
fix: add why section for the configuration location change
MalteJanz Sep 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 17 additions & 17 deletions guides/development/dev-environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ nav:
Shopware CLI provides a fully integrated Docker-based development environment. A single command launches your entire stack, streams logs, manages watchers, and lets you configure PHP and profiling - all without manually editing Docker files.

:::info
The development environment requires a compatibility date of `2026-03-01` or later in your `.shopware-project.yml`. Projects created with `shopware-cli project create` have this set automatically.
The development environment requires a compatibility date of `2026-03-01` or later in your `.config/shopware-project.yml`. Projects created with `shopware-cli project create` have this set automatically. See the [Shopware CLI configuration file lookup priority](../../products/tools/cli/configuration.md) for the preferred path and legacy fallbacks.
:::

## Starting the environment
Expand Down Expand Up @@ -78,7 +78,7 @@ The following table lists the settings you can change in the Config tab:
| **PHP Version** | `8.2`, `8.3`, `8.4`, `8.5` |
| **Profiler** | `none`, `xdebug`, `blackfire`, `tideways`, `pcov`, `spx` |

When selecting `blackfire` or `tideways`, additional credential fields appear. Sensitive credentials are stored in `.shopware-project.local.yml` (excluded from version control).
When selecting `blackfire` or `tideways`, additional credential fields appear. Sensitive credentials are stored in `.config/shopware-project.local.yml` (excluded from version control).

:::info
The profiler is now configured via the Config tab.
Expand All @@ -92,34 +92,34 @@ If your project was created before March 2026 and uses the older `make up`/`make

### What triggers the wizard

The wizard appears when your project's `compatibility_date` in `.shopware-project.yml` is before `2026-03-01` (or missing entirely). This signals that the project hasn't been configured for the new development environment yet.
The wizard appears when your project's `compatibility_date` in `.config/shopware-project.yml` is before `2026-03-01` (or missing entirely). This signals that the project hasn't been configured for the new development environment yet.
Comment thread
MalteJanz marked this conversation as resolved.

### What the wizard does

Walking through the setup wizard takes about a minute. Here's what happens at each step:

1. **Welcome** - explains what the wizard will do and asks you to proceed
2. **Admin user** - pre-fills `admin` (you can change it) for the Shopware admin account
3. **Admin password** - pre-fills `shopware` (you can change it); stored as credentials in `.shopware-project.yml`
3. **Admin password** - pre-fills `shopware` (you can change it); stored as credentials in `.config/shopware-project.yml`
4. **PHP version** - reads your `composer.lock` to determine compatible PHP versions and offers the highest supported one as the default (e.g., `8.5`)

After you confirm, the wizard:

- Sets `compatibility_date` to `2026-03-01` in `.shopware-project.yml`
- Sets `compatibility_date` to `2026-03-01` in `.config/shopware-project.yml`
- Adds a `local` environment with type `docker` and your chosen URL/credentials
- Configures the Docker PHP version
- Generates a new `compose.yaml` tailored to your project's dependencies
- Starts the Docker containers and runs the Shopware installer

### What happens to existing files

| File | What changes |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.shopware-project.yml` | Updated with `compatibility_date`, `environments`, and `docker` config |
| `.shopware-project.local.yml` | Created if you chose a profiler with credentials (Blackfire, Tideways) |
| `compose.yaml` | **Replaced** with the CLI-managed version - your old file is overwritten, so back it up first and move any customizations to `compose.override.yaml` |
| `Makefile` | **Not touched** - you can delete it once you've migrated, or keep it around |
| `composer.json` | If `shopware/deployment-helper` isn't already present, it's added to `require` |
| File | What changes |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.config/shopware-project.yml` | Updated with `compatibility_date`, `environments`, and `docker` config |
| `.config/shopware-project.local.yml` | Created if you chose a profiler with credentials (Blackfire, Tideways) |
| `compose.yaml` | **Replaced** with the CLI-managed version - your old file is overwritten, so back it up first and move any customizations to `compose.override.yaml` |
| `Makefile` | **Not touched** - you can delete it once you've migrated |
| `composer.json` | If `shopware/deployment-helper` isn't already present, it's added to `require` |

### After the wizard completes

Expand Down Expand Up @@ -273,7 +273,7 @@ The compose file inspects your `composer.lock` at generation time:

## Environment executors

The CLI abstracts command execution across environment types, configured per environment in `.shopware-project.yml`:
The CLI abstracts command execution across environment types, configured per environment in `.config/shopware-project.yml`:

| Type | Behavior |
| ------------- | -------------------------------------------------------------------- |
Expand Down Expand Up @@ -308,7 +308,7 @@ The web container exposes these ports by default:

## Configuration reference

### `.shopware-project.yml`
### `.config/shopware-project.yml`

```yaml
compatibility_date: '2026-03-01'
Expand All @@ -332,9 +332,9 @@ environments:

Shop URL and Admin API credentials belong under `environments` (an empty `-e`/`--env` defaults to `environments.local`). Top-level `url` and `admin_api` keys are deprecated: existing config files that still use them keep working and log a deprecation warning, but `project create` and `project config init` only write `environments.local`.

### `.shopware-project.local.yml`
### `.config/shopware-project.local.yml`

Sensitive credentials are stored in `.shopware-project.local.yml` (add to `.gitignore`):
Sensitive credentials are stored in `.config/shopware-project.local.yml` (add to `.gitignore`):

```yaml
docker:
Expand Down Expand Up @@ -432,7 +432,7 @@ If you must run Composer on the host, raise CLI `memory_limit` to at least `512M

### Compatibility date error

Set `compatibility_date: '2026-03-01'` in `.shopware-project.yml`. For more context, see the [build command docs](../../products/tools/cli/project-commands/build.md#compatibility-date).
Set `compatibility_date: '2026-03-01'` in `.config/shopware-project.yml`. For more context, see the [build command docs](../../products/tools/cli/project-commands/build.md#compatibility-date).

## Next steps

Expand Down
2 changes: 1 addition & 1 deletion guides/hosting/installation-updates/creating-a-staging-instance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ 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
```

Configure the dump command with `.shopware-project.yml` to specify tables to skip, additional anonymization fields, and more. See the [CLI documentation](../../../products/tools/cli/project-commands/mysql-dump.md) for details.
Configure the dump command with `.config/shopware-project.yml` to specify tables to skip, additional anonymization fields, and more. See the [CLI documentation](../../../products/tools/cli/project-commands/mysql-dump.md) for details.

### 3. Configuring the staging instance

Expand Down
16 changes: 8 additions & 8 deletions guides/hosting/installation-updates/deployments/deployment-helper/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ nav:

# Deployment Helper Configuration

The Deployment Helper can be configured via a `.shopware-project.yml` file in the root of your project. Configure only the keys you use. Every section is optional.
The Deployment Helper can be configured via a `.config/shopware-project.yml` file in the root of your project. Configure only the keys you use. Every section is optional. See the [Shopware CLI configuration file lookup priority](../../../../../products/tools/cli/configuration.md) for the preferred path and legacy fallbacks.

## Basic configuration

Expand Down Expand Up @@ -238,7 +238,7 @@ This significantly speeds up deployment for shops with many sales channels.

## OpenSearch index creation on install

The `opensearch.index-on-install` key controls whether OpenSearch indexes are created automatically right after a fresh installation. When creating a new Shopware PaaS project with `shopware-cli project create --deployment shopware-paas`, the generated `.shopware-project.yml` sets this to `true` so OpenSearch indexing is enabled from the first deployment. For other deployment targets, the key defaults to `false` and can be enabled manually if needed:
The `opensearch.index-on-install` key controls whether OpenSearch indexes are created automatically right after a fresh installation. When creating a new Shopware PaaS project with `shopware-cli project create --deployment shopware-paas`, the generated `.config/shopware-project.yml` sets this to `true` so OpenSearch indexing is enabled from the first deployment. For other deployment targets, the key defaults to `false` and can be enabled manually if needed:

```yaml
deployment:
Expand All @@ -248,16 +248,16 @@ deployment:

## Local configuration overrides

You can create a `.shopware-project.local.yml` file alongside your `.shopware-project.yml` to override configuration values for local development without modifying the base config. This file should be added to your `.gitignore`.
You can create a `.config/shopware-project.local.yml` file alongside your `.config/shopware-project.yml` to override configuration values for local development without modifying the base config. This file should be added to your `.gitignore`.

The local file is deep-merged on top of the base configuration:

- **Scalar values** (strings, numbers) are replaced by the local value.
- **Maps** (associative arrays) are deep-merged recursively.
- **Lists** (indexed arrays): for each list-valued key, the list from `.shopware-project.local.yml` is appended to the end of the list from `.shopware-project.yml`. The relative order of items within each list is preserved, nested lists are treated the same way, and no automatic deduplication is performed.
- **Lists** (indexed arrays): for each list-valued key, the list from `.config/shopware-project.local.yml` is appended to the end of the list from `.config/shopware-project.yml`. The relative order of items within each list is preserved, nested lists are treated the same way, and no automatic deduplication is performed.

```yaml
# .shopware-project.local.yml
# .config/shopware-project.local.yml
deployment:
hooks:
pre: |
Expand All @@ -275,14 +275,14 @@ deployment:

The local config file supports custom YAML tags to control how values are merged. These tags (such as `!reset` and `!override`) are interpreted by the Deployment Helper itself and are not part of the YAML standard.

> Note: Generic YAML parsers or linters that are not configured to allow custom tags may emit errors or warnings when loading `.shopware-project.local.yml`. Ensure your tooling supports custom tags or excludes this file, and use a Deployment Helper version that documents support for `!reset` and `!override` (see the Deployment Helper changelog for the minimum supported version).
> Note: Generic YAML parsers or linters that are not configured to allow custom tags may emit errors or warnings when loading `.config/shopware-project.local.yml`. Ensure your tooling supports custom tags or excludes this file, and use a Deployment Helper version that documents support for `!reset` and `!override` (see the Deployment Helper changelog for the minimum supported version).

#### `!reset`: clear and replace a field

Use `!reset` on a single field to ignore the value from the base configuration and use only the tagged value. It can be applied to scalars, lists, or maps, and it affects only that one field: the parent object is still merged as usual, but the value for this key is completely replaced. For lists, all inherited items are dropped; for maps, only the keys you define remain for that field.

```yaml
# .shopware-project.local.yml
# .config/shopware-project.local.yml
deployment:
extension-management:
# Resets just this exclude field: the base exclude list is discarded and replaced
Expand All @@ -300,7 +300,7 @@ deployment:
Use `!override` on a mapping/section to disable deep-merging for that whole mapping. The tagged section completely replaces the corresponding section from the base configuration: nested keys are not merged recursively, and any keys that are not listed in the overriding section are removed.

```yaml
# .shopware-project.local.yml
# .config/shopware-project.local.yml
deployment:
# Overrides the entire hooks section: all hooks from the base config are removed
hooks: !override
Expand Down
2 changes: 1 addition & 1 deletion guides/hosting/installation-updates/deployments/deployment-helper/environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ See [SSL/TLS Setup](../../../infrastructure/database.md#ssltls-connection) for c
| `SHOPWARE_DEPLOYMENT_TIMEOUT` | Seconds (default: `300`) | Max time a single deployment step can run; set to `null` to disable |
| `SHOPWARE_DEPLOYMENT_FORCE_REINSTALL` | `1` or unset | Set to `1` to force fresh install with `--drop-database` (destroys existing data!) |
| `SHOPWARE_DEPLOYMENT_STAGING` | `1` or unset | Set to `1` to enable staging mode on every deployment |
| `SHOPWARE_PROJECT_CONFIG_FILE` | File path | Custom path to `.shopware-project.yml` (absolute or relative to project root) |
| `SHOPWARE_PROJECT_CONFIG_FILE` | File path | Custom project configuration path (absolute or relative to project root) |

### Store authentication

Expand Down
6 changes: 3 additions & 3 deletions guides/hosting/installation-updates/deployments/deployment-helper/extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ See [Extension Management](../../extension-management.md) for details on install

### Option 2: Disable the Deployment Helper's extension management

If you prefer to manage extensions manually through the Store or Administration, disable the extension management in your `.shopware-project.yml`:
If you prefer to manage extensions manually through the Store or Administration, disable the extension management in your `.config/shopware-project.yml`:

```yaml
deployment:
Expand Down Expand Up @@ -139,7 +139,7 @@ Shopware Plugin Service

Removing an extension requires you to follow two steps:

First, set the extension to `remove` in the `.shopware-project.yml` file:
First, set the extension to `remove` in the `.config/shopware-project.yml` file:

```yaml
deployment:
Expand All @@ -157,7 +157,7 @@ deployment:

and deploy the changes. The extension will be uninstalled and is inactive.

Secondly, remove the extension from source code, remove the entry from the `.shopware-project.yml` file, and deploy the changes again.
Secondly, remove the extension from source code, remove the entry from the `.config/shopware-project.yml` file, and deploy the changes again.

## How Deployment Helper adapts to different Shopware versions

Expand Down
4 changes: 2 additions & 2 deletions guides/hosting/installation-updates/deployments/deployment-helper/hosting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,11 @@

## PaaS Native

PaaS Native environments invoke Deployment Helper during the deploy step of your CI/CD pipeline. Simply configure your `.shopware-project.yml` as usual and DH will execute with the same flow as Platform.sh or manual deployments.
PaaS Native environments invoke Deployment Helper during the deploy step of your CI/CD pipeline. Simply configure your `.config/shopware-project.yml` as usual and DH will execute with the same flow as Platform.sh or manual deployments.

Check warning on line 23 in guides/hosting/installation-updates/deployments/deployment-helper/hosting.md

View workflow job for this annotation

GitHub Actions / LanguageTool

[LanguageTool] guides/hosting/installation-updates/deployments/deployment-helper/hosting.md#L23 

The word ‘deploy’ is a verb. Did you mean the noun “deployment” (= release, placement)? (PREPOSITION_VERB[53])
Suggestions: `deployment`
URL: https://languagetool.org/insights/post/verbs-as-nouns/ 
Rule: https://community.languagetool.org/rule/show/PREPOSITION_VERB?lang=en-US&subId=53
Category: GRAMMAR
Raw output 
guides/hosting/installation-updates/deployments/deployment-helper/hosting.md:23:61: The word ‘deploy’ is a verb. Did you mean the noun “deployment” (= release, placement)? (PREPOSITION_VERB[53])
 Suggestions: `deployment`
 URL: https://languagetool.org/insights/post/verbs-as-nouns/ 
 Rule: https://community.languagetool.org/rule/show/PREPOSITION_VERB?lang=en-US&subId=53
 Category: GRAMMAR

## Kubernetes / Operators

When using [Shopware's Kubernetes operator](https://github.com/shopware/shopware-operator), deployment is triggered via a one-time job that invokes Deployment Helper. The operator does not run DH directly; it spawns it as a pod job. Configure your `.shopware-project.yml` and Deployment Helper will behave as normal.
When using [Shopware's Kubernetes operator](https://github.com/shopware/shopware-operator), deployment is triggered via a one-time job that invokes Deployment Helper. The operator does not run DH directly; it spawns it as a pod job. Configure your `.config/shopware-project.yml` and Deployment Helper will behave as normal.

## Fastly integration

Expand Down
8 changes: 4 additions & 4 deletions guides/hosting/installation-updates/deployments/deployment-helper/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,18 +60,18 @@ The `run` command accepts the following options:
| `--skip-assets-install` | Skip asset installation (use when assets were already copied in CI/CD) |
| `--skip-asset-install` | Deprecated alias for `--skip-assets-install` |
| `--timeout=<seconds>` | Set script execution timeout in seconds. Set to `null` to disable. Takes precedence over `SHOPWARE_DEPLOYMENT_TIMEOUT`, which in turn defaults to `300` (see [`RunCommand`](https://github.com/shopware/deployment-helper/blob/main/src/Command/RunCommand.php)). |
| `--project-config=<path>` | Path to a custom `.shopware-project.yml` file (absolute or relative to project root) |
| `--project-config=<path>` | Path to a custom project configuration file (absolute or relative to project root) |

`run` returns a non-zero exit code if any step fails. In CI/CD, treat a non-zero exit as a failed deployment and stop the rollout.

## Best practices: multi-environment deployments

### One config file, environment variables for differences

Use a single `.shopware-project.yml` for all environments (production, staging, dev). Override environment-specific settings via environment variables in your CI/CD:
Use a single `.config/shopware-project.yml` for all environments (production, staging, dev). Override environment-specific settings via environment variables in your CI/CD:

```yaml
# .shopware-project.yml (committed)
# .config/shopware-project.yml (committed)
deployment:
store:
license-domain: 'example.com'
Expand Down Expand Up @@ -130,7 +130,7 @@ Only enable `always_clear` if you have a specific reason (e.g., custom caching l

### One-time tasks are version-control, not manual ops

Include one-time tasks in your `.shopware-project.yml` and commit them to Git. This way:
Include one-time tasks in your `.config/shopware-project.yml` and commit them to Git. This way:

- Developers see what migrations exist in the codebase.
- The task runs automatically on production with no manual steps.
Expand Down
Loading
Loading