From f4c7b62490f2575d3496dc4931c53b6e028a72e9 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Mon, 18 May 2026 05:37:04 +0200 Subject: [PATCH 01/37] feat(cli): document new Docker-based development environment Add comprehensive documentation for the new Manage your Shopware Project Usage: shopware-cli project [command] Available Commands: admin-api pre authenticated curl interface to the Admin API admin-build Builds the Administration admin-watch Starts the Shopware Admin Watcher autofix Autofix a project ci Build Shopware in the CI clear-cache Clears the Shop cache config Manage the project config console Runs the Symfony Console (bin/console) for current project create Create a new Shopware 6 project doctor Check your Shopware project for potential problems dump Dumps the Shopware database extension Manage the extensions of the Shopware shop fix Fix project format Format project generate-jwt Generate a new JWT secret key image-proxy Start a proxy server for serving images from the public folder storefront-build Builds the Storefront storefront-watch Starts the Shopware Storefront Watcher upgrade-check Check that installed extensions are compatible with a future Shopware version validate Validate project worker Run multiple Symfony worker in background. Flags: -h, --help help for project --project-config string Path to config (default ".shopware-project.yml") Global Flags: -n, --no-interaction do not ask any interactive questions --verbose show debug output Use "shopware-cli project [command] --help" for more information about a command. development environment introduced in shopware-cli. Covers: - Interactive DevTUI dashboard with General, Logs, and Config tabs - Background start/stop via and subcommands - Setup wizard for projects migrating to dev mode - command for viewing application logs - Auto-generated compose.yaml with services, port mappings, and auto-detection of queue/search dependencies - Environment executor abstraction (docker, local, symfony-cli) - Configuration reference for .shopware-project.yml and local overrides - Troubleshooting guide Also updates the start-developing guide, CLI index, and helper commands page to reference the new development environment. --- guides/development/start-developing.md | 22 ++ products/tools/cli/index.md | 1 + .../cli/project-commands/dev-environment.md | 241 ++++++++++++++++++ .../cli/project-commands/helper-commands.md | 16 ++ 4 files changed, 280 insertions(+) create mode 100644 products/tools/cli/project-commands/dev-environment.md diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md index 793936fbbb..f47ed3c302 100644 --- a/guides/development/start-developing.md +++ b/guides/development/start-developing.md @@ -22,6 +22,28 @@ Common development areas: Projects follow the [project template layout](../installation/project-overview.md). +## Using the Development Environment + +Shopware CLI provides an integrated Docker-based development environment with an interactive terminal dashboard. From your project root: + +```bash +# Launch the interactive DevTUI dashboard +shopware-cli project dev + +# Or start the environment in the background +shopware-cli project dev start +``` + +The dashboard provides: + +- An overview of your Shop and Admin URLs with credentials +- One-click Admin and Storefront watchers +- Real-time log streaming from `var/log/` and Docker containers +- PHP version and profiler configuration (xdebug, blackfire, tideways, etc.) +- Service discovery (Adminer, Mailpit, queue, etc.) + +See the [Development Environment guide](../../products/cli/project-commands/dev-environment.md) for full details. + ## Using `bin/console` for development To run commands, open a shell inside the web container: diff --git a/products/tools/cli/index.md b/products/tools/cli/index.md index 1cc279c3c4..d8e81fd859 100644 --- a/products/tools/cli/index.md +++ b/products/tools/cli/index.md @@ -10,6 +10,7 @@ nav: [Shopware CLI](https://github.com/shopware/shopware-cli) is the open-source command-line interface for working with Shopware 6. It's a standalone developer tool that you install and configure separately from your Shopware instance. Once set up, it helps you automate and speed up common tasks such as: - managing and configuring Shopware projects +- starting and operating an integrated Docker-based development environment - building, validating, and packaging extensions - uploading and maintaining extensions in the Shopware Store - running CI/CD pipelines for Shopware-based solutions diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md new file mode 100644 index 0000000000..f947ab3b9e --- /dev/null +++ b/products/tools/cli/project-commands/dev-environment.md @@ -0,0 +1,241 @@ +--- +nav: + title: Development Environment + position: 1 + +--- + +# Development Environment + +Starting with compatibility date `2026-03-01`, Shopware CLI provides a fully integrated development environment powered by Docker. It replaces manual `docker compose` workflows with a single command and an interactive terminal dashboard. + +## Quick Start + +From your Shopware project root, run: + +```bash +shopware-cli project dev +``` + +This launches the interactive **DevTUI** dashboard, which manages your environment lifecycle, displays service information, streams logs, and lets you configure PHP and profiling settings — all through a terminal interface. + +### For projects without a dev environment + +If your project doesn't yet have a development environment configured (compatibility date before `2026-03-01`), running `shopware-cli project dev` automatically starts the **setup wizard**. The wizard: + +- Collects your Shop URL, admin credentials, PHP version, and profiler preference +- Adds `shopware/deployment-helper` to your `composer.json` if missing +- Updates `.shopware-project.yml` with environment and Docker configuration +- Generates `compose.yaml` and starts the Docker environment + +## Background Usage + +If you're running in CI or prefer not to use the interactive dashboard, you can start and stop the environment in the background: + +```bash +# Start the environment (non-interactive) +shopware-cli project dev start + +# Stop the environment +shopware-cli project dev stop +``` + +The `start` command prints the Shop and Admin URLs, any auxiliary services, and hints for stopping and viewing logs. + +## DevTUI Dashboard + +The interactive dashboard has three tabs: + +### General Tab + +Displays an overview of your running environment: + +- **Environment type** (docker, local, symfony-cli) +- **Shop URL** and **Admin URL** with admin credentials +- **Watchers** — start Admin and Storefront watchers directly from the dashboard +- **Services** — auto-discovered auxiliary services (Adminer, Mailpit, queue, etc.) + +### Logs Tab + +Real-time log streaming from your Shopware application. The tab shows: + +- **Log files from `var/log/`** — the most recently modified file is selected by default +- **Watcher output** — live output from running Admin and Storefront watchers +- **Docker container logs** — `docker compose logs` output from the web container + +Use the sidebar to switch between log sources. Press `f` to toggle follow mode. + +### Config Tab + +Adjust your Docker development environment without manually editing YAML files: + +| Setting | Options | +|---------|---------| +| **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 (Server ID/Token or API Key). Sensitive credentials are stored in `.shopware-project.local.yml`, which is excluded from version control. + +After changing settings, select **Save & Regenerate** to update `compose.yaml` with the new configuration. Restart Docker for changes to take effect. + +## Viewing Application Logs + +The `shopware-cli project logs` command lets you inspect Shopware application logs without opening the dashboard: + +```bash +# Show last 100 lines of the most recently modified log file +shopware-cli project logs + +# Show a specific log file +shopware-cli project logs dev-2026-05-18.log + +# Follow the log (like tail -f) +shopware-cli project logs -f + +# List available log files +shopware-cli project logs -l + +# Show a custom number of lines +shopware-cli project logs --lines 50 +``` + +## Docker Services + +The development environment automatically generates a `compose.yaml` file with the following services: + +| Service | Description | URL (default) | +|---------|-------------|---------------| +| **web** | PHP + Node.js application server (Caddy) | `http://127.0.0.1:8000` | +| **database** | MariaDB 11.8 database | internal only | +| **adminer** | Web-based database management | `http://127.0.0.1:9080` | +| **mailer** | Mailpit email testing tool | `http://127.0.0.1:8025` | +| **lavinmq** | Message queue (auto-detected from `composer.lock`) | `http://127.0.0.1:15672` | +| **opensearch** | Search engine (auto-detected from `composer.lock`) | `http://127.0.0.1:9200` | +| **blackfire** | Blackfire profiler agent (when profiler is configured) | internal only | +| **tideways-daemon** | Tideways profiler agent (when profiler is configured) | internal only | + +The `compose.yaml` file is **managed by shopware-cli** and regenerated when you change configuration. Create a `compose.override.yaml` file to customize services without affecting the managed configuration. + +### Auto-Detection + +The compose file is generated based on your project's `composer.lock`: + +- If `symfony/amqp-messenger` is installed, a **LavinMQ** queue service is added and `MESSENGER_TRANSPORT_DSN` is configured +- If `shopware/elasticsearch` is installed, an **OpenSearch** service is added with corresponding environment variables +- The **PHP version** defaults to `8.3` unless overridden in the Config tab + +## Environment Executors + +Shopware CLI abstracts command execution across different environment types: + +| Type | Description | +|------|-------------| +| `docker` | Executes commands inside the web container via `docker compose exec` | +| `local` | Executes commands directly on the host machine | +| `symfony-cli` | Uses the Symfony CLI binary for command execution (auto-detected) | + +The executor type is configured per environment in `.shopware-project.yml`: + +```yaml +environments: + local: + type: docker + url: http://127.0.0.1:8000 + admin_api: + username: admin + password: shopware +``` + +When no environment is specified, Shopware CLI looks for a `local` environment first, then falls back to a local executor using the top-level `url` and `admin_api` configuration. + +## Configuration Reference + +### .shopware-project.yml + +```yaml +# Required to enable the development environment +compatibility_date: '2026-03-01' + +# Top-level URL (used as fallback when no environment is specified) +url: http://127.0.0.1:8000 + +# Docker development environment configuration +docker: + php: + version: "8.3" # PHP version: 8.2, 8.3, 8.4, 8.5 + profiler: xdebug # Profiler: none (empty), xdebug, blackfire, tideways, pcov, spx + blackfire_server_id: "" # Required when profiler is blackfire + blackfire_server_token: "" # Required when profiler is blackfire + tideways_api_key: "" # Required when profiler is tideways + +# Named environments +environments: + local: + type: docker # docker, local, or symfony-cli + url: http://127.0.0.1:8000 + admin_api: + username: admin + password: shopware +``` + +### .shopware-project.local.yml + +Sensitive credentials (Blackfire server ID/token, Tideways API key) are stored in `.shopware-project.local.yml`. This file is intended to be added to `.gitignore`: + +```yaml +docker: + php: + blackfire_server_id: "your-server-id" + blackfire_server_token: "your-server-token" +``` + +### compose.yaml + +The generated `compose.yaml` is managed by shopware-cli. Customize it via `compose.override.yaml` rather than editing it directly: + +```yaml +# compose.override.yaml — customize without modifying the managed file +services: + web: + ports: + - "8080:8080" # Add additional ports + environment: + APP_ENV: dev +``` + +## Ports + +The web container exposes these ports by default: + +| Port | Purpose | +|------|---------| +| `8000` | Shopware Storefront | +| `8080` | HTTP (alternative) | +| `5173` | Admin Watcher (Vite) | +| `9998` | Storefront Watcher (webpack/Node) | +| `9999` | Storefront Proxy | +| `5773` | IDE debugging | + +## Troubleshooting + +### The compose.yaml file keeps getting reset + +The `compose.yaml` file is managed by shopware-cli and regenerated when configuration changes. Use `compose.override.yaml` for persistent customizations. + +### Container won't start + +Check the application logs with `shopware-cli project logs -f` or from within the DevTUI Logs tab. + +### Shopware isn't installed yet + +When the environment starts and Shopware is not installed, the DevTUI prompts you to run the installer. Provide your preferred locale, currency, and admin credentials. The installer uses `shopware/deployment-helper` under the hood. + +### Compatibility date is not set + +If you see an error about the compatibility date, set it in `.shopware-project.yml`: + +```yaml +compatibility_date: '2026-03-01' +``` + +For more context on compatibility dates, see the [Build command documentation](./build.md#compatibility-date). diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index 2fd24bcaf8..dbebe6f3e3 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/products/tools/cli/project-commands/helper-commands.md @@ -25,6 +25,22 @@ shopware-cli project create The version parameter can be also `latest` for the latest stable version or `dev-trunk` for the latest development version. +## Development Environment + +Shopware CLI provides a fully integrated Docker-based development environment. See the [Development Environment](./dev-environment.md) guide for details. + +```bash +# Launch the interactive dashboard +shopware-cli project dev + +# Start/stop in the background +shopware-cli project dev start +shopware-cli project dev stop + +# View application logs +shopware-cli project logs +``` + ## Replacements to include in shell scripts Shopware CLI contains replacements for `bin/build-administration.sh` and `bin/build-storefront.sh`. From f7c1925b7879b1b86ea37f709e94529b39e55c81 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Mon, 18 May 2026 07:05:01 +0200 Subject: [PATCH 02/37] docs(cli): emphasize compose.override.yaml pattern for managed compose.yaml Add a dedicated section explaining that compose.yaml is fully managed by the CLI and will be regenerated, with practical compose.override.yaml examples for common customization use cases (extra env vars, ports, volumes, additional services). Strengthen the troubleshooting entry and config reference section with the same guidance. --- .../cli/project-commands/dev-environment.md | 57 +++++++++++++++++-- 1 file changed, 52 insertions(+), 5 deletions(-) diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md index f947ab3b9e..3f25416ea4 100644 --- a/products/tools/cli/project-commands/dev-environment.md +++ b/products/tools/cli/project-commands/dev-environment.md @@ -114,7 +114,54 @@ The development environment automatically generates a `compose.yaml` file with t | **blackfire** | Blackfire profiler agent (when profiler is configured) | internal only | | **tideways-daemon** | Tideways profiler agent (when profiler is configured) | internal only | -The `compose.yaml` file is **managed by shopware-cli** and regenerated when you change configuration. Create a `compose.override.yaml` file to customize services without affecting the managed configuration. +The `compose.yaml` file is **managed by shopware-cli** and regenerated when you change configuration. Never edit this file directly — your changes will be overwritten the next time the CLI regenerates it (for example, after changing PHP version or profiler settings in the Config tab, or after running `shopware-cli project dev`). + +### Customizing with compose.override.yaml + +To extend or override any service, create a `compose.override.yaml` file in your project root. Docker Compose [merges multiple compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/), so your overrides are applied on top of the managed `compose.yaml`. This file is yours to own and should be committed to version control. + +**Common use cases:** + +```yaml +# compose.override.yaml — customize without modifying the managed file + +services: + web: + # Add extra environment variables + environment: + APP_ENV: dev + COMPOSER_HOME: /tmp/composer + + # Expose additional ports (e.g., for debugging) + ports: + - "9003:9003" # Xdebug + + # Mount additional volumes (e.g., custom extensions) + volumes: + - ./custom/extensions:/var/www/html/custom/extensions + + database: + # Persist database data to a named volume + volumes: + - db-data:/var/lib/mysql + + # Add your own services + redis: + image: redis:7-alpine + ports: + - "6379:6379" + +volumes: + db-data: +``` + +The CLI-generated `compose.yaml` includes this header for clarity: + +```yaml +# This file is managed by shopware-cli. Do not edit manually. +# Create a compose.override.yaml to customize services. +# See https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/ +``` ### Auto-Detection @@ -189,12 +236,12 @@ docker: blackfire_server_token: "your-server-token" ``` -### compose.yaml +### compose.yaml (managed) -The generated `compose.yaml` is managed by shopware-cli. Customize it via `compose.override.yaml` rather than editing it directly: +The generated `compose.yaml` is owned and regenerated by shopware-cli. **Do not edit it manually** — your changes will be overwritten. Use `compose.override.yaml` for all customizations. ```yaml -# compose.override.yaml — customize without modifying the managed file +# compose.override.yaml services: web: ports: @@ -220,7 +267,7 @@ The web container exposes these ports by default: ### The compose.yaml file keeps getting reset -The `compose.yaml` file is managed by shopware-cli and regenerated when configuration changes. Use `compose.override.yaml` for persistent customizations. +This is by design. The `compose.yaml` file is **fully managed** by shopware-cli and is regenerated whenever configuration changes (PHP version, profiler) or when the dev environment starts. **Never edit `compose.yaml` directly.** Instead, place all customizations in `compose.override.yaml` — Docker Compose merges it with the managed file automatically. See the [Customizing with compose.override.yaml](#customizing-with-composeoverrideyaml) section for examples. ### Container won't start From 08f221f0fc44a2c0dfc9aa4a8ce6c0427e3e4a81 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Mon, 18 May 2026 07:13:16 +0200 Subject: [PATCH 03/37] docs: move dev environment into development guide as default workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The development environment documentation now lives in the main development guide as the primary workflow for developers: - New guides/development/dev-environment.md — comprehensive guide covering DevTUI dashboard, setup wizard, compose.override.yaml pattern, log streaming, configuration reference, troubleshooting - Restructured guides/development/start-developing.md — leads with the dev environment; old make shell workflow moved to legacy note - Updated guides/development/index.md — dev environment in workflow and tooling sections - Updated guides/installation/index.md — replaced make up/setup instructions with shopware-cli project dev as the way to start - Updated guides/installation/project-overview.md — mentions dev environment as standard interaction method - Updated guides/development/tooling/index.md — added dev environment - Slimmed products/cli/project-commands/dev-environment.md to a CLI command reference pointing to the main guide - Updated helper-commands.md to cross-reference the main guide --- guides/development/dev-environment.md | 264 ++++++++++++++++++ guides/development/index.md | 8 +- guides/development/start-developing.md | 187 ++++++------- guides/development/tooling/index.md | 2 + guides/installation/index.md | 55 +--- guides/installation/project-overview.md | 26 +- .../cli/project-commands/dev-environment.md | 258 ++--------------- .../cli/project-commands/helper-commands.md | 2 +- 8 files changed, 405 insertions(+), 397 deletions(-) create mode 100644 guides/development/dev-environment.md diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md new file mode 100644 index 0000000000..b69f0d8e65 --- /dev/null +++ b/guides/development/dev-environment.md @@ -0,0 +1,264 @@ +--- +nav: + title: Development Environment + position: 3 + +--- + +# Development Environment + +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. +::: + +## Starting the Environment + +From your Shopware project root, run: + +```bash +shopware-cli project dev +``` + +This launches the interactive **DevTUI** dashboard. If your containers aren't running yet, the dashboard starts them. If Shopware hasn't been installed, it guides you through the installation wizard. + +To start without the interactive dashboard (for CI or scripting): + +```bash +shopware-cli project dev start +``` + +To stop everything: + +```bash +shopware-cli project dev stop +``` + +## DevTUI Dashboard + +The dashboard has three tabs, switched with the number keys or by clicking: + +### General Tab (1) + +Your environment at a glance: + +- **Environment type** — docker, local, or symfony-cli +- **Shop and Admin URLs** with credentials for quick access +- **Watchers** — start Admin (Vite HMR on port `5173`) and Storefront (webpack HMR on port `9998`) watchers with one keypress +- **Services** — auto-discovered auxiliary services like Adminer, Mailpit, and message queues + +### Logs Tab (2) + +Real-time log streaming from multiple sources: + +- **Application logs** from `var/log/` — most recently modified file selected by default +- **Watcher output** — live build output from Admin and Storefront watchers +- **Docker logs** — `docker compose logs` from the web container + +Use the sidebar to switch sources. Toggle follow mode with `f`. + +### Config Tab (3) + +Adjust your Docker environment without touching YAML: + +| Setting | Options | +|---------|---------| +| **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). + +After changing settings, select **Save & Regenerate** to update `compose.yaml`. Restart the environment for changes to take effect. + +## Setup Wizard + +If your project doesn't have a development environment configured (compatibility date before `2026-03-01`), running `shopware-cli project dev` starts the setup wizard instead. The wizard: + +1. Collects your Shop URL, admin username/password, PHP version, and profiler choice +2. Resolves compatible PHP versions from your `composer.lock` +3. Adds `shopware/deployment-helper` to `composer.json` if missing +4. Writes the environment configuration to `.shopware-project.yml` +5. Generates `compose.yaml` and starts the Docker environment + +## Viewing Application Logs + +Inspect Shopware logs without opening the dashboard: + +```bash +# Last 100 lines of the most recently modified log +shopware-cli project logs + +# A specific log file +shopware-cli project logs dev-2026-05-18.log + +# Follow the log (like tail -f) +shopware-cli project logs -f + +# List available log files +shopware-cli project logs -l + +# Set number of lines +shopware-cli project logs --lines 50 +``` + +## Running Shopware Commands + +Use `shopware-cli project console` to run `bin/console` commands from your host — no need to shell into the container: + +```bash +shopware-cli project console cache:clear +shopware-cli project console plugin:refresh +shopware-cli project console dal:refresh:index +``` + +When using the Docker executor, commands automatically run inside the web container via `docker compose exec`. + +## Docker Services + +The CLI generates a `compose.yaml` tailored to your project: + +| Service | Description | URL | +|---------|-------------|-----| +| **web** | PHP + Node.js with Caddy | `http://127.0.0.1:8000` | +| **database** | MariaDB 11.8 | internal | +| **adminer** | Database management UI | `http://127.0.0.1:9080` | +| **mailer** | Mailpit (email testing) | `http://127.0.0.1:8025` | +| **lavinmq** | Message queue * | `http://127.0.0.1:15672` | +| **opensearch** | Search engine * | `http://127.0.0.1:9200` | +| **blackfire** | Blackfire agent * | internal | +| **tideways-daemon** | Tideways agent * | internal | + +\* *Auto-detected from `composer.lock` or enabled via configuration.* + +The `compose.yaml` file is **fully managed by shopware-cli** and regenerated whenever you change configuration. **Never edit it directly.** + +### Customizing with compose.override.yaml + +Place all customizations in `compose.override.yaml`. Docker Compose [merges multiple files](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/), so your overrides are applied on top of the managed file: + +```yaml +# compose.override.yaml +services: + web: + environment: + APP_ENV: dev + COMPOSER_HOME: /tmp/composer + ports: + - "9003:9003" # Xdebug + + # Add your own services + redis: + image: redis:7-alpine + ports: + - "6379:6379" +``` + +The CLI-generated `compose.yaml` includes this header for clarity: + +```yaml +# This file is managed by shopware-cli. Do not edit manually. +# Create a compose.override.yaml to customize services. +``` + +### Auto-Detection + +The compose file inspects your `composer.lock` at generation time: + +- `symfony/amqp-messenger` → adds **LavinMQ** and sets `MESSENGER_TRANSPORT_DSN` +- `shopware/elasticsearch` → adds **OpenSearch** with environment variables +- PHP version defaults to `8.3`, overridable in the Config tab + +## Environment Executors + +The CLI abstracts command execution across environment types, configured per environment in `.shopware-project.yml`: + +| Type | Behavior | +|------|----------| +| `docker` | Executes commands inside the web container via `docker compose exec` | +| `local` | Executes commands directly on the host | +| `symfony-cli` | Uses the Symfony CLI binary (auto-detected) | + +```yaml +environments: + local: + type: docker + url: http://127.0.0.1:8000 + admin_api: + username: admin + password: shopware +``` + +## Ports + +The web container exposes these ports by default: + +| Port | Purpose | +|------|---------| +| `8000` | Storefront | +| `8080` | HTTP (alternative) | +| `5173` | Admin Watcher (Vite) | +| `9998` | Storefront Watcher | +| `9999` | Storefront Proxy | +| `5773` | IDE debugging | + +## Configuration Reference + +### .shopware-project.yml + +```yaml +compatibility_date: '2026-03-01' + +url: http://127.0.0.1:8000 + +docker: + php: + version: "8.3" # 8.2, 8.3, 8.4, 8.5 + profiler: xdebug # none (empty), xdebug, blackfire, tideways, pcov, spx + blackfire_server_id: "" # required when profiler is blackfire + blackfire_server_token: "" # required when profiler is blackfire + tideways_api_key: "" # required when profiler is tideways + +environments: + local: + type: docker + url: http://127.0.0.1:8000 + admin_api: + username: admin + password: shopware +``` + +### .shopware-project.local.yml + +Sensitive credentials are stored in `.shopware-project.local.yml` (add to `.gitignore`): + +```yaml +docker: + php: + blackfire_server_id: "your-server-id" + blackfire_server_token: "your-server-token" +``` + +## Troubleshooting + +### compose.yaml keeps getting reset + +This is by design. `compose.yaml` is fully managed and regenerated on config changes. Use `compose.override.yaml` for all customizations. See [Customizing with compose.override.yaml](#customizing-with-composeoverrideyaml). + +### Containers won't start + +Check logs with `shopware-cli project logs -f` or from the Logs tab in the dashboard. + +### Shopware isn't installed + +The DevTUI prompts you to run the installer. It uses `shopware/deployment-helper` to install Shopware with your chosen locale, currency, and admin credentials. + +### 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). + +## Next Steps + +- [Start Developing](./start-developing.md) — What to do once your environment is running +- [Build Extensions](./extensions/index.md) — Create plugins, apps, and themes +- [Using Watchers](./tooling/using-watchers.md) — Hot Module Replacement for Admin and Storefront diff --git a/guides/development/index.md b/guides/development/index.md index b45418226c..16ab282ce8 100644 --- a/guides/development/index.md +++ b/guides/development/index.md @@ -40,7 +40,8 @@ To sell an extension or offer paid features, see the [Monetization guide](moneti Most development follows this sequence: -* Set up the environment +* [Set up the environment](./dev-environment.md) — Start your Docker-based development environment with `shopware-cli project dev` +* [Start developing](./start-developing.md) — Run commands, use watchers, and customize your environment * Create the project or extension * Install and activate it * Implement business logic @@ -77,7 +78,8 @@ The Administration is part of the runtime environment and will be used throughou ## Development tooling -* `bin/console`: Shopware's built-in CLI, used for installing and activating plugins, running database migrations, clearing caches, executing scheduled tasks, and inspecting system state. See [command reference guide](../../resources/references/core-reference/commands-reference.md). +* [Development Environment](./dev-environment.md) — Docker-based environment with an interactive terminal dashboard, log streaming, and runtime configuration +* `bin/console`: Shopware's built-in CLI, used for installing and activating plugins, running database migrations, clearing caches, executing scheduled tasks, and inspecting system state. See [command reference guide](../../resources/references/core-reference/commands-reference.md). You can run these from your host with `shopware-cli project console`. * The standalone [Shopware CLI](../../products/tools/cli/installation.md) supports project scaffolding, CI/CD workflows, automation tasks, and more. See the [helper commands guide](../../products/tools/cli/project-commands/helper-commands.md). * IDE support: Shopware provides a [PHPStorm plugin](tooling/shopware-toolbox.md) and [VS Code extension](https://marketplace.visualstudio.com/items?itemName=shopware.shopware-lsp). * [Deployment Helper](../hosting/installation-updates/deployments/deployment-helper.md): Supports database and maintenance operations for deployments (e.g., migrations, cache handling). @@ -88,4 +90,4 @@ The [troubleshooting](troubleshooting/index.md) guides provide reference informa ## Next steps -Move on to the [Start Developing guide](start-developing.md). +Set up your [Development Environment](./dev-environment.md), then move on to [Start Developing](./start-developing.md). diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md index f47ed3c302..72944e12f1 100644 --- a/guides/development/start-developing.md +++ b/guides/development/start-developing.md @@ -1,177 +1,146 @@ --- nav: title: Start Developing - position: 2 + position: 4 --- # Start Developing -This section outlines the typical next steps for development in your running Shopware instance. +This guide covers what to do once your [development environment](./dev-environment.md) is running. -## Access Administration and Storefront +## Your Environment -- Storefront: `http://127.0.0.1:8000` -- Administration: `http://127.0.0.1:8000/admin` *(default credentials: `admin` / `shopware`)* +Once the containers are up, you have: + +- **Storefront**: `http://127.0.0.1:8000` +- **Administration**: `http://127.0.0.1:8000/admin` *(default credentials: `admin` / `shopware`)* + +The DevTUI dashboard (`shopware-cli project dev`) shows these URLs and your credentials at a glance. Common development areas: -- `custom/`: your plugins and themes -- `bin/console`: application CLI (Symfony console) +- `custom/` — your plugins and themes +- `bin/console` — application CLI (Symfony console), runnable from your host via `shopware-cli project console` - the Administration UI -Projects follow the [project template layout](../installation/project-overview.md). - -## Using the Development Environment +## Running Commands -Shopware CLI provides an integrated Docker-based development environment with an interactive terminal dashboard. From your project root: +Use `shopware-cli project console` to run `bin/console` commands from your host — no need to enter the container: ```bash -# Launch the interactive DevTUI dashboard -shopware-cli project dev - -# Or start the environment in the background -shopware-cli project dev start -``` +# Clear caches +shopware-cli project console cache:clear -The dashboard provides: +# Install and activate a plugin +shopware-cli project console plugin:install --activate MyPlugin -- An overview of your Shop and Admin URLs with credentials -- One-click Admin and Storefront watchers -- Real-time log streaming from `var/log/` and Docker containers -- PHP version and profiler configuration (xdebug, blackfire, tideways, etc.) -- Service discovery (Adminer, Mailpit, queue, etc.) - -See the [Development Environment guide](../../products/cli/project-commands/dev-environment.md) for full details. - -## Using `bin/console` for development - -To run commands, open a shell inside the web container: - -```bash -make shell +# Run database migrations +shopware-cli project console database:migrate --all ``` -This command drops you into the container’s terminal; you will see the prompt change. - -From inside the container, retrieve a list of commands with: - +:::info Legacy workflow +If your project uses the older `make`-based setup and you need to shell into the container manually: ```bash -bin/console +make shell +docker compose exec web bash ``` - -Tasks handled in `bin/console` include: - -- Installing and activating plugins -- Clearing caches -- Running migrations -- Adjusting system configuration -- Running plugin-related development tasks - -:::info -Inside the container, you only need `bin/console …`. But if you prefer to run commands from your host machine instead, you can use the full Docker prefix: `docker compose exec web bin/console cache:clear`. +Most tasks are now easier with `shopware-cli project console` and the DevTUI dashboard. ::: -## Administration setup tasks +## Frontend Development -- Open the **Admin** at `http://localhost:8000/admin` -- Sign in or create a Shopware account; this is necessary when you want to install Store extensions. -- Connect to the **Shopware Store** -- Install plugins or themes from the Store -- Configure payment methods if you need them (not required for local development) +When developing the Administration or Storefront, use watchers for Hot Module Replacement. Start them directly from the DevTUI General tab (key `1`), or from the command line: -Basic shop settings such as shop name, default language, and currency can be changed later in the Admin under **`Settings > Shop > Basic information`**. +```bash +# Administration (Vite HMR on port 5173) +shopware-cli project admin-watch -## Frontend development +# Storefront (webpack HMR on port 9998) +shopware-cli project storefront-watch +``` -Use these commands when developing or customizing the UI, including Storefront, Administration, or extensions that affect either one: +To only watch specific extensions: ```bash -# Build the administration (admin panel) -make build-administration - -# Build the storefront (shop frontend) -make build-storefront +shopware-cli project admin-watch --only-extensions MyPlugin,OtherPlugin +shopware-cli project storefront-watch --only-extensions MyPlugin,OtherPlugin +``` -# Start a watcher to rebuild the Administration automatically when files change -make watch-admin +To exclude specific extensions: -# Start a watcher for Storefront -make watch-storefront +```bash +shopware-cli project admin-watch --skip-extensions SomePlugin ``` -### Alternative: use Shopware CLI +For the Storefront watcher, the CLI prompts you to select a sales channel if one isn't configured. -If you prefer not to use `make`, you can use the [Shopware CLI](https://developer.shopware.com/docs/products/cli/) to build and watch the Administration and Storefront. Run the following commands: +When working with many third-party extensions, building only custom extensions speeds things up: ```bash -shopware-cli project admin-build -shopware-cli project storefront-build -shopware-cli project admin-watch -shopware-cli project storefront-watch +shopware-cli project storefront-build --only-custom-static-extensions +shopware-cli project admin-build --only-custom-static-extensions ``` -The `watch` commands monitor changes to the Administration and Storefront and automatically rebuild them. +For more details, see [Using Watchers](./tooling/using-watchers.md). -## Local environment overview +## Administration Setup -With Shopware running, your local setup includes: +When accessing the Administration for the first time: -- **Web service:** Serves the Storefront and the Administration. -- **Database (MariaDB):** Runs on port 3306 inside Docker. - - Internal hostname: `database`. - - Host access: `localhost:3306`, if you want to inspect the database directly. -- **Mailpit:** A local mail-testing tool available at `http://localhost:8025`. Use it to view emails sent by Shopware (e.g., registration or order confirmations) without an external mail server. -- **Adminer (database UI):** A lightweight web interface for viewing and editing your database, available at `http://localhost:8080`. +- Sign in or create a Shopware account (required to install Store extensions) +- Connect to the **Shopware Store** +- Install plugins or themes from the Store +- Configure payment methods if needed -For Docker setups, inspect ports and services with: +Basic shop settings (name, language, currency) can be changed later under **Settings > Shop > Basic information**. -```bash -docker compose ps -``` +## Environment Customization -## Environment setup +### compose.override.yaml -### Connecting to a remote database +The `compose.yaml` file is managed by shopware-cli and regenerated automatically. Place all customizations in `compose.override.yaml`: -To use a database outside the Docker stack, set `DATABASE_URL` in `.env.local` in the standard form: +```yaml +# compose.override.yaml +services: + web: + environment: + APP_ENV: dev + ports: + - "9003:9003" # Xdebug -```bash -DATABASE_URL="mysql://user:password@:3306/" + database: + ports: + - "3306:3306" # Expose MySQL to host ``` -Containers cannot always reach services bound only to the host's `localhost`. If `localhost` does not work, try `host.docker.internal` or your host machine’s LAN IP, or add an `extra_hosts` entry in `compose.yaml`. - -### Environment variables +### Connecting to a Remote Database -You can create a `.env` file in the project root to override default environment variables. Most changes take effect automatically without requiring container restarts. Changes to `APP_ENV` require a restart: +To use an external database, set `DATABASE_URL` in `.env.local`: ```bash -make up +DATABASE_URL="mysql://user:password@:3306/" ``` -### Docker overrides - -Use `compose.override.yaml` to: +If the container can't reach `localhost`, try `host.docker.internal` or your host's LAN IP. -- Change ports -- Add services -- Enable debugging -- Adjust networking +### Environment Variables -This keeps your changes local and out of version control. +Create a `.env` file in the project root to override defaults. Most changes apply immediately. Changes to `APP_ENV` require a restart (`shopware-cli project dev stop && shopware-cli project dev start`). -## Shopware account and Composer (private packages) +## Shopware Account and Private Composer Packages -Shopware operates a private Composer registry for licensed and commercial extensions. To install packages that require Shopware account authentication, configure Composer with your Shopware account credentials (create an access token in your Shopware account when prompted): +To install licensed extensions from Shopware's private Composer registry: ```bash composer config --global http-basic.packages.shopware.com ``` -Use the hostname and steps described in your Shopware account or in the extension download instructions, if they differ. +Create an access token in your Shopware account under **Shops > Licenses**. -## Next steps +## Next Steps -- Build extensions: [Extensions](extensions/index.md). -- Integrate via HTTP: [APIs](integrations-api/index.md). +- [Build Extensions](./extensions/index.md) — Create plugins, apps, and themes +- [Work with APIs](./integrations-api/index.md) — Integrate external systems +- [Set up CI/CD](../../products/tools/cli/project-commands/build.md) — Automate builds and deployments diff --git a/guides/development/tooling/index.md b/guides/development/tooling/index.md index 85f9ed9ef1..7c774c08f3 100644 --- a/guides/development/tooling/index.md +++ b/guides/development/tooling/index.md @@ -9,6 +9,8 @@ nav: Shopware provides official tools that support the full lifecycle of a Shopware project, from development to deployment and long-term maintenance: +- [Development Environment](../dev-environment.md): The Docker-based development environment with an interactive terminal dashboard that manages your entire stack, streams logs, and controls watchers. + - [Admin Extension SDK](https://developer.shopware.com/resources/admin-extension-sdk/): an NPM library for Shopware 6 apps and plugins that need an easy way to extend or customize the Administration. - `bin/console`: Shopware's built-in CLI, used for installing and activating plugins, running database migrations, clearing caches, executing scheduled tasks, and inspecting system state. See [command reference guide](../../../resources/references/core-reference/commands-reference.md). diff --git a/guides/installation/index.md b/guides/installation/index.md index 8f8fb3897f..3b367da26d 100644 --- a/guides/installation/index.md +++ b/guides/installation/index.md @@ -76,57 +76,32 @@ If the summary looks good, choose `proceed` to start the process of setting up S When it finishes, users who did not install with Docker will receive guidance to continue. -### Finish Docker setup (optional) +### Start your development environment -When setup finishes, users who installed with Docker will see this prompt: - -- Start containers: `cd && make up` -- Set up Shopware: `make setup` -- Stop containers: `make down` (do this later) - -Running `make up` starts Shopware and all required services (web server, database, search, Mailpit, etc.) in the background. Docker images already include all required PHP extensions and services, so the system-check step of the installer is always fulfilled. - -Running `make setup` is necessary to access the new shop. - -:::info -What happens during `make setup`: - -- The Makefile runs the Shopware installer inside the web container -- Shopware is installed automatically (no browser wizard required) -- A MariaDB database is created -- An admin user is created, with username `admin` and password `shopware` -- Required services (database, search, mail, etc.) are preconfigured and run inside Docker -- The Shopware project is configured to connect to the database via the Docker service name `database` -- Database credentials are defined in the `compose.yaml` -- If Elasticsearch was enabled during project creation, a compatible search service runs as part of the Docker stack. -::: - -Check the container status anytime with the following command: +Once the project is created, start the development environment with: ```bash -docker compose ps +cd my-shop +shopware-cli project dev ``` -### Accessing the new shop (all setups) +This launches the interactive **DevTUI** dashboard. The dashboard starts your Docker containers, runs the Shopware installer (first time only), and gives you an overview of your environment — Shop URLs, credentials, watchers, logs, and service configuration — all in one place. -The prompt also provides links to access the new shop in the browser: +For details, see the [Development Environment guide](../development/dev-environment.md). -- Storefront: [http://127.0.0.1:8000](http://127.0.0.1:8000) -- Admin: [http://127.0.0.1:8000/admin](http://127.0.0.1:8000/admin) -- Credentials: `admin` / `shopware` +### Accessing your shop -Users who do not install with Docker can also use the Storefront and Administration URLs to continue. +When the environment is running, your shop is accessible at: -If you're setting up Shopware for the very first time, you may prefer to complete Shopware installation from the Administration UI using the First Run Wizard: - -- Sign in or create a Shopware account; this is necessary when you want to install Store extensions -- Connect to the **Shopware Store** -- Install plugins or themes from the Store -- Configure payment methods if you need them (not required for local development) +- Storefront: [http://127.0.0.1:8000](http://127.0.0.1:8000) +- Admin: [http://127.0.0.1:8000/admin](http://127.0.0.1:8000/admin) +- Default credentials: `admin` / `shopware` -Basic shop settings such as shop name, default language, and currency can be changed later in the Admin under **`Settings > Shop > Basic information`**. +Check container status anytime with: -However, most developers will want to continue from the terminal. +```bash +docker compose ps +``` ### Next steps diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md index 4a2abd61a9..dba39aac65 100644 --- a/guides/installation/project-overview.md +++ b/guides/installation/project-overview.md @@ -11,19 +11,27 @@ You have just installed Shopware, and this section guides you through the fundam ## Development tooling -The Docker setup provisions Shopware for development. Development tools such as: +The Docker setup provisions Shopware for development. The recommended way to manage your environment is through the [Development Environment](../development/dev-environment.md) dashboard (`shopware-cli project dev`), which provides: + +- One-command start/stop of the entire stack +- Real-time log streaming from `var/log/` and Docker containers +- Admin and Storefront watchers (HMR) +- PHP version and profiler configuration (xdebug, blackfire, tideways, etc.) +- Service discovery (Adminer, Mailpit, queue, etc.) + +Development tools such as: - [`shopware/dev-tools`](https://github.com/shopware/dev-tools) - [Symfony profiler]( https://symfony.com/doc/current/profiler.html) (**only in development mode**) - linting and testing tools -are managed via the Shopware CLI. These are installed into the user’s environment and shared across projects and extensions, rather than being added as project-level `require-dev` dependencies. +are managed via the Shopware CLI. These are installed into the user's environment and shared across projects and extensions, rather than being added as project-level `require-dev` dependencies. [Demo data](https://github.com/shopware/SwagPlatformDemoData) is optional and can be installed during the in-browser first-run wizard. Your local project is ready for debugging, profiling, and extension development out of the box. -In day-to-day development, you’ll mostly interact with: +In day-to-day development, you'll mostly interact with: - **Makefile**: shortcuts for Docker and Shopware commands (`make up`, `make setup`, etc.) - **custom/**: where you build your own plugins and themes @@ -54,7 +62,7 @@ Container names depend on the name of your project folder. | Name | Type | Purpose | |---------------------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------| | **Network `my-project_default`** | Docker network | A private virtual network so all containers can communicate (for example, the web container connects to the database). | -| **Volume `my-project_db-data`** | Persistent storage | Stores the MariaDB database files so your data isn’t lost when containers are stopped or rebuilt. | +| **Volume `my-project_db-data`** | Persistent storage | Stores the MariaDB database files so your data isn't lost when containers are stopped or rebuilt. | | **Container `my-project-mailer-1`** | Mailpit service | Captures outgoing emails for local testing. View at `http://localhost:8025`. | | **Container `my-project-database-1`** | MariaDB service | Runs the Shopware database. Inside the Docker network, its hostname is `database`. | | **Container `my-project-web-1`** | PHP + Caddy web service | Runs Shopware itself and serves the storefront and Admin UI at `http://localhost:8000`. | @@ -91,17 +99,17 @@ This table outlines the key directories and files in your Shopware project and t | Item | Type | Purpose / what it contains | Notes | |---------------------------|-----------------------------|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| -| **bin/** | Directory | Executable scripts (e.g., `bin/console` — the main CLI for Shopware/Symfony). | Think of it like `npm run` or `go run` scripts. Use `bin/console` to run commands inside the app. | -| **compose.yaml** | Docker | Defines the Docker services (web, database, mailpit, etc.). | Equivalent to your project’s “infrastructure recipe.” | +| **bin/** | Directory | Executable scripts (e.g., `bin/console` - the main CLI for Shopware/Symfony). | Think of it like `npm run` or `go run` scripts. Use `bin/console` to run commands inside the app. | +| **compose.yaml** | Docker | Defines the Docker services (web, database, mailpit, etc.). | Equivalent to your project's "infrastructure recipe." | | **compose.override.yaml** | Docker | Local overrides for the default Docker Compose stack (e.g., port mappings, extra volumes). | Optional; used to customize or extend services locally. | | **composer.json** | PHP dependency manifest | Lists PHP dependencies and metadata (like `package.json`). | `composer install` reads this. | -| **composer.lock** | Dependency lock file | Locks exact versions of PHP packages. | Don’t edit manually; committed to git. | +| **composer.lock** | Dependency lock file | Locks exact versions of PHP packages. | Don't edit manually; committed to git. | | **config/** | Directory | Symfony configuration files (framework, database, mail, etc.). | Similar to `config/` in many web frameworks. | -| **custom/** | Directory | Your plugins, themes, or app customizations. | This is where you add new extensions — your “src” for Shopware plugins. | +| **custom/** | Directory | Your plugins, themes, or app customizations. | This is where you add new extensions - your "src" for Shopware plugins. | | **files/** | Directory | Uploaded media and temporary files. | Ignored by git; generated at runtime. | | **Makefile** | Build helper | Shortcuts for Docker tasks (`make up`, `make setup`, etc.). | Replaces long Docker commands with memorable aliases. | | **public/** | Web root | The actual web-server-accessible directory (contains `index.php`, assets, etc.). | Like `/dist` in JS frameworks or `/public_html`. | -| **src/** | Source code | Shopware’s core application source. | Where the main PHP codebase lives; not usually edited in a project clone. | +| **src/** | Source code | Shopware's core application source. | Where the main PHP codebase lives; not usually edited in a project clone. | | **symfony.lock** | Symfony dependency snapshot | Records Symfony recipes applied during setup. | Used internally by Symfony Flex; no manual editing. | | **var/** | Runtime data | Cache, logs, temporary files. | Can safely be deleted (Shopware rebuilds it). | | **vendor/** | Dependency code | All installed PHP libraries from Composer. | Analogous to `node_modules/`. | diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md index 3f25416ea4..d91e44f787 100644 --- a/products/tools/cli/project-commands/dev-environment.md +++ b/products/tools/cli/project-commands/dev-environment.md @@ -5,284 +5,72 @@ nav: --- -# Development Environment +# Development Environment (CLI Reference) -Starting with compatibility date `2026-03-01`, Shopware CLI provides a fully integrated development environment powered by Docker. It replaces manual `docker compose` workflows with a single command and an interactive terminal dashboard. +This page is a quick reference for the `shopware-cli project dev` and `shopware-cli project logs` commands. For the full development workflow and setup guide, see [Development Environment](../../guides/development/dev-environment.md). -## Quick Start +## Commands -From your Shopware project root, run: +### Start the Environment ```bash +# Interactive dashboard (default when run in a terminal) shopware-cli project dev -``` - -This launches the interactive **DevTUI** dashboard, which manages your environment lifecycle, displays service information, streams logs, and lets you configure PHP and profiling settings — all through a terminal interface. - -### For projects without a dev environment - -If your project doesn't yet have a development environment configured (compatibility date before `2026-03-01`), running `shopware-cli project dev` automatically starts the **setup wizard**. The wizard: - -- Collects your Shop URL, admin credentials, PHP version, and profiler preference -- Adds `shopware/deployment-helper` to your `composer.json` if missing -- Updates `.shopware-project.yml` with environment and Docker configuration -- Generates `compose.yaml` and starts the Docker environment - -## Background Usage -If you're running in CI or prefer not to use the interactive dashboard, you can start and stop the environment in the background: - -```bash -# Start the environment (non-interactive) +# Start in the background (for CI or scripting) shopware-cli project dev start # Stop the environment shopware-cli project dev stop ``` -The `start` command prints the Shop and Admin URLs, any auxiliary services, and hints for stopping and viewing logs. - -## DevTUI Dashboard - The interactive dashboard has three tabs: +- **General** — environment overview, URLs, credentials, watchers, services +- **Logs** — real-time log streaming from `var/log/`, watchers, and Docker +- **Config** — PHP version, profiler, and credential management -### General Tab - -Displays an overview of your running environment: - -- **Environment type** (docker, local, symfony-cli) -- **Shop URL** and **Admin URL** with admin credentials -- **Watchers** — start Admin and Storefront watchers directly from the dashboard -- **Services** — auto-discovered auxiliary services (Adminer, Mailpit, queue, etc.) - -### Logs Tab - -Real-time log streaming from your Shopware application. The tab shows: - -- **Log files from `var/log/`** — the most recently modified file is selected by default -- **Watcher output** — live output from running Admin and Storefront watchers -- **Docker container logs** — `docker compose logs` output from the web container - -Use the sidebar to switch between log sources. Press `f` to toggle follow mode. - -### Config Tab - -Adjust your Docker development environment without manually editing YAML files: - -| Setting | Options | -|---------|---------| -| **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 (Server ID/Token or API Key). Sensitive credentials are stored in `.shopware-project.local.yml`, which is excluded from version control. - -After changing settings, select **Save & Regenerate** to update `compose.yaml` with the new configuration. Restart Docker for changes to take effect. - -## Viewing Application Logs - -The `shopware-cli project logs` command lets you inspect Shopware application logs without opening the dashboard: +### View Application Logs ```bash -# Show last 100 lines of the most recently modified log file +# Last 100 lines of the most recently modified log file shopware-cli project logs -# Show a specific log file +# A specific log file shopware-cli project logs dev-2026-05-18.log -# Follow the log (like tail -f) +# Follow the log in real time shopware-cli project logs -f # List available log files shopware-cli project logs -l -# Show a custom number of lines +# Set number of lines to show (default: 100) shopware-cli project logs --lines 50 ``` -## Docker Services - -The development environment automatically generates a `compose.yaml` file with the following services: - -| Service | Description | URL (default) | -|---------|-------------|---------------| -| **web** | PHP + Node.js application server (Caddy) | `http://127.0.0.1:8000` | -| **database** | MariaDB 11.8 database | internal only | -| **adminer** | Web-based database management | `http://127.0.0.1:9080` | -| **mailer** | Mailpit email testing tool | `http://127.0.0.1:8025` | -| **lavinmq** | Message queue (auto-detected from `composer.lock`) | `http://127.0.0.1:15672` | -| **opensearch** | Search engine (auto-detected from `composer.lock`) | `http://127.0.0.1:9200` | -| **blackfire** | Blackfire profiler agent (when profiler is configured) | internal only | -| **tideways-daemon** | Tideways profiler agent (when profiler is configured) | internal only | - -The `compose.yaml` file is **managed by shopware-cli** and regenerated when you change configuration. Never edit this file directly — your changes will be overwritten the next time the CLI regenerates it (for example, after changing PHP version or profiler settings in the Config tab, or after running `shopware-cli project dev`). - -### Customizing with compose.override.yaml - -To extend or override any service, create a `compose.override.yaml` file in your project root. Docker Compose [merges multiple compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/), so your overrides are applied on top of the managed `compose.yaml`. This file is yours to own and should be committed to version control. - -**Common use cases:** - -```yaml -# compose.override.yaml — customize without modifying the managed file - -services: - web: - # Add extra environment variables - environment: - APP_ENV: dev - COMPOSER_HOME: /tmp/composer - - # Expose additional ports (e.g., for debugging) - ports: - - "9003:9003" # Xdebug - - # Mount additional volumes (e.g., custom extensions) - volumes: - - ./custom/extensions:/var/www/html/custom/extensions - - database: - # Persist database data to a named volume - volumes: - - db-data:/var/lib/mysql - - # Add your own services - redis: - image: redis:7-alpine - ports: - - "6379:6379" - -volumes: - db-data: -``` - -The CLI-generated `compose.yaml` includes this header for clarity: - -```yaml -# This file is managed by shopware-cli. Do not edit manually. -# Create a compose.override.yaml to customize services. -# See https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/ -``` - -### Auto-Detection - -The compose file is generated based on your project's `composer.lock`: - -- If `symfony/amqp-messenger` is installed, a **LavinMQ** queue service is added and `MESSENGER_TRANSPORT_DSN` is configured -- If `shopware/elasticsearch` is installed, an **OpenSearch** service is added with corresponding environment variables -- The **PHP version** defaults to `8.3` unless overridden in the Config tab - -## Environment Executors - -Shopware CLI abstracts command execution across different environment types: - -| Type | Description | -|------|-------------| -| `docker` | Executes commands inside the web container via `docker compose exec` | -| `local` | Executes commands directly on the host machine | -| `symfony-cli` | Uses the Symfony CLI binary for command execution (auto-detected) | - -The executor type is configured per environment in `.shopware-project.yml`: - -```yaml -environments: - local: - type: docker - url: http://127.0.0.1:8000 - admin_api: - username: admin - password: shopware -``` - -When no environment is specified, Shopware CLI looks for a `local` environment first, then falls back to a local executor using the top-level `url` and `admin_api` configuration. +## Configuration -## Configuration Reference - -### .shopware-project.yml +The environment is configured in `.shopware-project.yml`. See the [full configuration reference](../../guides/development/dev-environment.md#configuration-reference) for all options. ```yaml -# Required to enable the development environment +# .shopware-project.yml compatibility_date: '2026-03-01' -# Top-level URL (used as fallback when no environment is specified) -url: http://127.0.0.1:8000 - -# Docker development environment configuration docker: php: - version: "8.3" # PHP version: 8.2, 8.3, 8.4, 8.5 - profiler: xdebug # Profiler: none (empty), xdebug, blackfire, tideways, pcov, spx - blackfire_server_id: "" # Required when profiler is blackfire - blackfire_server_token: "" # Required when profiler is blackfire - tideways_api_key: "" # Required when profiler is tideways + version: "8.3" + profiler: xdebug -# Named environments environments: local: - type: docker # docker, local, or symfony-cli + type: docker url: http://127.0.0.1:8000 admin_api: username: admin password: shopware ``` -### .shopware-project.local.yml - -Sensitive credentials (Blackfire server ID/token, Tideways API key) are stored in `.shopware-project.local.yml`. This file is intended to be added to `.gitignore`: - -```yaml -docker: - php: - blackfire_server_id: "your-server-id" - blackfire_server_token: "your-server-token" -``` - -### compose.yaml (managed) - -The generated `compose.yaml` is owned and regenerated by shopware-cli. **Do not edit it manually** — your changes will be overwritten. Use `compose.override.yaml` for all customizations. - -```yaml -# compose.override.yaml -services: - web: - ports: - - "8080:8080" # Add additional ports - environment: - APP_ENV: dev -``` - -## Ports - -The web container exposes these ports by default: - -| Port | Purpose | -|------|---------| -| `8000` | Shopware Storefront | -| `8080` | HTTP (alternative) | -| `5173` | Admin Watcher (Vite) | -| `9998` | Storefront Watcher (webpack/Node) | -| `9999` | Storefront Proxy | -| `5773` | IDE debugging | - -## Troubleshooting - -### The compose.yaml file keeps getting reset - -This is by design. The `compose.yaml` file is **fully managed** by shopware-cli and is regenerated whenever configuration changes (PHP version, profiler) or when the dev environment starts. **Never edit `compose.yaml` directly.** Instead, place all customizations in `compose.override.yaml` — Docker Compose merges it with the managed file automatically. See the [Customizing with compose.override.yaml](#customizing-with-composeoverrideyaml) section for examples. - -### Container won't start - -Check the application logs with `shopware-cli project logs -f` or from within the DevTUI Logs tab. - -### Shopware isn't installed yet - -When the environment starts and Shopware is not installed, the DevTUI prompts you to run the installer. Provide your preferred locale, currency, and admin credentials. The installer uses `shopware/deployment-helper` under the hood. - -### Compatibility date is not set - -If you see an error about the compatibility date, set it in `.shopware-project.yml`: - -```yaml -compatibility_date: '2026-03-01' -``` +## Further Reading -For more context on compatibility dates, see the [Build command documentation](./build.md#compatibility-date). +- [Development Environment guide](../../guides/development/dev-environment.md) — full workflow, setup wizard, service overview, troubleshooting +- [Start Developing](../../guides/development/start-developing.md) — next steps after your environment is running diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index dbebe6f3e3..92663d3367 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/products/tools/cli/project-commands/helper-commands.md @@ -27,7 +27,7 @@ The version parameter can be also `latest` for the latest stable version or `dev ## Development Environment -Shopware CLI provides a fully integrated Docker-based development environment. See the [Development Environment](./dev-environment.md) guide for details. +Shopware CLI provides a fully integrated Docker-based development environment. See the [Development Environment](../../../guides/development/dev-environment.md) guide for the full workflow, or the [CLI command reference](./dev-environment.md) for a quick overview. ```bash # Launch the interactive dashboard From e924682b037016c528bc09fbbceb6e52138a801b Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Mon, 18 May 2026 07:25:53 +0200 Subject: [PATCH 04/37] chore: add new terms to spellcheck wordlist, fix markdown linting - Added DevTUI, LavinMQ, lavinmq, adminer, keypress, overridable, runnable, xdebug to .wordlist.txt - Fixed markdown linting: blank lines before code blocks and lists --- .wordlist.txt | 8 ++++++++ guides/development/start-developing.md | 2 ++ products/tools/cli/project-commands/dev-environment.md | 1 + 3 files changed, 11 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 7199f5a5db..77d9931c28 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -332,6 +332,7 @@ Deployer Deprecations Deutsch DevOps +DevTUI DevTools Devenv DeviceHelper @@ -536,6 +537,7 @@ LONGTEXT LUA LandingPage LastNameRule +LavinMQ Lerna Lifecycle LineItemClearanceSaleRule @@ -1174,6 +1176,7 @@ actionAmount actionType actionability activateShopwareTheme +adminer adr afterSort ag @@ -1629,8 +1632,10 @@ jwks jwt kebabCase keyframes +keypress landingpage lang +lavinmq lazysizes libxml lifecycle @@ -1754,6 +1759,7 @@ org's organizationUnitIds otel otlp +overridable overrideComponentSetup oversales paas @@ -1895,6 +1901,7 @@ rollout routeName routeScope routeScopes +runnable runtime runtimes salesChannel @@ -2131,6 +2138,7 @@ wishlist wordlist www xasjkyld +xdebug xhost's xkeys xl diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md index 72944e12f1..11707c82ee 100644 --- a/guides/development/start-developing.md +++ b/guides/development/start-developing.md @@ -41,10 +41,12 @@ shopware-cli project console database:migrate --all :::info Legacy workflow If your project uses the older `make`-based setup and you need to shell into the container manually: + ```bash make shell docker compose exec web bash ``` + Most tasks are now easier with `shopware-cli project console` and the DevTUI dashboard. ::: diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md index d91e44f787..ac12d788c0 100644 --- a/products/tools/cli/project-commands/dev-environment.md +++ b/products/tools/cli/project-commands/dev-environment.md @@ -25,6 +25,7 @@ shopware-cli project dev stop ``` The interactive dashboard has three tabs: + - **General** — environment overview, URLs, credentials, watchers, services - **Logs** — real-time log streaming from `var/log/`, watchers, and Docker - **Config** — PHP version, profiler, and credential management From 4ab0c304cbed76baf2fe0c1a879d09e3f39bf8ff Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Mon, 18 May 2026 07:41:59 +0200 Subject: [PATCH 05/37] docs: expand setup wizard into full migration guide for legacy projects Replace the brief 'Setup Wizard' section with a comprehensive 'Migrating from Legacy Setups' guide that explains: - What triggers the wizard (compatibility date before 2026-03-01) - Step-by-step walkthrough of each wizard screen - What files are created, updated, or replaced (with a table) - What happens to existing compose.yaml and Makefile - Post-migration steps (composer install if needed, moving customizations to compose.override.yaml) --- guides/development/dev-environment.md | 54 ++++++++++++++++--- .../cli/project-commands/dev-environment.md | 8 +-- .../cli/project-commands/helper-commands.md | 2 +- 3 files changed, 52 insertions(+), 12 deletions(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index b69f0d8e65..41e45744c1 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -71,15 +71,55 @@ When selecting `blackfire` or `tideways`, additional credential fields appear. S After changing settings, select **Save & Regenerate** to update `compose.yaml`. Restart the environment for changes to take effect. -## Setup Wizard +## Migrating from Legacy Setups -If your project doesn't have a development environment configured (compatibility date before `2026-03-01`), running `shopware-cli project dev` starts the setup wizard instead. The wizard: +If your project was created before March 2026 and uses the older `make up`/`make setup` workflow with a hand-written `compose.yaml`, running `shopware-cli project dev` automatically detects this and launches a **setup wizard** instead of the dashboard. -1. Collects your Shop URL, admin username/password, PHP version, and profiler choice -2. Resolves compatible PHP versions from your `composer.lock` -3. Adds `shopware/deployment-helper` to `composer.json` if missing -4. Writes the environment configuration to `.shopware-project.yml` -5. Generates `compose.yaml` and starts the Docker environment +### 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. + +### 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` +4. **PHP version** — reads your `composer.lock` to determine compatible PHP versions and offers the highest supported one as the default (e.g., `8.4`) +5. **Profiler** — choose from `none`, `xdebug`, `blackfire`, `tideways`, `pcov`, or `spx` +6. **Review** — shows a summary of all your choices before applying changes + +After you confirm, the wizard: + +- Sets `compatibility_date` to `2026-03-01` in `.shopware-project.yml` +- Adds a `local` environment with type `docker` and your chosen URL/credentials +- Configures the Docker PHP version and profiler settings +- Writes profiler secrets (Blackfire credentials, Tideways API key) to `.shopware-project.local.yml` +- 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 — back it up first if you have customizations you want to port 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` | + +### After the Wizard Completes + +If `shopware/deployment-helper` was added to `composer.json`, you'll be prompted to run: + +```bash +composer install +``` + +This pulls in the helper package, which the dashboard uses to run the Shopware installer. After that, the environment starts automatically. + +Once migrated, the legacy `make up`/`make down`/`make setup` workflow is no longer needed — use `shopware-cli project dev` to manage your environment instead. If you had customizations in your old `compose.yaml`, move them to `compose.override.yaml` before running the wizard (or recover them from git afterwards). ## Viewing Application Logs diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md index ac12d788c0..b646365cd5 100644 --- a/products/tools/cli/project-commands/dev-environment.md +++ b/products/tools/cli/project-commands/dev-environment.md @@ -7,7 +7,7 @@ nav: # Development Environment (CLI Reference) -This page is a quick reference for the `shopware-cli project dev` and `shopware-cli project logs` commands. For the full development workflow and setup guide, see [Development Environment](../../guides/development/dev-environment.md). +This page is a quick reference for the `shopware-cli project dev` and `shopware-cli project logs` commands. For the full development workflow and setup guide, see [Development Environment](../../../../guides/development/dev-environment.md). ## Commands @@ -51,7 +51,7 @@ shopware-cli project logs --lines 50 ## Configuration -The environment is configured in `.shopware-project.yml`. See the [full configuration reference](../../guides/development/dev-environment.md#configuration-reference) for all options. +The environment is configured in `.shopware-project.yml`. See the [full configuration reference](../../../../guides/development/dev-environment.md#configuration-reference) for all options. ```yaml # .shopware-project.yml @@ -73,5 +73,5 @@ environments: ## Further Reading -- [Development Environment guide](../../guides/development/dev-environment.md) — full workflow, setup wizard, service overview, troubleshooting -- [Start Developing](../../guides/development/start-developing.md) — next steps after your environment is running +- [Development Environment guide](../../../../guides/development/dev-environment.md) — full workflow, setup wizard, service overview, troubleshooting +- [Start Developing](../../../../guides/development/start-developing.md) — next steps after your environment is running diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index 92663d3367..a9b2dc341c 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/products/tools/cli/project-commands/helper-commands.md @@ -27,7 +27,7 @@ The version parameter can be also `latest` for the latest stable version or `dev ## Development Environment -Shopware CLI provides a fully integrated Docker-based development environment. See the [Development Environment](../../../guides/development/dev-environment.md) guide for the full workflow, or the [CLI command reference](./dev-environment.md) for a quick overview. +Shopware CLI provides a fully integrated Docker-based development environment. See the [Development Environment](../../../../guides/development/dev-environment.md) guide for the full workflow, or the [CLI command reference](./dev-environment.md) for a quick overview. ```bash # Launch the interactive dashboard From 7fb3561452a024a356f4a6ced0a4102eb9a151f8 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Tue, 30 Jun 2026 11:53:11 +0200 Subject: [PATCH 06/37] docs(cli): document dev status command --- guides/development/dev-environment.md | 6 ++++++ products/tools/cli/project-commands/dev-environment.md | 3 +++ products/tools/cli/project-commands/helper-commands.md | 1 + 3 files changed, 10 insertions(+) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 41e45744c1..544e1cb714 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -29,6 +29,12 @@ To start without the interactive dashboard (for CI or scripting): shopware-cli project dev start ``` +To check whether the environment is running: + +```bash +shopware-cli project dev status +``` + To stop everything: ```bash diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md index b646365cd5..82608122af 100644 --- a/products/tools/cli/project-commands/dev-environment.md +++ b/products/tools/cli/project-commands/dev-environment.md @@ -20,6 +20,9 @@ shopware-cli project dev # Start in the background (for CI or scripting) shopware-cli project dev start +# Check whether the environment is running +shopware-cli project dev status + # Stop the environment shopware-cli project dev stop ``` diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index a9b2dc341c..75f3a0c771 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/products/tools/cli/project-commands/helper-commands.md @@ -35,6 +35,7 @@ shopware-cli project dev # Start/stop in the background shopware-cli project dev start +shopware-cli project dev status shopware-cli project dev stop # View application logs From 830956adfcc3a07024b46f7978c027b6c1ba8681 Mon Sep 17 00:00:00 2001 From: Tomasz Turkowski Date: Tue, 7 Jul 2026 12:41:26 +0200 Subject: [PATCH 07/37] Updates to docs --- guides/development/dev-environment.md | 45 ++++++++++--------- guides/development/start-developing.md | 6 +-- guides/development/tooling/index.md | 2 +- guides/installation/project-overview.md | 4 +- .../cli/project-commands/dev-environment.md | 6 +-- .../cli/project-commands/helper-commands.md | 6 +-- 6 files changed, 37 insertions(+), 32 deletions(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 544e1cb714..294c872866 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -43,26 +43,31 @@ shopware-cli project dev stop ## DevTUI Dashboard -The dashboard has three tabs, switched with the number keys or by clicking: +The dashboard has three tabs, switched with the number keys: -### General Tab (1) +### Overview Tab (1) Your environment at a glance: -- **Environment type** — docker, local, or symfony-cli -- **Shop and Admin URLs** with credentials for quick access -- **Watchers** — start Admin (Vite HMR on port `5173`) and Storefront (webpack HMR on port `9998`) watchers with one keypress -- **Services** — auto-discovered auxiliary services like Adminer, Mailpit, and message queues +**Left panel:** -### Logs Tab (2) +- **Shop** — Shopware version, environment type (`docker`, `local`, or `symfony-cli`), shop and admin URLs, and security update expiry date +- **Access** — URLs, usernames, and passwords for Shop Admin, Adminer, and Mailpit +- **Setup health** — runtime checks (PHP version, memory limit), local behavior warnings, and debug settings, each showing the current value against the recommended one -Real-time log streaming from multiple sources: +**Right panel:** -- **Application logs** from `var/log/` — most recently modified file selected by default -- **Watcher output** — live build output from Admin and Storefront watchers -- **Docker logs** — `docker compose logs` from the web container +- **Watchers** — toggle Admin and Storefront watchers on or off -Use the sidebar to switch sources. Toggle follow mode with `f`. +### Instance Tab (2) + +Browse and stream logs from your running environment: + +- **Containers** — all Docker containers with a live status indicator for the active one +- **Processes** — watcher processes (Admin Watcher, Storefront Watcher) when running +- **Log files** — application log files (e.g., `dev.log`) + +Use `↑`/`↓` to navigate sources and `enter` to select one. Scroll with `pgup`/`pgdn`. ### Config Tab (3) @@ -92,16 +97,14 @@ Walking through the setup wizard takes about a minute. Here's what happens at ea 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` -4. **PHP version** — reads your `composer.lock` to determine compatible PHP versions and offers the highest supported one as the default (e.g., `8.4`) -5. **Profiler** — choose from `none`, `xdebug`, `blackfire`, `tideways`, `pcov`, or `spx` -6. **Review** — shows a summary of all your choices before applying changes +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`) +5. **Review** — shows a summary of all your choices before applying changes After you confirm, the wizard: - Sets `compatibility_date` to `2026-03-01` in `.shopware-project.yml` - Adds a `local` environment with type `docker` and your chosen URL/credentials -- Configures the Docker PHP version and profiler settings -- Writes profiler secrets (Blackfire credentials, Tideways API key) to `.shopware-project.local.yml` +- 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 @@ -111,7 +114,7 @@ After you confirm, the wizard: |------|-------------| | `.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 — back it up first if you have customizations you want to port to `compose.override.yaml` | +| `compose.yaml` | **Replaced** with the CLI-managed version. Your old file is overwritten — back it up first. 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` | @@ -177,7 +180,9 @@ The CLI generates a `compose.yaml` tailored to your project: \* *Auto-detected from `composer.lock` or enabled via configuration.* -The `compose.yaml` file is **fully managed by shopware-cli** and regenerated whenever you change configuration. **Never edit it directly.** +::: warning +`compose.yaml` is fully managed by shopware-cli and regenerated whenever you change configuration. Never edit it directly — your changes will be overwritten. +::: ### Customizing with compose.override.yaml @@ -293,7 +298,7 @@ This is by design. `compose.yaml` is fully managed and regenerated on config cha ### Containers won't start -Check logs with `shopware-cli project logs -f` or from the Logs tab in the dashboard. +Check logs with `shopware-cli project logs -f` or from the Instance tab in the dashboard. ### Shopware isn't installed diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md index 11707c82ee..ab4127be5f 100644 --- a/guides/development/start-developing.md +++ b/guides/development/start-developing.md @@ -22,7 +22,7 @@ Common development areas: - `custom/` — your plugins and themes - `bin/console` — application CLI (Symfony console), runnable from your host via `shopware-cli project console` -- the Administration UI +- The Administration UI ## Running Commands @@ -52,7 +52,7 @@ Most tasks are now easier with `shopware-cli project console` and the DevTUI das ## Frontend Development -When developing the Administration or Storefront, use watchers for Hot Module Replacement. Start them directly from the DevTUI General tab (key `1`), or from the command line: +When developing the Administration or Storefront, use watchers for Hot Module Replacement. Start them directly from the DevTUI Overview tab (key `1`), or from the command line: ```bash # Administration (Vite HMR on port 5173) @@ -75,7 +75,7 @@ To exclude specific extensions: shopware-cli project admin-watch --skip-extensions SomePlugin ``` -For the Storefront watcher, the CLI prompts you to select a sales channel if one isn't configured. +For the Storefront Watcher, the CLI prompts you to select a sales channel if one isn't configured. When working with many third-party extensions, building only custom extensions speeds things up: diff --git a/guides/development/tooling/index.md b/guides/development/tooling/index.md index 7c774c08f3..594b7373a2 100644 --- a/guides/development/tooling/index.md +++ b/guides/development/tooling/index.md @@ -15,7 +15,7 @@ Shopware provides official tools that support the full lifecycle of a Shopware p - `bin/console`: Shopware's built-in CLI, used for installing and activating plugins, running database migrations, clearing caches, executing scheduled tasks, and inspecting system state. See [command reference guide](../../../resources/references/core-reference/commands-reference.md). -- [Deployment Helper](../../hosting/installation-updates/deployments/deployment-helper.md): Supports database and maintenance operations for deployments (e.g., migrations, cache handling). +- [Deployment Helper](../../hosting/installation-updates/deployments/deployment-helper.md): Supports database and maintenance operations for deployments (e.g., migrations, cache handling). - [Fixture Bundle](../../../guides/development/tooling/fixture-bundle.md): Seed development environments with demo and test data. diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md index dba39aac65..8bf542bafd 100644 --- a/guides/installation/project-overview.md +++ b/guides/installation/project-overview.md @@ -15,7 +15,7 @@ The Docker setup provisions Shopware for development. The recommended way to man - One-command start/stop of the entire stack - Real-time log streaming from `var/log/` and Docker containers -- Admin and Storefront watchers (HMR) +- Admin and Storefront Watchers (HMR) - PHP version and profiler configuration (xdebug, blackfire, tideways, etc.) - Service discovery (Adminer, Mailpit, queue, etc.) @@ -65,7 +65,7 @@ Container names depend on the name of your project folder. | **Volume `my-project_db-data`** | Persistent storage | Stores the MariaDB database files so your data isn't lost when containers are stopped or rebuilt. | | **Container `my-project-mailer-1`** | Mailpit service | Captures outgoing emails for local testing. View at `http://localhost:8025`. | | **Container `my-project-database-1`** | MariaDB service | Runs the Shopware database. Inside the Docker network, its hostname is `database`. | -| **Container `my-project-web-1`** | PHP + Caddy web service | Runs Shopware itself and serves the storefront and Admin UI at `http://localhost:8000`. | +| **Container `my-project-web-1`** | PHP + Caddy web service | Runs Shopware itself and serves the Storefront and Admin UI at `http://localhost:8000`. | | **Container `my-project-adminer-1`** | Adminer (DB UI) | Lightweight web interface for viewing and editing your database. Available at `http://localhost:8080`. | ### Project structure diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md index 82608122af..8c015abf46 100644 --- a/products/tools/cli/project-commands/dev-environment.md +++ b/products/tools/cli/project-commands/dev-environment.md @@ -29,9 +29,9 @@ shopware-cli project dev stop The interactive dashboard has three tabs: -- **General** — environment overview, URLs, credentials, watchers, services -- **Logs** — real-time log streaming from `var/log/`, watchers, and Docker -- **Config** — PHP version, profiler, and credential management +- **Overview** — shop info, access credentials, setup health checks, and watcher toggles +- **Instance** — containers, watcher processes, and log files with live-streaming +- **Config** — PHP version, profiler ### View Application Logs diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index 75f3a0c771..9e1a2d7c58 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/products/tools/cli/project-commands/helper-commands.md @@ -53,7 +53,7 @@ Shopware CLI contains replacements for `bin/build-administration.sh` and `bin/bu | bin/watch-storefront.sh | `shopware-cli project storefront-watch` | | bin/watch-administration.sh | `shopware-cli project admin-watch` | -Additionally to the replacement, Shopware CLI allows only watching a specific set of extensions or excluding a few. +In addition to the replacements, Shopware CLI allows only watching a specific set of extensions or excluding a few. To only watch specific extensions: @@ -69,7 +69,7 @@ shopware-cli project admin-watch --skip-extensions ,.... ### Building only custom extensions -When working with a lot of 3rd party extensions, `project storefront-build` and `project admin-build` would become slow, when all extensions are built. +When working with many third-party extensions, `project storefront-build` and `project admin-build` would become slow, when all extensions are built. This is unnecessary because store extensions are shipped together with their assets. Use @@ -99,7 +99,7 @@ It is just a shortcut for `bin/console cache:clear` without having to be in the shopware-cli project clear-cache ``` -If in the `.shopware-project.yml` a API connection is configured, it will clear the remote instance cache. +If in the `.shopware-project.yml` an API connection is configured, it will clear the remote instance cache. ## Console From 2100d63d88ad72def0d3e1c07324651693044b77 Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 7 Jul 2026 18:22:55 +0200 Subject: [PATCH 08/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 294c872866..5eddcf66a4 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -41,7 +41,7 @@ To stop everything: shopware-cli project dev stop ``` -## DevTUI Dashboard +## Development TUI Dashboard The dashboard has three tabs, switched with the number keys: From 68ace4392ab1f358359bc6be43d329759d914a65 Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 7 Jul 2026 18:23:09 +0200 Subject: [PATCH 09/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 5eddcf66a4..017ab3fa71 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -43,7 +43,7 @@ shopware-cli project dev stop ## Development TUI Dashboard -The dashboard has three tabs, switched with the number keys: +The development terminal user interface (TUI) dashboard has three tabs, switched with the number keys or by pressing "Enter": ### Overview Tab (1) From 5a82dc566f39bc912fa5e93133b573dd31b55f34 Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 7 Jul 2026 18:23:16 +0200 Subject: [PATCH 10/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 017ab3fa71..179144cb03 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -45,7 +45,7 @@ shopware-cli project dev stop The development terminal user interface (TUI) dashboard has three tabs, switched with the number keys or by pressing "Enter": -### Overview Tab (1) +### Overview tab (1) Your environment at a glance: From c4d30cbfcd6b4d77e075b7904f54747baf978183 Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 7 Jul 2026 18:23:23 +0200 Subject: [PATCH 11/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 179144cb03..4991d2d7af 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -59,7 +59,7 @@ Your environment at a glance: - **Watchers** — toggle Admin and Storefront watchers on or off -### Instance Tab (2) +### Instance tab (2) Browse and stream logs from your running environment: From 30d6b1909a593369477293750f29e278e0c6b532 Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 7 Jul 2026 18:23:32 +0200 Subject: [PATCH 12/37] Update products/tools/cli/project-commands/helper-commands.md --- products/tools/cli/project-commands/helper-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index 9e1a2d7c58..cb331e30fd 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/products/tools/cli/project-commands/helper-commands.md @@ -99,7 +99,7 @@ It is just a shortcut for `bin/console cache:clear` without having to be in the shopware-cli project clear-cache ``` -If in the `.shopware-project.yml` an API connection is configured, it will clear the remote instance cache. +If an API connection is configured in the `.shopware-project.yml`, it will clear the remote instance cache. ## Console From d71460244e1ccca69e5524658fd2b35e4c467aae Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 7 Jul 2026 18:23:39 +0200 Subject: [PATCH 13/37] Update guides/development/start-developing.md --- guides/development/start-developing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md index ab4127be5f..9be5434c40 100644 --- a/guides/development/start-developing.md +++ b/guides/development/start-developing.md @@ -50,7 +50,7 @@ docker compose exec web bash Most tasks are now easier with `shopware-cli project console` and the DevTUI dashboard. ::: -## Frontend Development +## Frontend development When developing the Administration or Storefront, use watchers for Hot Module Replacement. Start them directly from the DevTUI Overview tab (key `1`), or from the command line: From 71942528cc2f3d6ddac38d732d2d6f9b363df9f5 Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 7 Jul 2026 18:23:45 +0200 Subject: [PATCH 14/37] Update guides/development/start-developing.md --- guides/development/start-developing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md index 9be5434c40..6498535b46 100644 --- a/guides/development/start-developing.md +++ b/guides/development/start-developing.md @@ -24,7 +24,7 @@ Common development areas: - `bin/console` — application CLI (Symfony console), runnable from your host via `shopware-cli project console` - The Administration UI -## Running Commands +## Running commands Use `shopware-cli project console` to run `bin/console` commands from your host — no need to enter the container: From 0a55df64f36d12e85c18dec7243e4d92cfdc847e Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 7 Jul 2026 18:23:53 +0200 Subject: [PATCH 15/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 4991d2d7af..e5309b0b4a 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -184,7 +184,7 @@ The CLI generates a `compose.yaml` tailored to your project: `compose.yaml` is fully managed by shopware-cli and regenerated whenever you change configuration. Never edit it directly — your changes will be overwritten. ::: -### Customizing with compose.override.yaml +### Customizing with `compose.override.yaml` Place all customizations in `compose.override.yaml`. Docker Compose [merges multiple files](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/), so your overrides are applied on top of the managed file: From 09d93b686e46c9784548e016d5f8d10195dfea01 Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 7 Jul 2026 18:24:00 +0200 Subject: [PATCH 16/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index e5309b0b4a..73d39f87b0 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -69,7 +69,7 @@ Browse and stream logs from your running environment: Use `↑`/`↓` to navigate sources and `enter` to select one. Scroll with `pgup`/`pgdn`. -### Config Tab (3) +### Config tab (3) Adjust your Docker environment without touching YAML: From 11ca185b277d07f9f910a1382026e042190c71ce Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 7 Jul 2026 18:26:51 +0200 Subject: [PATCH 17/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 73d39f87b0..57289b0bc5 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -181,7 +181,7 @@ The CLI generates a `compose.yaml` tailored to your project: \* *Auto-detected from `composer.lock` or enabled via configuration.* ::: warning -`compose.yaml` is fully managed by shopware-cli and regenerated whenever you change configuration. Never edit it directly — your changes will be overwritten. +`compose.yaml` is fully managed by Shopware CLI and regenerated whenever you change configuration. Never edit it directly, because your changes will be overwritten. ::: ### Customizing with `compose.override.yaml` From d1f19cecd82673f3d60429ad847f436d9baf8ee4 Mon Sep 17 00:00:00 2001 From: somethings Date: Wed, 8 Jul 2026 09:57:11 +0200 Subject: [PATCH 18/37] Update start-developing.md --- guides/development/start-developing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md index 6498535b46..60b2c99e0b 100644 --- a/guides/development/start-developing.md +++ b/guides/development/start-developing.md @@ -1,7 +1,7 @@ --- nav: title: Start Developing - position: 4 + position: 2 --- From d08c3e8e529a8489707a30978876202aaf3253c6 Mon Sep 17 00:00:00 2001 From: somethings Date: Wed, 8 Jul 2026 10:22:05 +0200 Subject: [PATCH 19/37] Update dev-environment.md --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 57289b0bc5..305f10d6d2 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -302,7 +302,7 @@ Check logs with `shopware-cli project logs -f` or from the Instance tab in the d ### Shopware isn't installed -The DevTUI prompts you to run the installer. It uses `shopware/deployment-helper` to install Shopware with your chosen locale, currency, and admin credentials. +The development TUI's initialization wizard, which mirrors steps in Shopware's in-browser First Run Wizard, prompts you to run the installer. It uses `shopware/deployment-helper` to install Shopware with your chosen locale, currency, and Admin credentials. ### Compatibility date error From 76cde531ee1bb4d0dae6246d8301d2ace5b5665d Mon Sep 17 00:00:00 2001 From: Soner Date: Wed, 8 Jul 2026 13:10:13 +0200 Subject: [PATCH 20/37] Apply suggestions from code review Co-authored-by: somethings Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- guides/development/dev-environment.md | 41 +++++++++---------- guides/development/index.md | 2 +- guides/development/start-developing.md | 20 ++++----- guides/installation/index.md | 2 +- guides/installation/project-overview.md | 4 +- .../cli/project-commands/dev-environment.md | 6 +-- .../cli/project-commands/helper-commands.md | 4 +- 7 files changed, 39 insertions(+), 40 deletions(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 305f10d6d2..d885d80c7c 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -13,7 +13,7 @@ Shopware CLI provides a fully integrated Docker-based development environment. A 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. ::: -## Starting the Environment +## Starting the environment From your Shopware project root, run: @@ -21,7 +21,7 @@ From your Shopware project root, run: shopware-cli project dev ``` -This launches the interactive **DevTUI** dashboard. If your containers aren't running yet, the dashboard starts them. If Shopware hasn't been installed, it guides you through the installation wizard. +This launches the development terminal user interface (TUI). If your containers aren't running yet, the dashboard starts them. If Shopware hasn't been installed, it guides you through the installation wizard. To start without the interactive dashboard (for CI or scripting): @@ -71,8 +71,7 @@ Use `↑`/`↓` to navigate sources and `enter` to select one. Scroll with `pgup ### Config tab (3) -Adjust your Docker environment without touching YAML: - +The following table lists the settings you can change in the Config tab: | Setting | Options | |---------|---------| | **PHP Version** | `8.2`, `8.3`, `8.4`, `8.5` | @@ -82,15 +81,15 @@ When selecting `blackfire` or `tideways`, additional credential fields appear. S After changing settings, select **Save & Regenerate** to update `compose.yaml`. Restart the environment for changes to take effect. -## Migrating from Legacy Setups +## Migrating from legacy setups -If your project was created before March 2026 and uses the older `make up`/`make setup` workflow with a hand-written `compose.yaml`, running `shopware-cli project dev` automatically detects this and launches a **setup wizard** instead of the dashboard. +If your project was created before March 2026 and uses the older `make up`/`make setup` workflow with a hand-written `compose.yaml`, running `shopware-cli project dev` automatically detects this and launches a setup wizard instead of the dashboard. -### What Triggers the Wizard +### 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. -### What the Wizard Does +### What the wizard does Walking through the setup wizard takes about a minute. Here's what happens at each step: @@ -108,17 +107,17 @@ After you confirm, the wizard: - 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 +### 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 — back it up first. Move any customizations to `compose.override.yaml`. | -| `Makefile` | **Not touched**. You can delete it once you've migrated, or keep it around | +| `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` | -### After the Wizard Completes +### After the wizard completes If `shopware/deployment-helper` was added to `composer.json`, you'll be prompted to run: @@ -128,9 +127,9 @@ composer install This pulls in the helper package, which the dashboard uses to run the Shopware installer. After that, the environment starts automatically. -Once migrated, the legacy `make up`/`make down`/`make setup` workflow is no longer needed — use `shopware-cli project dev` to manage your environment instead. If you had customizations in your old `compose.yaml`, move them to `compose.override.yaml` before running the wizard (or recover them from git afterwards). +Once migrated, the legacy `make up`/`make down`/`make setup` workflow is no longer needed; use `shopware-cli project dev` to manage your environment instead. If you had customizations in your old `compose.yaml`, move them to `compose.override.yaml` before running the wizard (or recover them from git afterwards). -## Viewing Application Logs +## Viewing application logs Inspect Shopware logs without opening the dashboard: @@ -151,7 +150,7 @@ shopware-cli project logs -l shopware-cli project logs --lines 50 ``` -## Running Shopware Commands +## Running Shopware commands Use `shopware-cli project console` to run `bin/console` commands from your host — no need to shell into the container: @@ -163,7 +162,7 @@ shopware-cli project console dal:refresh:index When using the Docker executor, commands automatically run inside the web container via `docker compose exec`. -## Docker Services +## Docker services The CLI generates a `compose.yaml` tailored to your project: @@ -220,7 +219,7 @@ The compose file inspects your `composer.lock` at generation time: - `shopware/elasticsearch` → adds **OpenSearch** with environment variables - PHP version defaults to `8.3`, overridable in the Config tab -## Environment Executors +## Environment executors The CLI abstracts command execution across environment types, configured per environment in `.shopware-project.yml`: @@ -253,7 +252,7 @@ The web container exposes these ports by default: | `9999` | Storefront Proxy | | `5773` | IDE debugging | -## Configuration Reference +## Configuration reference ### .shopware-project.yml @@ -279,7 +278,7 @@ environments: password: shopware ``` -### .shopware-project.local.yml +### `.shopware-project.local.yml` Sensitive credentials are stored in `.shopware-project.local.yml` (add to `.gitignore`): @@ -292,7 +291,7 @@ docker: ## Troubleshooting -### compose.yaml keeps getting reset +### `compose.yaml` keeps getting reset This is by design. `compose.yaml` is fully managed and regenerated on config changes. Use `compose.override.yaml` for all customizations. See [Customizing with compose.override.yaml](#customizing-with-composeoverrideyaml). @@ -308,7 +307,7 @@ The development TUI's initialization wizard, which mirrors steps in Shopware's i 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). -## Next Steps +## Next steps - [Start Developing](./start-developing.md) — What to do once your environment is running - [Build Extensions](./extensions/index.md) — Create plugins, apps, and themes diff --git a/guides/development/index.md b/guides/development/index.md index 16ab282ce8..08d9319317 100644 --- a/guides/development/index.md +++ b/guides/development/index.md @@ -78,7 +78,7 @@ The Administration is part of the runtime environment and will be used throughou ## Development tooling -* [Development Environment](./dev-environment.md) — Docker-based environment with an interactive terminal dashboard, log streaming, and runtime configuration +* [Development Environment](./dev-environment.md) — Docker-based environment with an interactive terminal user interface (TUI), log streaming, and runtime configuration * `bin/console`: Shopware's built-in CLI, used for installing and activating plugins, running database migrations, clearing caches, executing scheduled tasks, and inspecting system state. See [command reference guide](../../resources/references/core-reference/commands-reference.md). You can run these from your host with `shopware-cli project console`. * The standalone [Shopware CLI](../../products/tools/cli/installation.md) supports project scaffolding, CI/CD workflows, automation tasks, and more. See the [helper commands guide](../../products/tools/cli/project-commands/helper-commands.md). * IDE support: Shopware provides a [PHPStorm plugin](tooling/shopware-toolbox.md) and [VS Code extension](https://marketplace.visualstudio.com/items?itemName=shopware.shopware-lsp). diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md index 60b2c99e0b..37f77574ef 100644 --- a/guides/development/start-developing.md +++ b/guides/development/start-developing.md @@ -9,14 +9,14 @@ nav: This guide covers what to do once your [development environment](./dev-environment.md) is running. -## Your Environment +## Your environment Once the containers are up, you have: - **Storefront**: `http://127.0.0.1:8000` - **Administration**: `http://127.0.0.1:8000/admin` *(default credentials: `admin` / `shopware`)* -The DevTUI dashboard (`shopware-cli project dev`) shows these URLs and your credentials at a glance. +The development terminal user interface (TUI) (`shopware-cli project dev`) shows these URLs and your credentials at a glance. Common development areas: @@ -47,7 +47,7 @@ make shell docker compose exec web bash ``` -Most tasks are now easier with `shopware-cli project console` and the DevTUI dashboard. +Most tasks are now easier with `shopware-cli project console` and the development TUI. ::: ## Frontend development @@ -86,18 +86,18 @@ shopware-cli project admin-build --only-custom-static-extensions For more details, see [Using Watchers](./tooling/using-watchers.md). -## Administration Setup +## Administration setup When accessing the Administration for the first time: - Sign in or create a Shopware account (required to install Store extensions) -- Connect to the **Shopware Store** +- Connect to the Shopware Store - Install plugins or themes from the Store - Configure payment methods if needed Basic shop settings (name, language, currency) can be changed later under **Settings > Shop > Basic information**. -## Environment Customization +## Environment customization ### compose.override.yaml @@ -117,7 +117,7 @@ services: - "3306:3306" # Expose MySQL to host ``` -### Connecting to a Remote Database +### Connecting to a remote database To use an external database, set `DATABASE_URL` in `.env.local`: @@ -127,11 +127,11 @@ DATABASE_URL="mysql://user:password@:3306/" If the container can't reach `localhost`, try `host.docker.internal` or your host's LAN IP. -### Environment Variables +### Environment variables Create a `.env` file in the project root to override defaults. Most changes apply immediately. Changes to `APP_ENV` require a restart (`shopware-cli project dev stop && shopware-cli project dev start`). -## Shopware Account and Private Composer Packages +## Shopware account and private Composer packages To install licensed extensions from Shopware's private Composer registry: @@ -141,7 +141,7 @@ composer config --global http-basic.packages.shopware.com Create an access token in your Shopware account under **Shops > Licenses**. -## Next Steps +## Next steps - [Build Extensions](./extensions/index.md) — Create plugins, apps, and themes - [Work with APIs](./integrations-api/index.md) — Integrate external systems diff --git a/guides/installation/index.md b/guides/installation/index.md index 3b367da26d..8db955916a 100644 --- a/guides/installation/index.md +++ b/guides/installation/index.md @@ -85,7 +85,7 @@ cd my-shop shopware-cli project dev ``` -This launches the interactive **DevTUI** dashboard. The dashboard starts your Docker containers, runs the Shopware installer (first time only), and gives you an overview of your environment — Shop URLs, credentials, watchers, logs, and service configuration — all in one place. +This launches the development terminal user interface (TUI). The dashboard starts your Docker containers, runs the Shopware installer (first time only), and gives you an overview of your environment — Shop URLs, credentials, watchers, logs, and service configuration — all in one place. For details, see the [Development Environment guide](../development/dev-environment.md). diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md index 8bf542bafd..9934a4bf9a 100644 --- a/guides/installation/project-overview.md +++ b/guides/installation/project-overview.md @@ -11,7 +11,7 @@ You have just installed Shopware, and this section guides you through the fundam ## Development tooling -The Docker setup provisions Shopware for development. The recommended way to manage your environment is through the [Development Environment](../development/dev-environment.md) dashboard (`shopware-cli project dev`), which provides: +The Docker setup provisions Shopware for development. The recommended way to manage your environment is through the [Development Environment](../development/dev-environment.md) terminal user interface (TUI), available via `shopware-cli project dev`. It provides: - One-command start/stop of the entire stack - Real-time log streaming from `var/log/` and Docker containers @@ -22,7 +22,7 @@ The Docker setup provisions Shopware for development. The recommended way to man Development tools such as: - [`shopware/dev-tools`](https://github.com/shopware/dev-tools) -- [Symfony profiler]( https://symfony.com/doc/current/profiler.html) (**only in development mode**) +- [Symfony profiler](https://symfony.com/doc/current/profiler.html) (**only in development mode**) - linting and testing tools are managed via the Shopware CLI. These are installed into the user's environment and shared across projects and extensions, rather than being added as project-level `require-dev` dependencies. diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md index 8c015abf46..71c375abaf 100644 --- a/products/tools/cli/project-commands/dev-environment.md +++ b/products/tools/cli/project-commands/dev-environment.md @@ -11,7 +11,7 @@ This page is a quick reference for the `shopware-cli project dev` and `shopware- ## Commands -### Start the Environment +### Start the environment ```bash # Interactive dashboard (default when run in a terminal) @@ -33,7 +33,7 @@ The interactive dashboard has three tabs: - **Instance** — containers, watcher processes, and log files with live-streaming - **Config** — PHP version, profiler -### View Application Logs +### View application logs ```bash # Last 100 lines of the most recently modified log file @@ -74,7 +74,7 @@ environments: password: shopware ``` -## Further Reading +## Further reading - [Development Environment guide](../../../../guides/development/dev-environment.md) — full workflow, setup wizard, service overview, troubleshooting - [Start Developing](../../../../guides/development/start-developing.md) — next steps after your environment is running diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index cb331e30fd..c8188fd24b 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/products/tools/cli/project-commands/helper-commands.md @@ -25,12 +25,12 @@ shopware-cli project create The version parameter can be also `latest` for the latest stable version or `dev-trunk` for the latest development version. -## Development Environment +## Development environment Shopware CLI provides a fully integrated Docker-based development environment. See the [Development Environment](../../../../guides/development/dev-environment.md) guide for the full workflow, or the [CLI command reference](./dev-environment.md) for a quick overview. ```bash -# Launch the interactive dashboard +# Launch the interactive development terminal user interface (TUI) shopware-cli project dev # Start/stop in the background From 5705c40fc3425c1c35435886b3c93bcbe7c2b1eb Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Thu, 9 Jul 2026 10:02:05 +0200 Subject: [PATCH 21/37] Update development environment documentation and wordlist --- .wordlist.txt | 2 ++ guides/development/dev-environment.md | 20 +++++++++++--------- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index 77d9931c28..f527b9e23c 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1020,6 +1020,8 @@ TCP TLS TTL TTLs +TUI +TUI's TaxFreeConfigField TaxProvider TaxProviderStruct diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index d885d80c7c..e0f14dea32 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -41,11 +41,11 @@ To stop everything: shopware-cli project dev stop ``` -## Development TUI Dashboard +## Development terminal user interface (TUI) -The development terminal user interface (TUI) dashboard has three tabs, switched with the number keys or by pressing "Enter": +The dashboard has three tabs, either switched to with the corresponding number key or by using the Tab button. -### Overview tab (1) +### Overview Tab (1) Your environment at a glance: @@ -59,7 +59,7 @@ Your environment at a glance: - **Watchers** — toggle Admin and Storefront watchers on or off -### Instance tab (2) +### Instance Tab (2) Browse and stream logs from your running environment: @@ -67,9 +67,9 @@ Browse and stream logs from your running environment: - **Processes** — watcher processes (Admin Watcher, Storefront Watcher) when running - **Log files** — application log files (e.g., `dev.log`) -Use `↑`/`↓` to navigate sources and `enter` to select one. Scroll with `pgup`/`pgdn`. +Use the sidebar to switch sources. Toggle follow mode with `Enter`. -### Config tab (3) +### Config Tab (3) The following table lists the settings you can change in the Config tab: | Setting | Options | @@ -79,6 +79,8 @@ The following table lists the settings you can change in the Config tab: When selecting `blackfire` or `tideways`, additional credential fields appear. Sensitive credentials are stored in `.shopware-project.local.yml` (excluded from version control). +> **Note:** The profiler is now configured via the Config tab. + After changing settings, select **Save & Regenerate** to update `compose.yaml`. Restart the environment for changes to take effect. ## Migrating from legacy setups @@ -180,7 +182,7 @@ The CLI generates a `compose.yaml` tailored to your project: \* *Auto-detected from `composer.lock` or enabled via configuration.* ::: warning -`compose.yaml` is fully managed by Shopware CLI and regenerated whenever you change configuration. Never edit it directly, because your changes will be overwritten. +The `compose.yaml` file is fully managed by the Shopware CLI and regenerated whenever you change configuration. **Never edit it directly.** ::: ### Customizing with `compose.override.yaml` @@ -254,7 +256,7 @@ The web container exposes these ports by default: ## Configuration reference -### .shopware-project.yml +### `.shopware-project.local.yml` ```yaml compatibility_date: '2026-03-01' @@ -297,7 +299,7 @@ This is by design. `compose.yaml` is fully managed and regenerated on config cha ### Containers won't start -Check logs with `shopware-cli project logs -f` or from the Instance tab in the dashboard. +Check logs with `shopware-cli project logs -f` or from the Instance tab in the TUI. ### Shopware isn't installed From 73158a404cab93edb5b04abb6115f9a9deaf474a Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Thu, 9 Jul 2026 10:08:24 +0200 Subject: [PATCH 22/37] Fix punctuation in development documentation for consistency --- guides/development/dev-environment.md | 34 +++++++++++++------------- guides/development/start-developing.md | 12 ++++----- guides/installation/index.md | 2 +- 3 files changed, 24 insertions(+), 24 deletions(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index e0f14dea32..0851518182 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -7,7 +7,7 @@ nav: # Development Environment -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. +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. @@ -51,21 +51,21 @@ Your environment at a glance: **Left panel:** -- **Shop** — Shopware version, environment type (`docker`, `local`, or `symfony-cli`), shop and admin URLs, and security update expiry date -- **Access** — URLs, usernames, and passwords for Shop Admin, Adminer, and Mailpit -- **Setup health** — runtime checks (PHP version, memory limit), local behavior warnings, and debug settings, each showing the current value against the recommended one +- **Shop** - Shopware version, environment type (`docker`, `local`, or `symfony-cli`), shop and admin URLs, and security update expiry date +- **Access** - URLs, usernames, and passwords for Shop Admin, Adminer, and Mailpit +- **Setup health** - runtime checks (PHP version, memory limit), local behavior warnings, and debug settings, each showing the current value against the recommended one **Right panel:** -- **Watchers** — toggle Admin and Storefront watchers on or off +- **Watchers** - toggle Admin and Storefront watchers on or off ### Instance Tab (2) Browse and stream logs from your running environment: -- **Containers** — all Docker containers with a live status indicator for the active one -- **Processes** — watcher processes (Admin Watcher, Storefront Watcher) when running -- **Log files** — application log files (e.g., `dev.log`) +- **Containers** - all Docker containers with a live status indicator for the active one +- **Processes** - watcher processes (Admin Watcher, Storefront Watcher) when running +- **Log files** - application log files (e.g., `dev.log`) Use the sidebar to switch sources. Toggle follow mode with `Enter`. @@ -95,11 +95,11 @@ The wizard appears when your project's `compatibility_date` in `.shopware-projec 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` -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`) -5. **Review** — shows a summary of all your choices before applying changes +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` +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`) +5. **Review** - shows a summary of all your choices before applying changes After you confirm, the wizard: @@ -154,7 +154,7 @@ shopware-cli project logs --lines 50 ## Running Shopware commands -Use `shopware-cli project console` to run `bin/console` commands from your host — no need to shell into the container: +Use `shopware-cli project console` to run `bin/console` commands from your host - no need to shell into the container: ```bash shopware-cli project console cache:clear @@ -311,6 +311,6 @@ Set `compatibility_date: '2026-03-01'` in `.shopware-project.yml`. For more cont ## Next steps -- [Start Developing](./start-developing.md) — What to do once your environment is running -- [Build Extensions](./extensions/index.md) — Create plugins, apps, and themes -- [Using Watchers](./tooling/using-watchers.md) — Hot Module Replacement for Admin and Storefront +- [Start Developing](./start-developing.md) - What to do once your environment is running +- [Build Extensions](./extensions/index.md) - Create plugins, apps, and themes +- [Using Watchers](./tooling/using-watchers.md) - Hot Module Replacement for Admin and Storefront diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md index 37f77574ef..6bca3ddc9b 100644 --- a/guides/development/start-developing.md +++ b/guides/development/start-developing.md @@ -20,13 +20,13 @@ The development terminal user interface (TUI) (`shopware-cli project dev`) shows Common development areas: -- `custom/` — your plugins and themes -- `bin/console` — application CLI (Symfony console), runnable from your host via `shopware-cli project console` +- `custom/` - your plugins and themes +- `bin/console` - application CLI (Symfony console), runnable from your host via `shopware-cli project console` - The Administration UI ## Running commands -Use `shopware-cli project console` to run `bin/console` commands from your host — no need to enter the container: +Use `shopware-cli project console` to run `bin/console` commands from your host - no need to enter the container: ```bash # Clear caches @@ -143,6 +143,6 @@ Create an access token in your Shopware account under **Shops > Licenses**. ## Next steps -- [Build Extensions](./extensions/index.md) — Create plugins, apps, and themes -- [Work with APIs](./integrations-api/index.md) — Integrate external systems -- [Set up CI/CD](../../products/tools/cli/project-commands/build.md) — Automate builds and deployments +- [Build Extensions](./extensions/index.md) - Create plugins, apps, and themes +- [Work with APIs](./integrations-api/index.md) - Integrate external systems +- [Set up CI/CD](../../products/tools/cli/project-commands/build.md) - Automate builds and deployments diff --git a/guides/installation/index.md b/guides/installation/index.md index 3ef9a36c34..354f0f439e 100644 --- a/guides/installation/index.md +++ b/guides/installation/index.md @@ -99,7 +99,7 @@ cd my-shop shopware-cli project dev ``` -This launches the development terminal user interface (TUI). The dashboard starts your Docker containers, runs the Shopware installer (first time only), and gives you an overview of your environment — Shop URLs, credentials, watchers, logs, and service configuration — all in one place. +This launches the development terminal user interface (TUI). The dashboard starts your Docker containers, runs the Shopware installer (first time only), and gives you an overview of your environment - Shop URLs, credentials, watchers, logs, and service configuration - all in one place. For details, see the [Development Environment guide](../development/dev-environment.md). From 7cf5188d49f7150df70277e80016d256233fe03e Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Thu, 9 Jul 2026 10:38:23 +0200 Subject: [PATCH 23/37] Fix typo in configuration file name in development documentation --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 0851518182..ee0123318f 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -256,7 +256,7 @@ The web container exposes these ports by default: ## Configuration reference -### `.shopware-project.local.yml` +### `.shopware-project.yml` ```yaml compatibility_date: '2026-03-01' From b02958cb94940f734688a00c945457d00762587e Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 9 Jul 2026 11:24:57 +0200 Subject: [PATCH 24/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index ee0123318f..6139697a56 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -43,7 +43,7 @@ shopware-cli project dev stop ## Development terminal user interface (TUI) -The dashboard has three tabs, either switched to with the corresponding number key or by using the Tab button. +The dashboard has three tabs, which can be switched to with the corresponding number key or by using the Tab button. ### Overview Tab (1) From b84c735c76f7bb2513f94fa7ae2b764600b572b2 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 9 Jul 2026 11:25:11 +0200 Subject: [PATCH 25/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 6139697a56..63dd9982fe 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -59,7 +59,7 @@ Your environment at a glance: - **Watchers** - toggle Admin and Storefront watchers on or off -### Instance Tab (2) +### 2. Instance Tab Browse and stream logs from your running environment: From 79d79fc031af98a59250a9f091f938e3a27f600a Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 9 Jul 2026 11:25:20 +0200 Subject: [PATCH 26/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 63dd9982fe..6cd479e727 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -45,7 +45,7 @@ shopware-cli project dev stop The dashboard has three tabs, which can be switched to with the corresponding number key or by using the Tab button. -### Overview Tab (1) +### 1. Overview Tab Your environment at a glance: From 2f3240338e9f4b187c079489beb6b46bde070c64 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 9 Jul 2026 11:25:29 +0200 Subject: [PATCH 27/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 6cd479e727..9fa5915e3d 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -69,7 +69,7 @@ Browse and stream logs from your running environment: Use the sidebar to switch sources. Toggle follow mode with `Enter`. -### Config Tab (3) +### 3. Config Tab The following table lists the settings you can change in the Config tab: | Setting | Options | From f40de2a25bfa193542699f7eebd6cb2adca3fc7e Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 9 Jul 2026 11:25:39 +0200 Subject: [PATCH 28/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 9fa5915e3d..ebac0b9af7 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -79,7 +79,9 @@ The following table lists the settings you can change in the Config tab: When selecting `blackfire` or `tideways`, additional credential fields appear. Sensitive credentials are stored in `.shopware-project.local.yml` (excluded from version control). -> **Note:** The profiler is now configured via the Config tab. +:::info +The profiler is now configured via the Config tab. +::: After changing settings, select **Save & Regenerate** to update `compose.yaml`. Restart the environment for changes to take effect. From 7a7d3cbe4003c1e69ab32d4edf8dbe04a4486ea2 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 9 Jul 2026 11:25:49 +0200 Subject: [PATCH 29/37] Update guides/development/dev-environment.md --- guides/development/dev-environment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index ebac0b9af7..dc810f24b6 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -219,8 +219,8 @@ The CLI-generated `compose.yaml` includes this header for clarity: The compose file inspects your `composer.lock` at generation time: -- `symfony/amqp-messenger` → adds **LavinMQ** and sets `MESSENGER_TRANSPORT_DSN` -- `shopware/elasticsearch` → adds **OpenSearch** with environment variables +- `symfony/amqp-messenger` - adds **LavinMQ** and sets `MESSENGER_TRANSPORT_DSN` +- `shopware/elasticsearch` - adds **OpenSearch** with environment variables - PHP version defaults to `8.3`, overridable in the Config tab ## Environment executors From 4a4c37d611bc5313cb46b2b69919ac5609786bea Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 9 Jul 2026 11:38:31 +0200 Subject: [PATCH 30/37] Update guides/development/index.md --- guides/development/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/index.md b/guides/development/index.md index 08d9319317..da2902a9ac 100644 --- a/guides/development/index.md +++ b/guides/development/index.md @@ -78,7 +78,7 @@ The Administration is part of the runtime environment and will be used throughou ## Development tooling -* [Development Environment](./dev-environment.md) — Docker-based environment with an interactive terminal user interface (TUI), log streaming, and runtime configuration +* [Development Environment](./dev-environment.md) — Docker-based environment with an interactive Terminal User Interface (TUI), log streaming, and runtime configuration * `bin/console`: Shopware's built-in CLI, used for installing and activating plugins, running database migrations, clearing caches, executing scheduled tasks, and inspecting system state. See [command reference guide](../../resources/references/core-reference/commands-reference.md). You can run these from your host with `shopware-cli project console`. * The standalone [Shopware CLI](../../products/tools/cli/installation.md) supports project scaffolding, CI/CD workflows, automation tasks, and more. See the [helper commands guide](../../products/tools/cli/project-commands/helper-commands.md). * IDE support: Shopware provides a [PHPStorm plugin](tooling/shopware-toolbox.md) and [VS Code extension](https://marketplace.visualstudio.com/items?itemName=shopware.shopware-lsp). From 7339ce0c1a1da5dc7e79d9e95f961cc3a28e5864 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 9 Jul 2026 11:38:53 +0200 Subject: [PATCH 31/37] Update guides/installation/index.md --- guides/installation/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/index.md b/guides/installation/index.md index 354f0f439e..434c682308 100644 --- a/guides/installation/index.md +++ b/guides/installation/index.md @@ -99,7 +99,7 @@ cd my-shop shopware-cli project dev ``` -This launches the development terminal user interface (TUI). The dashboard starts your Docker containers, runs the Shopware installer (first time only), and gives you an overview of your environment - Shop URLs, credentials, watchers, logs, and service configuration - all in one place. +This launches the Development TUI. The dashboard starts your Docker containers, runs the Shopware installer (first time only), and gives you an overview of your environment - Shop URLs, credentials, watchers, logs, and service configuration - all in one place. For details, see the [Development Environment guide](../development/dev-environment.md). From 324fd614814693201ad12933b0fd3f3d8a193432 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 9 Jul 2026 11:39:03 +0200 Subject: [PATCH 32/37] Update guides/installation/project-overview.md --- guides/installation/project-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md index 9934a4bf9a..970649c209 100644 --- a/guides/installation/project-overview.md +++ b/guides/installation/project-overview.md @@ -11,7 +11,7 @@ You have just installed Shopware, and this section guides you through the fundam ## Development tooling -The Docker setup provisions Shopware for development. The recommended way to manage your environment is through the [Development Environment](../development/dev-environment.md) terminal user interface (TUI), available via `shopware-cli project dev`. It provides: +The Docker setup provisions Shopware for development. The recommended way to manage your environment is through the [Development Environment](../development/dev-environment.md) TUI, available via `shopware-cli project dev`. It provides: - One-command start/stop of the entire stack - Real-time log streaming from `var/log/` and Docker containers From 176bf41d908a9f2b6078b89435df6b5691f4e011 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 9 Jul 2026 09:40:58 +0000 Subject: [PATCH 33/37] fix: remove extra space in heading in dev-environment.md (MD019) --- guides/development/dev-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index dc810f24b6..2448361f51 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -45,7 +45,7 @@ shopware-cli project dev stop The dashboard has three tabs, which can be switched to with the corresponding number key or by using the Tab button. -### 1. Overview Tab +### 1. Overview Tab Your environment at a glance: From 9ee3f3b9aec537e58833ad606bd92675b7db3e4a Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 10 Jul 2026 12:57:10 +0200 Subject: [PATCH 34/37] Update dev-environment.md --- guides/development/dev-environment.md | 1 - 1 file changed, 1 deletion(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 2448361f51..865b840818 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -101,7 +101,6 @@ Walking through the setup wizard takes about a minute. Here's what happens at ea 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` 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`) -5. **Review** - shows a summary of all your choices before applying changes After you confirm, the wizard: From c7ef42431e8d2c3220d8915695d362027b6c14b3 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 10 Jul 2026 16:22:06 +0200 Subject: [PATCH 35/37] Update dev-environment.md --- guides/development/dev-environment.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 865b840818..846c3f0ce0 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -165,6 +165,14 @@ shopware-cli project console dal:refresh:index When using the Docker executor, commands automatically run inside the web container via `docker compose exec`. +To type a little less, you can also use the `swx` alias as a shortcut for `shopware-cli project console`: + +```bash +swx cache:clear +swx plugin:refresh +swx dal:refresh:index +``` + ## Docker services The CLI generates a `compose.yaml` tailored to your project: From 10fc6c358ea14485b6e1410c3706cab5b2ca5c5d Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 10 Jul 2026 16:24:01 +0200 Subject: [PATCH 36/37] Update start-developing.md --- guides/development/start-developing.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md index 6bca3ddc9b..f2f59fa43c 100644 --- a/guides/development/start-developing.md +++ b/guides/development/start-developing.md @@ -39,6 +39,8 @@ shopware-cli project console plugin:install --activate MyPlugin shopware-cli project console database:migrate --all ``` +For the shorter `swx` alias, see [Running Shopware commands](./dev-environment.md#running-shopware-commands). + :::info Legacy workflow If your project uses the older `make`-based setup and you need to shell into the container manually: From 243302119189467871b0c0df47783ea99660cead Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 10 Jul 2026 16:27:15 +0200 Subject: [PATCH 37/37] Update helper-commands.md --- products/tools/cli/project-commands/helper-commands.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index c8188fd24b..71ee0f5de0 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/products/tools/cli/project-commands/helper-commands.md @@ -109,6 +109,8 @@ Similar to `clear-cache`, there is also a general shortcut for `bin/console`: shopware-cli project console ``` +A shorter `swx` alias is also available. See [Running Shopware commands](../../../../guides/development/dev-environment.md#running-shopware-commands). + ## Admin API If you want to make requests against the Shopware-API using curl, you need to get a JWT token and add it as a header. Shopware CLI has a helper command for that: