From 77ce07c5eff123b54e41c2b3ea489680339cefb9 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Wed, 12 Aug 2026 08:45:04 +0200 Subject: [PATCH] docs: document Composer-in-container and PHP memory limit for CLI Docker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarify that Docker projects should run Composer inside the web container, that the TUI runtime memory check does not cover host PHP, and that Shopware requires memory_limit ≥ 512M when running PHP on the host. Related to shopware/shopware-cli#1343. --- guides/development/dev-environment.md | 58 ++++++++++++++++++- guides/development/start-developing.md | 37 +++++++++--- guides/installation/index.md | 4 ++ guides/installation/project-overview.md | 3 + products/tools/cli/index.md | 4 +- .../cli/project-commands/dev-environment.md | 1 + .../cli/project-commands/helper-commands.md | 2 + 7 files changed, 98 insertions(+), 11 deletions(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index 846c3f0ce..7ae217480 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -53,7 +53,7 @@ Your environment at a glance: - **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 you confirm, the wizard: ### 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 plugin:refresh 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 @@ Check logs with `shopware-cli project logs -f` or from the Instance tab in the T 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 +``` + +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). diff --git a/guides/development/start-developing.md b/guides/development/start-developing.md index f2f59fa43..8ab4594b1 100644 --- a/guides/development/start-developing.md +++ b/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 +``` + +Then install packages with Composer **inside** the container: ```bash -composer config --global http-basic.packages.shopware.com +docker compose exec web composer require ``` -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 diff --git a/guides/installation/index.md b/guides/installation/index.md index c92a805ee..5dc51f1ac 100644 --- a/guides/installation/index.md +++ b/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: diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md index 7db6b8c8f..123d8ab1c 100644 --- a/guides/installation/project-overview.md +++ b/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 `**: runs Shopware application commands from your host without opening an interactive container shell. - **`swx `**: shortcut for `shopware-cli project console `, 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 diff --git a/products/tools/cli/index.md b/products/tools/cli/index.md index 05801da90..77cb7bde4 100644 --- a/products/tools/cli/index.md +++ b/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 diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md index 71c375aba..da6031e71 100644 --- a/products/tools/cli/project-commands/dev-environment.md +++ b/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 diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index 8ab49fc3a..353934af9 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/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`.