docs: document Composer-in-container and PHP memory limit for CLI Docker

guides/development/dev-environment.md

@@ -53,7 +53,7 @@
 
 - **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
+- **Setup health** - runtime checks (PHP version and memory limit of the project executor — the web container for Docker projects), local behavior warnings, and debug settings, each showing the current value against the recommended one. Runtime memory is not the same as host PHP used by a local `composer` binary
 
 **Right panel:**
 
@@ -122,10 +122,10 @@
 
 ### After the wizard completes
 
-If `shopware/deployment-helper` was added to `composer.json`, you'll be prompted to run:
+If `shopware/deployment-helper` was added to `composer.json`, you'll be prompted to install dependencies. With the Docker environment type, run Composer **inside** the web container so PHP uses the container memory limit and database connection:
 
 ```bash
-composer install
+docker compose exec web composer install
 ```
 
 This pulls in the helper package, which the dashboard uses to run the Shopware installer. After that, the environment starts automatically.
@@ -173,6 +173,46 @@
 swx dal:refresh:index
 ```
 
+## Running Composer, PHP, and npm
+
+The project directory is bind-mounted into the `web` container (`.:/var/www/html`), so you can edit files on the host. That mount does **not** mean host PHP and Composer share the container environment.
+
+With the Docker-based development environment (`environments.local.type: docker`), run Composer, PHP, and npm **inside** the `web` container. The container has the correct PHP version, `memory_limit`, extensions, and network access to services such as the database.
+
+```bash
+# Open an interactive shell in the web container
+docker compose exec web bash
+
+# Or run a single command without an interactive shell
+docker compose exec web composer require shopware/docker
+docker compose exec web composer install
+docker compose exec web php -i | grep memory_limit
+```
+
+Prefer a higher-level Shopware CLI command when one exists. For example, use `shopware-cli project console` instead of calling `bin/console` yourself, and use `shopware-cli project admin-watch` / `storefront-watch` instead of npm watch scripts.
+
+::: warning
+Running `composer` on the host with a typical local PHP install often fails. Host PHP commonly defaults to `memory_limit=128M`, while Shopware needs **at least 512M**. Composer scripts may also try to boot Shopware and connect to the database, which is only available inside the Docker network.
+
+The **Setup health → Runtime → Memory limit** check in the development TUI reports the PHP used by the project executor (the container for Docker projects), not your host PHP. A green runtime check does not mean host-side Composer is safe.
+:::
+
+### PHP memory limit (when you run PHP on the host)
+
+If you use a local or Symfony CLI environment instead of Docker, or you intentionally run Composer on the host, configure CLI PHP with:
+
+```ini
+memory_limit = 512M
+```
+
+Verify with:
+
+```bash
+php -i | grep memory_limit
+```
+
+See the [recommended stack and supported versions](../hosting/index.md#recommended-stack-and-supported-versions) for the full PHP requirements (`memory_limit ≥ 512M`, extensions, and related settings).
+
 ## Docker services
 
 The CLI generates a `compose.yaml` tailored to your project:
@@ -314,6 +354,18 @@
 
 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.
 
+### Composer fails with "Allowed memory size of 134217728 bytes exhausted"
+
+`134217728` bytes is **128M** — the default host PHP memory limit. You almost certainly ran Composer on the host instead of in the web container.
+
+Use:
+
+```bash
+docker compose exec web composer <your-command>
+```
+
+If you must run Composer on the host, raise CLI `memory_limit` to at least `512M`. See [Running Composer, PHP, and npm](#running-composer-php-and-npm).
+
 ### 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).

guides/development/start-developing.md

@@ -26,7 +26,7 @@ Common development areas:
 
 ## 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 — Shopware CLI routes them into the web container for Docker projects:
 
 ```bash
 # Clear caches
@@ -41,15 +41,31 @@ 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:
+### Composer, PHP, and npm
+
+There is no Shopware CLI wrapper for arbitrary Composer commands yet. For Docker projects, run them **inside** the `web` container so you use the container PHP (`memory_limit ≥ 512M`) and can reach the database and other services:
+
+```bash
+# Interactive shell
+docker compose exec web bash
+
+# One-off Composer commands
+docker compose exec web composer require some/package
+docker compose exec web composer install
+```
+
+Do not run `composer` on the host against a Docker project unless your host PHP meets Shopware's requirements (`memory_limit ≥ 512M` and the needed extensions). The TUI **Setup health** memory check reflects the container runtime, not host PHP. Details: [Running Composer, PHP, and npm](./dev-environment.md#running-composer-php-and-npm).
+
+:::info Older make-based setups
+If your project still uses the older `make`-based workflow:
 
 ```bash
 make shell
+# or
 docker compose exec web bash
 ```
 
-Most tasks are now easier with `shopware-cli project console` and the development TUI.
+Prefer `shopware-cli project console` and the development TUI for console and day-to-day environment tasks.
 :::
 
 ## Frontend development
@@ -135,13 +151,20 @@ Create a `.env` file in the project root to override defaults. Most changes appl
 
 ## Shopware account and private Composer packages
 
-To install licensed extensions from Shopware's private Composer registry:
+To install licensed extensions from Shopware's private Composer registry, configure Composer authentication. Prefer a project-level `auth.json` in the project root so both host tooling and the bind-mounted web container can use it:
+
+```bash
+# Writes auth.json in the project root (bind-mounted into the web container)
+composer config --auth http-basic.packages.shopware.com <username> <token>
+```
+
+Then install packages with Composer **inside** the container:
 
 ```bash
-composer config --global http-basic.packages.shopware.com <username> <token>
+docker compose exec web composer require <package>
 ```
 
-Create an access token in your Shopware account under **Shops > Licenses**.
+Create an access token in your Shopware account under **Shops > Licenses**. Do not commit `auth.json`.
 
 ## Next steps
 

guides/installation/index.md

@@ -105,6 +105,10 @@ This launches the Development TUI. The dashboard starts your Docker containers,
 
 For details, see the [Development Environment guide](../development/dev-environment.md).
 
+::: tip Composer and PHP with Docker
+If you chose Docker, run Composer and PHP tools **inside** the `web` container (`docker compose exec web composer …`). Host PHP often has only `128M` memory and cannot reach the database; Shopware needs `memory_limit ≥ 512M`. See [Running Composer, PHP, and npm](../development/dev-environment.md#running-composer-php-and-npm).
+:::
+
 ### Accessing your shop
 
 When the environment is running, your shop is accessible at:

guides/installation/project-overview.md

@@ -36,10 +36,13 @@ In day-to-day development, you'll mostly interact with:
 - **`shopware-cli project dev`**: starts and manages the Docker-based development environment, including containers, logs, watchers, credentials, and service URLs.
 - **`shopware-cli project console <command>`**: runs Shopware application commands from your host without opening an interactive container shell.
 - **`swx <command>`**: shortcut for `shopware-cli project console <command>`, for example `swx cache:clear`.
+- **`docker compose exec web …`**: runs Composer, PHP, or npm inside the web container (required for Docker projects; do not use host Composer by default).
 - **`custom/`**: where you build your own plugins and themes.
 
 `bin/console` is the application CLI that ships with Shopware (Symfony console). Use it for Shopware application commands such as migrations, plugin installation, cache clearing, or configuration changes. In Docker-based setups, run those commands through `shopware-cli project console` or `swx` so they execute in the correct container context.
 
+For Composer and other PHP tools in Docker setups, use `docker compose exec web composer …`. The project files are bind-mounted for editing on the host, but host PHP does not share the container's memory limit or service network. Shopware requires `memory_limit ≥ 512M`. See [Running Composer, PHP, and npm](../development/dev-environment.md#running-composer-php-and-npm).
+
 The standalone [Shopware CLI](https://github.com/shopware/shopware-cli) is different from `bin/console`: it manages project workflows such as the development environment, helper commands, extension builds, and CI workflows.
 
 ## Project template

products/tools/cli/index.md

@@ -17,7 +17,9 @@ nav:
 
 For GitHub Actions, GitLab CI, and Docker examples, see [CI/CD and development environments](installation.md#cicd-and-development-environments).
 
-Shopware CLI runs on macOS, Linux, and via Docker. For system-level requirements (PHP, DB, memory, etc.) see the [System Requirements](../../../guides/installation/system-requirements.md). Windows users should use WSL 2 or Docker. (See [Installation Options](installation.md) page for Windows details.)
+Shopware CLI runs on macOS, Linux, and via Docker. For workstation hardware requirements, see the [System Requirements](../../../guides/installation/system-requirements.md). For PHP and stack requirements — including **`memory_limit ≥ 512M`** — see the [recommended stack](../../../guides/hosting/index.md#recommended-stack-and-supported-versions). Windows users should use WSL 2 or Docker. (See [Installation Options](installation.md) page for Windows details.)
+
+When you use the Docker-based development environment, run Composer and PHP tools inside the web container rather than on the host. See [Running Composer, PHP, and npm](../../../guides/development/dev-environment.md#running-composer-php-and-npm).
 
 ## Quickstart
 

products/tools/cli/project-commands/dev-environment.md

@@ -77,4 +77,5 @@ environments:
 ## Further reading
 
 - [Development Environment guide](../../../../guides/development/dev-environment.md) — full workflow, setup wizard, service overview, troubleshooting
+- [Running Composer, PHP, and npm](../../../../guides/development/dev-environment.md#running-composer-php-and-npm) — run tools inside the web container; PHP `memory_limit ≥ 512M`
 - [Start Developing](../../../../guides/development/start-developing.md) — next steps after your environment is running

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

@@ -50,6 +50,8 @@ shopware-cli project dev stop
 shopware-cli project logs
 ```
 
+With Docker projects, run Composer and other PHP tools **inside** the web container (`docker compose exec web composer …`), not on the host. Host PHP often has a too-low `memory_limit` (Shopware needs at least `512M`). Details: [Running Composer, PHP, and npm](../../../../guides/development/dev-environment.md#running-composer-php-and-npm).
+
 ## Replacements to include in shell scripts
 
 Shopware CLI contains replacements for `bin/build-administration.sh` and `bin/build-storefront.sh`.