feat(cli): Docker-based dev environment by shyim · Pull Request #2286 · shopware/docs

Soner (shyim) · 2026-05-18T03:37:27Z

Summary

Documents the new development environment introduced in (next branch), which adds a fully integrated Docker-based development environment with an interactive terminal dashboard.

Changes

New: products/cli/project-commands/dev-environment.md — comprehensive guide covering project dev, dev start/dev stop, project logs, the DevTUI dashboard, setup wizard, Docker services, environment executors, configuration reference, and troubleshooting
Updated: products/cli/project-commands/helper-commands.md — added Development Environment section
Updated: guides/development/start-developing.md — added "Using the Development Environment" section
Updated: products/cli/index.md — added dev environment to feature list

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.

…e.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.

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

- Added DevTUI, LavinMQ, lavinmq, adminer, keypress, overridable, runnable, xdebug to .wordlist.txt - Fixed markdown linting: blank lines before code blocks and lists

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)

shopware-dev-docs-connector · 2026-06-30T09:52:23Z

Developer Docs healthcheck

Status: Completed with success.
Repository: shopware/docs
Commit: 76cde53
Preview: https://developer-documentation-7jbdg06o0-shopware-frontends.vercel.app
Workflow run: #4425

…changes Updates to cli docs to current state

Copilot

Pull request overview

Adds documentation for the new Shopware CLI Docker-based Development Environment (DevTUI) and integrates it into the existing installation/development/CLI docs, including a CLI reference page and spellcheck wordlist updates.

Changes:

Introduces a comprehensive Development Environment guide (shopware-cli project dev, DevTUI, services, config, migration, troubleshooting).
Adds a CLI reference page for project dev / project logs, plus cross-links from CLI helper docs and development tooling indexes.
Updates installation and “start developing” docs to prefer the DevTUI workflow over legacy make-based flows; extends spellcheck wordlist for new terms.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
products/tools/cli/project-commands/helper-commands.md	Adds a Development Environment section and fixes wording/indentation in existing CLI helper docs.
products/tools/cli/project-commands/dev-environment.md	New CLI reference page for `project dev` and `project logs`, linking to the full guide.
products/tools/cli/index.md	Adds the dev environment to the CLI feature list.
guides/installation/project-overview.md	Updates “Development tooling” to recommend DevTUI; adjusts examples/wording in tables.
guides/installation/index.md	Replaces legacy “finish Docker setup” section with DevTUI-first startup instructions and links.
guides/development/tooling/index.md	Adds Development Environment to the official tooling list and cleans up formatting.
guides/development/start-developing.md	Reorients the guide around the DevTUI workflow (console, watchers, customization, legacy note).
guides/development/index.md	Updates the typical development workflow and tooling section to link Dev Environment + Start Developing.
guides/development/dev-environment.md	New detailed Development Environment guide, including migration and configuration reference.
.wordlist.txt	Adds new accepted terms (e.g., DevTUI, LavinMQ, xdebug).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+| **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`. |


+| **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.                                                            |


somethings (lasomethingsomething) · 2026-07-07T14:03:46Z

+shopware-cli project dev stop
+```
+
+## DevTUI Dashboard


Suggested change

## DevTUI Dashboard

## Development terminal user interface (TUI)

somethings (lasomethingsomething) · 2026-07-07T14:04:48Z

+
+## DevTUI Dashboard
+
+The dashboard has three tabs, switched with the number keys or by clicking:


Suggested change

The dashboard has three tabs, switched with the number keys or by clicking:

The dashboard has three tabs, either switched to with the corresponding number key or by using the Tab button.

somethings (lasomethingsomething) · 2026-07-07T14:05:03Z

+
+The dashboard has three tabs, switched with the number keys or by clicking:
+
+### General Tab (1)


Suggested change

### General Tab (1)

### Overview Tab (1)

somethings (lasomethingsomething) · 2026-07-07T14:50:20Z


 The version parameter can be also `latest` for the latest stable version or `dev-trunk` for the latest development version.

+## Development Environment


Suggested change

## Development Environment

## Development environment

somethings (lasomethingsomething) · 2026-07-07T14:51:01Z

+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


Suggested change

# Launch the interactive dashboard

# Launch the interactive development terminal user interface (TUI)

somethings (lasomethingsomething) · 2026-07-07T14:52:41Z

 Deprecations
 Deutsch
 DevOps
+DevTUI


Tomasz Turkowski (@tturkowski) I dropped this in favor of what it is, a development TUI. We should decide on a naming convention deliberately and think about the schema. Would remove this entry from the list.

somethings (lasomethingsomething) · 2026-07-07T15:05:10Z

+
+### 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.


Suggested change

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 prompts you to run the installer. It uses `shopware/deployment-helper` to install Shopware with your chosen locale, currency, and admin credentials.

Just to be clear, this is in the Shopware initialization wizard that starts here and includes similar steps in the in-browser first-run wizard. The currency, locale, etc. follow in the subsequent panels. We might wish to refer to this as the development TUI's "installation wizard" to be specific.

somethings (lasomethingsomething) · 2026-07-07T15:24:06Z

+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


Doesn't exist

Co-authored-by: somethings <l.apple@shopware.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Soner (shyim) added 5 commits June 30, 2026 11:48

chore: add new terms to spellcheck wordlist, fix markdown linting

e924682

- Added DevTUI, LavinMQ, lavinmq, adminer, keypress, overridable, runnable, xdebug to .wordlist.txt - Fixed markdown linting: blank lines before code blocks and lists

Soner (shyim) force-pushed the feat/cli-dev-environment-docs branch from 692d787 to 4ab0c30 Compare June 30, 2026 09:52

docs(cli): document dev status command

7fb3561

somethings (lasomethingsomething) mentioned this pull request Jul 2, 2026

Redesign project dev wizard + tabs for a more interactive, guided flow (MVP.1) shopware/shopware-cli#1113

Open

12 tasks

somethings (lasomethingsomething) assigned Tomasz Turkowski (tturkowski) Jul 6, 2026

Tomasz Turkowski (tturkowski) and others added 11 commits July 7, 2026 17:45

Updates to docs

830956a

Update guides/development/dev-environment.md

2100d63

Update guides/development/dev-environment.md

68ace43

Update guides/development/dev-environment.md

5a82dc5

Update guides/development/dev-environment.md

c4d30cb

Update products/tools/cli/project-commands/helper-commands.md

30d6b19

Update guides/development/start-developing.md

d714602

Update guides/development/start-developing.md

7194252

Update guides/development/dev-environment.md

0a55df6

Update guides/development/dev-environment.md

09d93b6

Update guides/development/dev-environment.md

11ca185

somethings (lasomethingsomething) changed the title ~~feat(cli): document new Docker-based development environment~~ feat(cli): older draft for Docker-based dev environment (still includes useful info) Jul 7, 2026

Merge pull request #2373 from shopware/feat/cli-dev-environment-docs-…

c732da1

…changes Updates to cli docs to current state

Soner (shyim) marked this pull request as ready for review July 8, 2026 07:51

Copilot AI review requested due to automatic review settings July 8, 2026 07:51

Copilot started reviewing on behalf of Soner (shyim) July 8, 2026 07:52 View session

somethings (lasomethingsomething) changed the title ~~feat(cli): older draft for Docker-based dev environment (still includes useful info)~~ feat(cli): Docker-based dev environment Jul 8, 2026

Copilot AI reviewed Jul 8, 2026

View reviewed changes

somethings (lasomethingsomething) added 2 commits July 8, 2026 09:57

Update start-developing.md

d1f19ce

Update dev-environment.md

d08c3e8

somethings (lasomethingsomething) requested changes Jul 8, 2026

View reviewed changes

Apply suggestions from code review

76cde53

Co-authored-by: somethings <l.apple@shopware.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

	## DevTUI Dashboard
	## Development terminal user interface (TUI)


		## 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 or by clicking:
	The dashboard has three tabs, either switched to with the corresponding number key or by using the Tab button.


		The dashboard has three tabs, switched with the number keys or by clicking:

		### General Tab (1)


		The version parameter can be also `latest` for the latest stable version or `dev-trunk` for the latest development version.

		## Development Environment

	# Launch the interactive dashboard
	# Launch the interactive development terminal user interface (TUI)


		### 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 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 prompts you to run the installer. It uses `shopware/deployment-helper` to install Shopware with your chosen locale, currency, and admin credentials.

Uh oh!

Conversation

Soner (shyim) commented May 18, 2026

Summary

Changes

Uh oh!

shopware-dev-docs-connector Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Developer Docs healthcheck

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

shopware-dev-docs-connector Bot commented Jun 30, 2026 •

edited

Loading