diff --git a/guides/installation/requirements.md b/guides/installation/requirements.md index 205f83a65..cd7ddc124 100644 --- a/guides/installation/requirements.md +++ b/guides/installation/requirements.md @@ -7,81 +7,205 @@ nav: # Requirements -This page lists the system requirements and supported software versions for developing Shopware 6. Find installation steps for each setup method on their respective pages: +Before installing Shopware 6, take a quick look at the requirements below to check if your local environment is capable of running it. -- [Docker setup](./setups/docker.md); recommended for most users -- [Devenv setup](./setups/devenv.md) -- [Symfony CLI](./setups/symfony-cli.md) +## Operating System -## Requirements for all setups +Shopware 6 is currently only supported on any Unix operating system. Windows is only supported inside WSL 2 or Docker. -Before setting up your Shopware 6 development environment, make sure your system is ready. Check these basics before installation: +## Versions -- You’re using a Unix-based system (macOS or Linux), or Windows with WSL 2 or Docker for full compatibility -- You have admin/root privileges (if required in your organization) -- [Git](https://git-scm.com/) installed and available in your `PATH` -- You have at least 8 GB RAM (16 GB recommended) and 10 GB free disk space -- Docker Desktop, PHP, or Nix are not already bound to conflicting ports -- You have a reliable Internet connection for dependency downloads +You can use these commands to check your actual environment: -## Hardware recommendations +::: info +On many shared hosting environments, you have multiple PHP versions installed. +Make sure that you use the correct PHP binary, as often CLI and FPM have different `php.ini` files. +Ask your hosting provider for the correct PHP binary to use and how to change the `php.ini` file. +::: + +* `php -v`: Shows CLI PHP version +* `php -m`: Shows CLI PHP modules +* `php -i | grep memory_limit`: Shows your actual CLI PHP memory limit +* `composer -V`: Shows your actual composer version +* `node -v`: Shows your actual Node version +* `npm -v`: Shows your actual NPM version + +### PHP + +* Compatible version: 8.2, 8.3, 8.4 and 8.5 +* `memory_limit` : 512M minimum +* `max_execution_time` : 30 seconds minimum +* Extensions: + * `ext-amqp` (only required if you plan to use a message queue, which is the default on PaaS) + * `ext-curl` + * `ext-dom` + * `ext-fileinfo` + * `ext-gd` + * `ext-iconv` + * `ext-intl` + * `ext-mbstring` + * `ext-openssl` + * `ext-pcre` + * `ext-pdo` + * `ext-pdo_mysql` + * `ext-phar` + * `ext-simplexml` + * `ext-xml` + * `ext-zip` + * `ext-zlib` +* Composer recommended version: 2.2 or higher + +This is how you install PHP and Composer: + + + + + +Add a new software repository to your system to have the latest PHP version. + +```bash +sudo add-apt-repository ppa:ondrej/php + +sudo apt-get install -y php8.4-fpm php8.4-mysql php8.4-curl php8.4-gd php8.4-xml php8.4-zip php8.4-opcache php8.4-mbstring php8.4-intl php8.4-cli + +sudo wget https://getcomposer.org/download/latest-stable/composer.phar -O /usr/local/bin/composer +sudo chmod +x /usr/local/bin/composer +``` + + + + + +Add a new software repository to your system to have the latest PHP version: + +```bash +sudo apt-get install extrepo +sudo extrepo enable sury + +sudo apt-get update +sudo apt-get install -y php8.4-fpm php8.4-mysql php8.4-curl php8.4-gd php8.4-xml php8.4-zip php8.4-opcache php8.4-mbstring php8.4-intl php8.4-cli + +sudo wget https://getcomposer.org/download/latest-stable/composer.phar -O /usr/local/bin/composer +sudo chmod +x /usr/local/bin/composer +``` + + + + + +```bash +brew install php@8.4 composer +``` + + + + + +### SQL + +* MySQL + + * Recommended version: 8.4 + * Minimum version: 8.0.22 + +* MariaDB + + * Recommended version: 11.8 + * Minimum version : 10.11.6 or 11.0.4 -These recommendations ensure smooth local development regardless of setup: +For optimal MySQL performance, it is advisable to set `max_allowed_packet` to a minimum of 32 MB. -| Component | Recommended | -|:---------------------|:-------------------------------------------------------------| -| **CPU** | Quad-core or higher | -| **Memory (RAM)** | 8 GB minimum, 16 GB recommended (especially for Docker) | -| **Disk space** | ~10 GB free for Shopware + services | -| **Operating system** | macOS 13+, Windows 10/11 (Pro with WSL 2), or Linux (64-bit) | +This is how you install MariaDB: -## Permissions and networking + -- Ensure Docker or Symfony CLI has permission to bind to local ports (typically:80 or:8080). -- Allow your system’s firewall to let containers or local web servers communicate internally. -- On Linux, you may need to add your user to the `docker` group: + ```bash -sudo usermod -aG docker $USER +sudo apt install -y mariadb-server ``` -## Recommended stack and supported versions + -The following versions and configurations are officially supported for Shopware 6 development: + -| Component | Install | Minimum Version | Recommended | Required / Notes | -|:---------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------|:-------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **PHP** | [PHP installation guide](https://www.php.net/manual/en/install.php)
[Composer installation guide](https://getcomposer.org/download/) | 8.2+ | 8.4 | **Required.**
`memory_limit ≥ 512M`, `max_execution_time ≥ 30s`.
Required extensions: `ctype`, `curl`, `dom`, `fileinfo`, `gd`, `iconv`, `intl`, `mbstring`, `openssl`, `pcre`, `pdo_mysql`, `phar`, `simplexml`, `xml`, `zip`, `zlib`.
Optional: `amqp` (for message queues).
Composer 2.2+ recommended.
**macOS note:** If you install PHP with Homebrew, the `intl` extension may not be included by default. Install it separately:
`brew install php-intl` then verify with `php -m | grep intl`. | -| **SQL** | [MariaDB installation guide](https://mariadb.com/kb/en/getting-installing-and-upgrading-mariadb/)
[MySQL installation guide](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/) | MariaDB ≥ 10.11.6 or MySQL ≥ 8.0.22 | MariaDB 11.4 / MySQL 8.4 | **Required.**
`max_allowed_packet ≥ 32M` for optimal performance. | -| **Node.js / npm** | [Node.js downloads](https://nodejs.org/en/download) | Node 20.0.0+ | Node 24 / npm 10 | **Required.** | -| **Search** | [OpenSearch installation guide](https://opensearch.org/docs/latest/install-and-configure/install-opensearch/index/) | OpenSearch 1.0+ or ElasticSearch 7.8+ | OpenSearch 2.17.1 | **Optional.** Used for product search and indexing.
**Note**: The search preview in the administration requires OpenSearch 2.12+ or Elasticsearch 8.8+.
Support for OpenSearch 3.1 was added in shopware v6.7.3.1 | -| **Cache / KV store** | [Valkey](https://valkey.io/)
[Redis](https://redis.io) / [Redict](https://redict.io) / [Dragonfly](https://www.dragonflydb.io) | Redis v7+ | Valkey 8.0 | **Optional.** Used for caching and session storage.
Redis-protocol compatible alternatives supported.
`maxmemory-policy: volatile-lfu`. | -| **Web server** | [Caddy setup guide](https://developer.shopware.com/docs/resources/references/config-reference/server/caddy.html)
[Apache](https://developer.shopware.com/docs/resources/references/config-reference/server/apache.html)
[Nginx](https://developer.shopware.com/docs/resources/references/config-reference/server/nginx.html) | Any | Caddy | **Required.** For local development, the [Symfony CLI server](https://symfony.com/doc/current/setup/symfony_cli.html) works out of the box. | -| **Queue** | [RabbitMQ downloads](https://www.rabbitmq.com/download.html)
[AWS SQS](https://aws.amazon.com/sqs/) | Any transport supported by the [symfony messenger component](https://symfony.com/doc/current/messenger.html#transport-configuration) | RabbitMQ | **Optional.** By default the SQL database will be used as a queue, however in production setups it is highly recommended to use a dedicated queue system for scalability and observability reasons. | +The easiest way is to use [Homebrew](https://brew.sh/): -See also: [PHP performance tweaks guide](https://developer.shopware.com/docs/guides/hosting/performance/performance-tweaks.html#php-config-tweaks) +```bash +brew install mariadb +``` -## Verifying your local environment + -Use the following commands to verify your local environment: + + +### JavaScript ::: info -On many systems or hosting environments, multiple PHP versions may be installed. -Make sure to use the correct PHP binary, as CLI and FPM often have different `php.ini` files. -Ask your hosting provider for the correct PHP binary and how to adjust `php.ini`. +JavaScript/Node.js is optional and only required for local development on your developer machine. ::: -- `php -v`: Show CLI PHP version -- `php -m`: List CLI PHP modules -- `php -i | grep memory_limit`: Show your CLI PHP memory limit -- `composer -V`: Show Composer version -- `node -v`: Show Node version -- `npm -v`: Show npm version +* Node.js + + * Recommended version: 24.0.0 or higher + * Minimum version: 20.0.0 + +This is how you install Node.js: + + + + + +```bash +curl -fsSL https://deb.nodesource.com/setup_24.x -o nodesource_setup.sh +sudo -E bash nodesource_setup.sh + +sudo apt-get install -y nodejs +``` + + + + + +```bash +brew install node@24 +``` + + + + + +## Redis or key/value stores + +Shopware uses the Redis Protocol and, therefore, supports the following key/value stores: + +* [Valkey (recommended)](https://valkey.io/) +* [Redis v7 or higher](https://redis.io) + +* Recommended configuration `maxmemory-policy`: `volatile-lfu` + +## Webserver + +To run Shopware in a development context, the [Symfony CLI](https://symfony.com/doc/current/setup/symfony_server.html) will work nicely. + + + + + +## Recommended stack + +We recommend the following stack: + +* Webserver: FrankenPHP (Caddy) +* PHP: 8.4 +* SQL: MariaDB 11.8 +* Search: OpenSearch 2.17.1 +* Queue: RabbitMQ +* Cache: Valkey 8.0 -## Next steps +Recommended PHP ini: + -Once your environment meets these requirements, proceed to your preferred installation method: +## Setup -- [Docker setup](./setups/docker.md) -- [Symfony CLI setup](./setups/symfony-cli) -- [Devenv setup](./setups/devenv.md) +Once the requirements are fulfilled, follow up with the [Template](template) guide to set up Shopware.