docs: document Composer-in-container and PHP memory limit for CLI Docker - #2436
Open
Soner (shyim) wants to merge 1 commit into
Open
docs: document Composer-in-container and PHP memory limit for CLI Docker#2436Soner (shyim) wants to merge 1 commit into
Soner (shyim) wants to merge 1 commit into
Conversation
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.
Developer Docs healthcheckStatus: Completed with |
Contributor
📊 Documentation Impact Analyzer
Reasons
|
Contributor
There was a problem hiding this comment.
Pull request overview
Documents the Docker-first workflow for Shopware CLI projects by clarifying that Composer/PHP/npm commands should be executed inside the web container, and by surfacing the memory_limit ≥ 512M requirement and common host-side OOM troubleshooting across key entry points in the docs.
Changes:
- Adds cross-links and callouts to run Composer/PHP/npm inside
docker compose exec web …for Docker-based projects. - Clarifies that the DevTUI “Setup health → Runtime → Memory limit” reflects container PHP, not host PHP used by a local Composer binary.
- Adds a troubleshooting note for the common host-side memory exhaustion error (
Allowed memory size of 134217728 bytes exhausted).
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| products/tools/cli/project-commands/helper-commands.md | Adds a Docker-specific note linking to the new “Running Composer, PHP, and npm” section and the memory limit requirement. |
| products/tools/cli/project-commands/dev-environment.md | Adds an additional “Further reading” entry pointing to the new container-tools guidance. |
| products/tools/cli/index.md | Updates requirements guidance to point to hosting “recommended stack” (incl. memory limit) and links Docker users to the new section. |
| guides/installation/project-overview.md | Adds docker compose exec web … as a core day-to-day command and explains why host Composer/PHP differs from container runtime. |
| guides/installation/index.md | Adds a tip admonition emphasizing container-executed Composer/PHP tools for Docker installs and links to the new section. |
| guides/development/start-developing.md | Adds a dedicated section on running Composer inside the container and updates private Composer registry auth guidance. |
| guides/development/dev-environment.md | Expands DevTUI runtime/memory explanation, adds a new “Running Composer, PHP, and npm” section, and adds OOM troubleshooting. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| 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). |
| 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). |
| - **`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). |
|
|
||
| `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). |
| - **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 |
|
|
||
| ```bash | ||
| # Writes auth.json in the project root (bind-mounted into the web container) | ||
| composer config --auth http-basic.packages.shopware.com <username> <token> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
webcontainer (docker compose exec web …), not on the host.memory_limit ≥ 512Mon the CLI/dev documentation path (installation, start-developing, CLI index, helper commands).Allowed memory size of 134217728 bytes exhausted).Addresses the documentation gap discussed in shopware/shopware-cli#1343.
Test plan
#running-composer-php-and-npmworks in the developer portal preview