From 12c44b037896633896b316309f9e1090b24ccc2a Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Mon, 18 May 2026 05:37:04 +0200 Subject: [PATCH 1/5] 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/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/cli/project-commands/dev-environment.md diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md index bf8c895a5f..8438b870f7 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/cli/index.md b/products/cli/index.md index 0f22053b48..f50a398484 100644 --- a/products/cli/index.md +++ b/products/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/cli/project-commands/dev-environment.md b/products/cli/project-commands/dev-environment.md new file mode 100644 index 0000000000..f947ab3b9e --- /dev/null +++ b/products/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/cli/project-commands/helper-commands.md b/products/cli/project-commands/helper-commands.md index c7d8216f6f..f4573e7127 100644 --- a/products/cli/project-commands/helper-commands.md +++ b/products/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 18dc562a72800040258fe40717e581b154d4da4f Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Mon, 18 May 2026 07:05:01 +0200 Subject: [PATCH 2/5] 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/cli/project-commands/dev-environment.md b/products/cli/project-commands/dev-environment.md index f947ab3b9e..3f25416ea4 100644 --- a/products/cli/project-commands/dev-environment.md +++ b/products/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 19fcab35cbe22ba6d0b46a3e4d04675b31a56bba Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Mon, 18 May 2026 07:13:16 +0200 Subject: [PATCH 3/5] 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..56f9717928 --- /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/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 57a56776c2..a924429c15 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/cli/installation.md) supports project scaffolding, CI/CD workflows, automation tasks, and more. See the [helper commands guide](../../products/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 8438b870f7..f66136c20d 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 -``` - -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 +# Clear caches +shopware-cli project console cache:clear -To run commands, open a shell inside the web container: +# Install and activate a plugin +shopware-cli project console plugin:install --activate MyPlugin -```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: run build and watch scripts directly +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`, your project also provides bash scripts in the `bin/` directory 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 -./bin/build-administration.sh -./bin/build-storefront.sh -./bin/watch-administration.sh -./bin/watch-storefront.sh +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/cli/project-commands/build.md) — Automate builds and deployments diff --git a/guides/development/tooling/index.md b/guides/development/tooling/index.md index 68c29d6fb2..50c10f0a41 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](/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 18ebd721e1..42d3f5bb0f 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/cli/project-commands/dev-environment.md b/products/cli/project-commands/dev-environment.md index 3f25416ea4..d91e44f787 100644 --- a/products/cli/project-commands/dev-environment.md +++ b/products/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/cli/project-commands/helper-commands.md b/products/cli/project-commands/helper-commands.md index f4573e7127..1c105af505 100644 --- a/products/cli/project-commands/helper-commands.md +++ b/products/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 3dab1d75085626126a2c09191c20bb26d4c33949 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Mon, 18 May 2026 07:25:53 +0200 Subject: [PATCH 4/5] 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/cli/project-commands/dev-environment.md | 1 + 3 files changed, 11 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 8cbec93262..6ffa8d5ced 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -324,6 +324,7 @@ Deployer Deprecations Deutsch DevOps +DevTUI DevTools Devenv DeviceHelper @@ -520,6 +521,7 @@ LONGTEXT LUA LandingPage LastNameRule +LavinMQ Lerna Lifecycle LineItemClearanceSaleRule @@ -1142,6 +1144,7 @@ actionAmount actionType actionability activateShopwareTheme +adminer adr afterSort ag @@ -1589,8 +1592,10 @@ jwks jwt kebabCase keyframes +keypress landingpage lang +lavinmq lazysizes libxml lifecycle @@ -1709,6 +1714,7 @@ org's organizationUnitIds otel otlp +overridable overrideComponentSetup oversales paas @@ -1848,6 +1854,7 @@ rollout routeName routeScope routeScopes +runnable runtime runtimes salesChannel @@ -2076,6 +2083,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 f66136c20d..f085db0166 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/cli/project-commands/dev-environment.md b/products/cli/project-commands/dev-environment.md index d91e44f787..ac12d788c0 100644 --- a/products/cli/project-commands/dev-environment.md +++ b/products/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 692d78738457b018471919beca63a10b47efd005 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Mon, 18 May 2026 07:41:59 +0200 Subject: [PATCH 5/5] 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 +++++++++++++++++++++++---- 1 file changed, 47 insertions(+), 7 deletions(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 56f9717928..c04ce18fbf 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