From 355cfd7aca108d1ffe68ba9ca668997e864ef53f Mon Sep 17 00:00:00 2001 From: LApple Date: Wed, 11 Feb 2026 10:28:20 +0100 Subject: [PATCH 01/45] docs: restructures installation and moves legacy setups --- guides/hosting/index.md | 33 ++ .../docker-options.md => advanced-options.md} | 99 ++---- guides/installation/after-installation.md | 237 ++++++++++++++ guides/installation/docker-setup.md | 114 +++++++ guides/installation/hardware-requirements.md | 35 +++ guides/installation/index.md | 38 --- guides/installation/installation-intro.md | 46 +++ guides/installation/project-overview.md | 73 +++++ guides/installation/requirements.md | 87 ------ guides/installation/setups/docker.md | 288 ------------------ guides/installation/setups/index.md | 130 -------- guides/installation/template.md | 239 --------------- .../devenv-options.md | 0 .../devenv-setup.md} | 4 +- guides/legacy-setups/setup-symfony-cli.md | 174 +++++++++++ .../symfony-cli-setup.md} | 4 +- .../add-custom-commands.md | 134 +------- index.md | 2 + 18 files changed, 744 insertions(+), 993 deletions(-) rename guides/installation/{setups/docker-options.md => advanced-options.md} (56%) create mode 100644 guides/installation/after-installation.md create mode 100644 guides/installation/docker-setup.md create mode 100644 guides/installation/hardware-requirements.md delete mode 100644 guides/installation/index.md create mode 100644 guides/installation/installation-intro.md create mode 100644 guides/installation/project-overview.md delete mode 100644 guides/installation/requirements.md delete mode 100644 guides/installation/setups/docker.md delete mode 100644 guides/installation/setups/index.md delete mode 100644 guides/installation/template.md rename guides/{installation/setups => legacy-setups}/devenv-options.md (100%) rename guides/{installation/setups/devenv.md => legacy-setups/devenv-setup.md} (99%) create mode 100644 guides/legacy-setups/setup-symfony-cli.md rename guides/{installation/setups/symfony-cli.md => legacy-setups/symfony-cli-setup.md} (98%) diff --git a/guides/hosting/index.md b/guides/hosting/index.md index 4572d28d17..0924c3abc8 100644 --- a/guides/hosting/index.md +++ b/guides/hosting/index.md @@ -8,3 +8,36 @@ nav: # Hosting Setting up an operating environment for Shopware can be hard, but it doesn't have to be if you follow some general guidelines in the subsequent sections. + +## 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. | + +See also: [PHP performance tweaks guide](https://developer.shopware.com/docs/guides/hosting/performance/performance-tweaks.html#php-config-tweaks) + +## Verifying your local environment + +Use the following commands to verify your local environment: + +::: 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`. +::: + +- `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 \ No newline at end of file diff --git a/guides/installation/setups/docker-options.md b/guides/installation/advanced-options.md similarity index 56% rename from guides/installation/setups/docker-options.md rename to guides/installation/advanced-options.md index 2835078d09..4f64eb40af 100644 --- a/guides/installation/setups/docker-options.md +++ b/guides/installation/advanced-options.md @@ -1,95 +1,50 @@ --- nav: - title: Additional Docker Options - position: 40 + title: Advanced Options + position: 6 --- -# Additional Docker Options +# Advanced options -## Connecting to a remote database +This page covers optional and advanced Docker configuration for Shopware projects. You can refer to information here once your local environment is running and you want to customize your environment, mirror production more closely, or support advanced workflows. -If you want to use a database outside the Docker stack (running on your host or another server, for examples), set `DATABASE_URL` in `.env.local` in the standard form: +## Customizing the runtime environment -```bash -DATABASE_URL="mysql://user:password@:3306/" -``` - -Note: containers cannot always reach services bound only to the host's `localhost`. If `localhost` does not work you can try `host.docker.internal`, your host machine’s LAN IP, or add an `extra_hosts` entry in `compose.yaml`. - -## Enable profiler/debugging for PHP - -Once your Shopware environment is running, you may want to enable PHP debugging or profiling to inspect code execution, set breakpoints, or measure performance. The default setup doesn’t include these tools, but you can enable them using Docker overrides. - -### Enable Xdebug - -To enable [Xdebug](https://xdebug.org/) inside the web container, create a `compose.override.yaml` in your project root with the following configuration: - -```yaml -services: - web: - environment: - - XDEBUG_MODE=debug - - XDEBUG_CONFIG=client_host=host.docker.internal - - PHP_PROFILER=xdebug -``` - -After saving the file, apply the changes: - -```bash -docker compose up -d -``` - -This restarts the containers with Xdebug enabled. You can now attach your IDE (for example, PHPStorm or VS Code) to the remote debugger on the default Xdebug port `9003`. +### Image variations -Shopware’s Docker setup also supports other profilers, like [Blackfire](https://www.blackfire.io/), [Tideways](https://tideways.com/), and [PCOV](https://github.com/krakjoe/pcov). For Tideways and Blackfire, you'll need to run an additional container. For example: - -```yaml -services: - web: - environment: - - PHP_PROFILER=blackfire - blackfire: - image: blackfire/blackfire:2 - environment: - BLACKFIRE_SERVER_ID: XXXX - BLACKFIRE_SERVER_TOKEN: XXXX -``` +Shopware provides multiple Docker image variants so you can match your local setup to your project's PHP version, Node version, and preferred web server. The image tag format is `ghcr.io/shopware/docker-dev:php(PHP_VERSION)-node(NODE_VERSION)-(WEBSERVER)`. -## Image variations +Version matrix: -The Shopware Docker image is available in several variations, allowing you to match your local setup to your project’s PHP version, Node version, and preferred web server. Use the following pattern to select the right image tag: - -`ghcr.io/shopware/docker-dev:php(PHP_VERSION)-node(NODE_VERSION)-(WEBSERVER)` - -Here’s the version matrix: - -PHP versions: +PHP versions - `8.4` - PHP 8.4 - `8.3` - PHP 8.3 - `8.2` - PHP 8.2 -Node versions: +Node versions - `node24` - Node 24 - `node22` - Node 22 -Web server: +Web server - `caddy` - Caddy as web server - `nginx` - Nginx as web server -Example: +Examples - `ghcr.io/shopware/docker-dev:php8.4-node24-caddy` - PHP 8.4, Node 24, Caddy as web server - `ghcr.io/shopware/docker-dev:php8.3-node24-caddy` - PHP 8.3, Node 24, Caddy as web server - `ghcr.io/shopware/docker-dev:php8.4-node22-nginx` - PHP 8.4, Node 22, Nginx as web server - `ghcr.io/shopware/docker-dev:php8.3-node22-nginx` - PHP 8.3, Node 22, Nginx as web server -## Adding Minio for local S3 storage +Choose the variant that best matches your production stack. + +## Adding S3-compatible storage (Minio) -Some projects use Amazon S3 for file storage in production. If you want to mimic that behavior locally—for example, to test uploads or CDN-like delivery—you can add [Minio](https://www.min.io/), an open-source S3-compatible storage server. +Some projects use Amazon S3 for file storage in production. If you want to mimic that behavior locally—for example, to test uploads or CDN-like delivery—you can add [Minio](https://www.min.io/), which is an open-source, S3-compatible storage server. ### 1. Add the Minio service @@ -139,7 +94,7 @@ volumes: ### 2. Configure Shopware to use Minio -Create a new YAML file at `config/packages/minio.yaml` with the following content: +Create a `config/packages/minio.yaml`: ```yaml # yaml-language-server: $schema=https://raw.githubusercontent.com/shopware/shopware/refs/heads/trunk/config-schema.json @@ -186,8 +141,7 @@ bin/console theme:compile ## Using OrbStack routing -If you're using [OrbStack](https://orbstack.dev) on macOS, you can take advantage of its built-in routing feature. -OrbStack automatically assigns local `.orb.local` URLs to your containers, so you don’t need to manage port mappings manually. This allows running multiple Shopware instances at the same time without port conflicts. +If you're using [OrbStack](https://orbstack.dev) on macOS, you can avoid manual port management by using its built-in routing feature. OrbStack automatically assigns local `.orb.local` URLs to your containers, which allows running multiple Shopware instances at the same time without port conflicts. To enable it, create a `compose.override.yaml` in your project root with the following content: @@ -213,16 +167,11 @@ The APP_URL environment variable follows this pattern: `web..orb.l You can also open `https://orb.local` in your browser to view all running containers and their assigned URLs. -## Proxy production images +## Working with production data locally -When you import a production database into your local environment, image URLs in the data may still point to production servers. As a result, your local store might show broken or missing images. You can fix this in two ways: +When importing production databases into your local environment, image URLs in the data may still point to production servers—leading to broken or missing images in your local store. You can proxy those images locally instead of downloading everything. -- **download all production images** and import them locally, or -- **set up a lightweight proxy service** that serves those images directly from the production server (recommended for quick testing). - -### 1. Add the image proxy service - -Add a `imageproxy` service to your `compose.override.yaml`: +Add the `imageproxy` service to your `compose.override.yaml`: ```yaml services: @@ -237,9 +186,7 @@ services: This starts a proxy server that fetches images from the production environment and caches them locally. For example, a request to `http://localhost:8050/assets/images.png` will be served from `https://[REMOTE_SERVER_HOST]/assets/images.png` and then stored in the local cache for faster reuse. -### 2. Point Shopware to the proxy - -Next, we need to configure Shopware to use the proxy server. To do this, create a new YAML file `config/packages/media-proxy.yaml` +Next, configure Shopware to use the proxy server. Create a new YAML file `config/packages/media-proxy.yaml`: ```yaml shopware: @@ -248,4 +195,4 @@ shopware: url: "http://localhost:8050" ``` -This tells Shopware to use the proxy server URL for all images. +Images are fetched from production on demand and cached locally. diff --git a/guides/installation/after-installation.md b/guides/installation/after-installation.md new file mode 100644 index 0000000000..61e909b918 --- /dev/null +++ b/guides/installation/after-installation.md @@ -0,0 +1,237 @@ +--- +nav: + title: After installation + position: 5 + +--- + +# After installation + +You now have a running Shopware instance. This page explains what you typically do next, in the order most developers need it. + +## Start developing + +### Administration & Storefront + +- Storefront: [http://localhost:8000](http://localhost:8000) +- Administration: [http://localhost:8000/admin](http://localhost:8000/admin) *(default credentials: `admin` / `shopware`)* + +Most day-to-day work happens in: + +- `custom/`: your plugins and themes +- `bin/console`: application CLI (Symfony console) +- the Administration UI + +### Using the Shopware CLI + +To run CLI commands, open a shell inside the web container: + +```bash +make shell +``` + +This command drops you into the container’s terminal (you’ll see the prompt change). + +From inside the container, use: + +```bash +bin/console +``` + +Development and automation tasks are handled in the CLI, including: + +- installing and activating plugins +- clearing caches +- running migrations +- adjusting system configuration +- developing plugins and themes + +**Tip**: Inside the container, you only need `bin/console …`. But if you prefer to run commands from your host machine instead, you can use the full Docker prefix: `docker compose exec web bin/console cache:clear`. + +Please note that some setup tasks are done in the Administration UI, including: + +- Opening the **Admin** at +- Signing in or creating a Shopware account; necessary when you want to install Store extensions. +- Connecting to the **Shopware Store** +- Installing plugins or themes from the Store +- Connecting payment methods; not necessary for local development + +Basic shop settings such as shop name, default language, and currency can be changed later in the Admin under **Settings > Shop > Basic information**. + +## Frontend and Administration development + +When you modify Storefront or Administration code, or develop plugins that affect the UI, you’ll use these Makefile commands: + +```bash +# Build the administration (admin panel) +make build-administration + +# Build the storefront (shop frontend) +make build-storefront + +# Start a watcher to rebuild the Administration automatically when files change +make watch-admin + +# Start a watcher for Storefront +make watch-storefront +``` + +These will become part of your everyday development workflow. Watchers are typically used during active UI development. + +## Inspecting and debugging locally + +If you connect to the database from your host machine—for example, via Adminer or a local MySQL client—use `127.0.0.1` or `localhost` and the exposed port shown in `docker compose ps`. + +## Local services overview + +With Shopware running, your local setup includes a web service that serves both the storefront and the Administration. By default this uses Caddy with PHP-FPM, but you may use Nginx instead. Knowing which service does what helps when debugging or connecting external tools. + +### Accessing services + +Your local stack includes: + +- Database (MariaDB): runs on port 3306 inside Docker. + - Internal hostname: `database` + - Host access: `localhost:3306`, if you want to inspect the database directly. +- Mailpit local mail testing tool: available at [http://localhost:8025](http://localhost:8025). Use this to view emails sent by Shopware (e.g., registration or order confirmations) without needing an external mail server. +- Adminer (database UI): Lightweight web interface for viewing and editing your database, available at [http://localhost:8080](http://localhost:8080). + +Inspect ports and services with: + +```bash +docker compose ps +``` + +### Enable profiler/debugging for PHP + +Once your Shopware environment is running, you may want to enable PHP debugging or profiling to inspect code execution, set breakpoints, or measure performance. The default setup doesn’t include these tools, but you can enable them using Docker overrides. + +As an example, enable [Xdebug](https://xdebug.org/) inside the web container by creating a `compose.override.yaml` in your project root with the following configuration: + +```yaml +services: + web: + environment: + - XDEBUG_MODE=debug + - XDEBUG_CONFIG=client_host=host.docker.internal + - PHP_PROFILER=xdebug +``` + +Save the file and apply the changes: + +```bash +docker compose up -d +``` + +This restarts the containers with Xdebug enabled. You can now attach your IDE (for example, PHPStorm or VS Code) to the remote debugger on the default Xdebug port `9003`. + +Shopware’s Docker setup also supports other profilers, like [Blackfire](https://www.blackfire.io/), [Tideways](https://tideways.com/), and [PCOV](https://github.com/krakjoe/pcov). For Tideways and Blackfire, you'll need to run an additional container. For example: + +```yaml +services: + web: + environment: + - PHP_PROFILER=blackfire + blackfire: + image: blackfire/blackfire:2 + environment: + BLACKFIRE_SERVER_ID: XXXX + BLACKFIRE_SERVER_TOKEN: XXXX +``` + +## Adjusting your local environment + +### Environment variables + +You can create a `.env` file in the project root to override default environment variables. Most changes take effect automatically without restarting containers. Changes to `APP_ENV` require a restart: + +```bash +make up +``` + +### Docker overrides + +Use `compose.override.yaml` to: + +- change ports +- add services +- enable debugging +- adjust networking + +This keeps your changes local and out of version control. + +## Working with data & external systems + +### Store API access key + +During setup, an access key is automatically generated for your default Sales Channel, which is usually the Storefront. You’ll see an output similar to this: + +```bash +Access tokens: ++------------+----------------------------+ +| Key | Value | ++------------+----------------------------+ +| Access key | `string of capital letters` | +``` + +The access key for authenticating requests to the [Store API](../../../concepts/api/store-api)—for example, when fetching product or category data from an external app, headless storefront, or API client. Example usage: + +```bash +curl -H "sw-access-key: YOUR_ACCESS_KEY" \ + http://localhost:8000/store-api/product +``` + +You can view or regenerate this key in the Admin under Sales Channels → [Your Channel] → API Access. + +## Connecting to a remote database + +If you want to use a database outside the Docker stack, set `DATABASE_URL` in `.env.local` in the standard form: + +```bash +DATABASE_URL="mysql://user:password@:3306/" +``` + +Containers cannot always reach services bound only to the host's `localhost`. If `localhost` does not work, try `host.docker.internal` or your host machine’s LAN IP, or add an `extra_hosts` entry in `compose.yaml`. + +## Running and maintaining the environment + +### Linux file permissions and known issues + +On Linux hosts, your user ID must be 1000 for file permissions to work correctly inside the containers. Check your user ID with: + +```bash +id -u +``` + +Other IDs may cause permission errors when running `make up` or writing to project files. + +## Preparing for production + +If you're preparing to run Shopware in production using Docker, [this page](../../hosting/installation-updates/docker.md) covers production images, environment configuration, and deployment workflows. + +## Build and Watch the Administration and Storefront + +You only need to run this step if you’re developing or customizing the frontend (Administration or Storefront). It compiles JavaScript and CSS assets so your changes are visible immediately. + +The created project contains Bash scripts in the `bin/` folder to build and watch the Administration and Storefront. Run the following commands: + +```bash +./bin/build-administration.sh +./bin/build-storefront.sh +./bin/watch-administration.sh +./bin/watch-storefront.sh +``` + +Use these scripts to build the Administration and Storefront. The `watch` commands will watch for changes in the Administration and Storefront and rebuild them automatically. + +## Advanced Docker configuration + +For advanced topics like: + +- image variants +- Minio (S3) +- OrbStack routing +- production image proxying +- service internals + +see [Advanced Options](advanced-options.md) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md new file mode 100644 index 0000000000..f31a73ecc7 --- /dev/null +++ b/guides/installation/docker-setup.md @@ -0,0 +1,114 @@ +--- +nav: + title: Docker Setup + position: 3 + +--- + +# Docker setup + +This guide is for developing Shopware stores and extensions. By the end of this page, you'll have a running empty Shopware instance and can immediately start working in the [Administration](https://developer.shopware.com/docs/concepts/framework/architecture/administration-concept.html). + +:::info +[Go here](../../hosting/installation-updates/docker.md) for information about using Docker for production. To contribute to the Shopware platform itself, visit our [Contributing.md guide](https://github.com/shopware/shopware/blob/trunk/CONTRIBUTING.md). +::: + +## Prerequisites + +- [Docker](https://docs.docker.com/get-started/get-docker/) or [OrbStack](https://docs.orbstack.dev/quick-start) is installed and running. OrbStack is a fast, free (for personal use) Docker-compatible replacement on macOS. + - Ensure Docker has permission to bind to local ports (typically:80 or:8080) and is not already bound to conflicting ports +- `make` is installed on your machine (`apt install make` on Ubuntu, `brew install make` on macOS) +- `Docker Compose` is installed on your machine. Docker Desktop provides it automatically. If you're using OrbStack or something else, you can follow the official [Docker Compose installation guide](https://docs.docker.com/compose/install/). +- Enough disk and network capacity to pull images (~500MB+ per image depending on tags) +- [Git](https://git-scm.com/) installed and available in your `PATH` + +This setup comes preinstalled with the [Shopware CLI](../../../products/cli/index.md), which helps with building, refactoring, validating, and managing Shopware projects and extensions. It works with all setups and is used in most Shopware upgrade, build, and CI workflows. The CLI is available in the container shell. + +## Pre-pull the image (optional) + +If you haven’t yet downloaded the Shopware Docker image, pull it now: + +```bash +docker pull ghcr.io/shopware/docker-dev:php8.3-node24-caddy +``` + +If you skip this step, Docker will automatically download the image during project creation. That’s normal, but pre-pulling makes the process cleaner and enables you to avoid waiting for large image downloads. + +## Create a new Shopware project + +Create an empty directory for your project and navigate into it: + +```bash +mkdir my-project && cd my-project +`` + +Now create a new project: + +```bash +docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup +``` + +To use a specific version of Shopware (optional), run: + +```bash +docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup 6.6.10.0 +``` + +This step creates your Shopware project using PHP and Composer inside the Docker image. It generates a ready-to-use setup including `compose.yaml` and a `Makefile`, so you don’t need to locally install PHP or Composer yourself. + +:::info +The Docker setup installs development dependencies (`require-dev`) and [`shopware/dev-tools`](https://github.com/shopware/dev-tools). This enables the Symfony profiler, [demo data](https://github.com/shopware/SwagPlatformDemoData), linters, and test tooling. +::: + +Project creation takes a few minutes to complete. In your terminal, this prompt will eventually appear: + +`Do you want to use Elasticsearch? (y/N)` + +Shopware supports an Elasticsearch-compatible search engine for improved performance with large catalogs and advanced search features. + +If you choose `y`, the Docker setup starts an Elasticsearch-compatible search service (OpenSearch) as part of your stack. + +If you choose `N`, Shopware will use MariaDB for search, which is sufficient for local testing or small datasets. + +## Initial setup + +After creating your project, you must install Shopware inside your containers. Run the setup commands below to initialize the database, generate configuration files, and create the default admin user. + +First, start the containers: + +```bash +make up +``` + +This command starts Shopware and all required services (web server, database, search, Mailpit, etc.) in the background. Docker images already include all required PHP extensions and services, so the system-check step of the installer is always fulfilled. + +**Tip:** You can check container status anytime with: + +```bash +docker compose ps +``` + +“Healthy” means the service passed its internal health check and is ready to use. + +Once the containers are running, install Shopware with this command: + +```bash +make setup +``` + +What happens during `make setup`: + +- The Makefile runs the Shopware installer inside the web container +- Shopware is installed automatically (no browser wizard required) +- A MariaDB database is created +- An admin user is created, with username `admin` and password `shopware` +- Required services (database, search, mail, etc.) are running inside Docker and already configured +- The Shopware project is configured to connect to the database via the Docker service name `database` +- Database credentials are defined in the `compose.yaml` +- If search was enabled during project creation, an Elasticsearch-compatible search service runs as part of the Docker stack + +You verify the installation succeeded by opening . + +Use `make up` and `make down` to start or stop your environment. Use `docker compose down -v` to fully reset it. The `-v` flag deletes the containers, networks, and volumes, meaning all stored data will be lost. + +On the next page, we'll help you to start developing. diff --git a/guides/installation/hardware-requirements.md b/guides/installation/hardware-requirements.md new file mode 100644 index 0000000000..3a76abfc67 --- /dev/null +++ b/guides/installation/hardware-requirements.md @@ -0,0 +1,35 @@ +--- +nav: + title: Hardware Requirements + position: 2 + +--- + +# Hardware requirements + +Before setting up your Shopware 6 development environment, make sure your system is ready. Check these basics before installation: + +- 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) +- You have at least 8 GB RAM (16 GB recommended) and 10 GB free disk space +- You have a reliable Internet connection for dependency downloads + +These recommendations ensure smooth local development regardless of your setup: + +| 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) | + +## Permissions and networking + +- 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 +``` + +Once your environment meets these requirements, proceed to [setup](./docker-setup.md). diff --git a/guides/installation/index.md b/guides/installation/index.md deleted file mode 100644 index 05292d81aa..0000000000 --- a/guides/installation/index.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -nav: - title: Installation - position: 10 - ---- - -# Overview — Shopware 6 Installation - -Welcome to the Shopware 6 Developer Installation Guide, which will help you set up a local Shopware 6 development environment whether you’re: - -- building a custom shop project -- developing a plugin, app, or theme -- contributing to the Shopware core - -You can choose from three supported setup options, each designed for specific use cases and development workflows. All setups start from the [Shopware Project Template](./template.md). - -## Shopware project template - -Every setup begins with the Project Template. It creates a new Composer project that includes Shopware as a dependency, allowing you to: - -- Extend the project with plugins, apps, or themes -- Customize configurations and services -- Align the environment with your development goals - -If you have downloaded the [shopware-installer.phar package](https://www.shopware.com/en/download/) instead of using Composer, skip the `composer create-project` step and follow the remaining instructions from the [Project Template](https://developer.shopware.com/docs/guides/installation/template.html) guide. - -## Supported setups - -| Setup | Description | Recommended For | -|:---------------------------------------------|:--------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------| -| [Docker Setup](./setups/docker.md) | A complete, containerized environment including all required services (database, search engine, cache, etc.). | Most developers — provides production-like conditions, consistent across teams and CI/CD. | -| [Symfony CLI Setup](./setups/symfony-cli.md) | Runs directly on your host system using local PHP and Composer. Lightweight and fast to start. | Quick plugin or theme development, or environments where Docker isn’t available. | -| [Devenv Setup](./setups/devenv.md) | A reproducible, Nix-based setup offering deterministic builds and cross-platform consistency. | Core contributors and advanced users managing multiple Shopware versions. | - -::: info -If you’re unsure which setup to choose, start with the Docker setup — it provides the smoothest onboarding experience. -::: diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md new file mode 100644 index 0000000000..e827a07453 --- /dev/null +++ b/guides/installation/installation-intro.md @@ -0,0 +1,46 @@ +--- +nav: + title: Shopware 6 Installation + position: 1 + +--- + +# Overview of Shopware 6 Installation + +Welcome to the Shopware 6 Developer Installation Guide, which will help you set up a local Shopware 6 development environment whether you’re: + +- building a custom shop project +- developing a plugin, app, or theme +- contributing to the Shopware core + +Our setup is based on [Docker](https://www.docker.com/), a platform that enables developers to develop, ship, and run applications inside containers: lightweight, standalone, and executable packages. Docker enables production-like conditions consistent across teams and CI/CD, and makes it easy to reset or rebuild environments (`docker compose down -v`). When you need you need full service parity (e.g. caching, queues, search), Docker shines. + +Our [Docker setup](./docker-setup.md) aims to provide a smooth onboarding experience aligned with modern development practices. It runs your entire Shopware environment in containers, including all backend services (PHP, MySQL, Node, an Elasticsearch-compatible search engine, Redis, Mailhog, etc.). No manual installation required. + +The pages that follow assume that you're using Docker itself. That said, the Shopware community has produced some related tooling for developers who prefer more automated or GUI-friendly ways to run Docker environments: DDEV and Dockware. Both are **community-maintained** and not officially supported by Shopware. + +## DDEV + +[DDEV](https://ddev.com/) is a developer-friendly wrapper around Docker that automates environment setup using simple CLI commands. Community members enjoy these features: + +- Simplifies Docker configuration: no manual `docker-compose.yml` needed. +- One command (`ddev start`) to start your Shopware environment. +- Easy to switch PHP/MySQL/Node versions per project. +- Integrates well with VS Code and PHPStorm. + +[DDEV with Shopware example →](https://github.com/ddev/test-shopware6) + +### Dockware setup + +[Dockware](https://www.dockware.io/) provides ready-to-run Docker images for quickly spinning up demo stores or full local environments in seconds. It emphasizes minimal setup over full customization. Community members enjoy these features: + +- Pre-built images for Shopware 5, 6, and nightly builds. +- Includes all key services: PHP, DB, Elasticsearch, Mailhog, Adminer, etc. +- Great for testing specific versions or quick evaluation. +- Can be used standalone or integrated into CI pipelines. + +[Dockware documentation →](https://docs.dockware.io/) + +:::info +Looking for older installation methods that are no longer recommended? See our [Legacy Installation Guides](./legacy-setups/). +::: diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md new file mode 100644 index 0000000000..a03e46e736 --- /dev/null +++ b/guides/installation/project-overview.md @@ -0,0 +1,73 @@ +--- +nav: + title: Project overview + position: 4 + +--- + +# Overview: Understanding your Shopware project + +You’ve just installed Shopware. But what exactly did you get? This page is an explainer to guide you through fundamentals you'll use through the rest of your development workflow. + +## Development tooling included + +The Docker setup installs Shopware with development dependencies (`require-dev`) enabled, including: + +- [`shopware/dev-tools`](https://github.com/shopware/dev-tools) +- Symfony profiler +- [Demo data](https://github.com/shopware/SwagPlatformDemoData) +- Linters and testing tools + +Your local project is ready for debugging, profiling, and extension development out of the box. + +In day-to-day development, you’ll mostly interact with: + +- **Makefile**: shortcuts for Docker and Shopware commands (`make up`, `make setup`, etc.) +- **custom/**: where you build your own plugins and themes +- **bin/console**: the application CLI that ships with Shopware (Symfony console). It's used for tasks like running migrations, installing plugins, clearing caches, or managing configuration inside your project. + +Note: `bin/console` is different from the standalone [Shopware CLI](https://github.com/shopware/shopware-cli) tool used for extension builds and CI workflows. The Docker setup already includes the standalone Shopware CLI inside the container. + +Most other files in the project either configure the environment or support these core layers. + +## Project template + +All setups start from the Shopware Project Template: a Composer-based project that installs Shopware as a dependency. It serves as the foundation for new Shopware projects as well as for developing plugins, apps, or themes. This allows you to: + +- extend the project with plugins, apps, or themes +- customize configuration and services +- tailor the environment to your development needs + +### Components explained + +The following table explains the Docker-level components created when you start the project. Container names depend on your project folder name. + +| Name | Type | Purpose | +|---------------------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------| +| **Network `my-project_default`** | Docker network | A private virtual network so all containers can communicate (for example, the web container connects to the database). | +| **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](http://localhost:8025). | +| **Container `my-project-database-1`** | MariaDB service | Runs the Shopware database. Inside the Docker network its host name 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](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](http://localhost:8080). | + +### Project structure explained + +This table outlines the key directories and files in your Shopware project and what they are used for. + +| Item | Type | Purpose / what it contains | Notes | +|---------------------------|-----------------------------|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| +| **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. | +| **config/** | Directory | Symfony configuration files (framework, database, mail, etc.). | Similar to `config/` in many web frameworks. | +| **custom/** | Directory | Your plugins, themes, or app customizations. | This is where you add new extensions — your “src” for Shopware plugins. | +| **files/** | Directory | Uploaded media and temporary files. | Ignored by git; generated at runtime. | +| **Makefile** | Build helper | Shortcuts for Docker tasks (`make up`, `make setup`, etc.). | Replaces long Docker commands with memorable aliases. | +| **public/** | Web root | The actual web-server-accessible directory (contains `index.php`, assets, etc.). | Like `/dist` in JS frameworks or `/public_html`. | +| **src/** | Source code | Shopware’s core application source. | Where the main PHP codebase lives; not usually edited in a project clone. | +| **symfony.lock** | Symfony dependency snapshot | Records Symfony recipes applied during setup. | Used internally by Symfony Flex; no manual editing. | +| **var/** | Runtime data | Cache, logs, temporary files. | Can safely be deleted (Shopware rebuilds it). | +| **vendor/** | Dependency code | All installed PHP libraries from Composer. | Analogous to `node_modules/`. | diff --git a/guides/installation/requirements.md b/guides/installation/requirements.md deleted file mode 100644 index 205f83a653..0000000000 --- a/guides/installation/requirements.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -nav: - title: Requirements - position: 1 - ---- - -# 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: - -- [Docker setup](./setups/docker.md); recommended for most users -- [Devenv setup](./setups/devenv.md) -- [Symfony CLI](./setups/symfony-cli.md) - -## Requirements for all setups - -Before setting up your Shopware 6 development environment, make sure your system is ready. Check these basics before installation: - -- 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 - -## Hardware recommendations - -These recommendations ensure smooth local development regardless of setup: - -| 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) | - -## 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 -``` - -## 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. | - -See also: [PHP performance tweaks guide](https://developer.shopware.com/docs/guides/hosting/performance/performance-tweaks.html#php-config-tweaks) - -## Verifying your local environment - -Use the following commands to verify your local environment: - -::: 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`. -::: - -- `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 - -## Next steps - -Once your environment meets these requirements, proceed to your preferred installation method: - -- [Docker setup](./setups/docker.md) -- [Symfony CLI setup](./setups/symfony-cli) -- [Devenv setup](./setups/devenv.md) diff --git a/guides/installation/setups/docker.md b/guides/installation/setups/docker.md deleted file mode 100644 index 4ad665ff19..0000000000 --- a/guides/installation/setups/docker.md +++ /dev/null @@ -1,288 +0,0 @@ ---- -nav: - title: Docker - position: 10 - ---- - -# Docker - -::: info -This setup is intended for development. If you want to use Docker for production, please check out this [guide](../../hosting/installation-updates/docker.md). -::: - -Docker is a platform that enables developers to develop, ship, and run applications inside containers. These containers are lightweight, standalone, and executable packages that include everything needed to run an application: code, runtime, system tools, libraries, and settings. To get started with Docker, you can follow the official [Docker installation guide](https://docs.docker.com/get-started/get-docker/). - -The Docker setup automatically provides all backend services (PHP, MySQL, Elasticsearch, Redis, Mailhog, etc.) so you don’t need to install anything else manually. - -In this guide, we will run PHP, Node, and all required services in Docker containers. If you just want to run the services (MySQL/OpenSearch/Redis/...) in Docker, check out the [Docker](./docker.md) guide. - -## Prerequisites - -- [Docker](https://docs.docker.com/get-started/get-docker/) or [OrbStack](https://docs.orbstack.dev/quick-start) (macOS) is installed and running. OrbStack is a fast, free (for personal use) alternative to Docker. -- `make` is installed on your machine (`apt install make` on Ubuntu, `brew install make` on macOS) -- `Docker Compose` is installed on your machine. Docker Desktop provides it automatically. If you're using OrbStack or something else, you can follow the official [Docker Compose installation guide](https://docs.docker.com/compose/install/). -- Enough disk and network capacity to pull images (~500MB+ per image depending on tags) - -## Pre-pull the image (optional) - -If you haven’t yet downloaded the Shopware Docker image, pull it now: - -```bash -docker pull ghcr.io/shopware/docker-dev:php8.3-node24-caddy -``` - -If you skip this step, Docker will automatically download the image during project creation. That’s normal, but pre-pulling makes the process cleaner and enables you to avoid waiting for large image downloads. - -## Create a new project - -Create a new empty directory and navigate to it: - -```bash -mkdir my-project && cd my-project -``` - -Then create a new project (required): - -```bash -docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup -``` - -Or you can use a specific version of Shopware (optional), like so: - -```bash -docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup 6.6.10.0 -``` - -This step creates your new Shopware project in the current directory, along with a `compose.yaml` and a `Makefile`. The difference from regular `composer create-project` is that we run PHP and Composer from within the Docker image. This means you don’t need to have PHP or Composer installed on your local machine. - -The project creation currently takes several minutes to complete. - -During the process, this prompt will appear: `Do you want to use Elasticsearch? (y/N)`. Elasticsearch improves search performance for large catalogs. We recommend: - -- answering "yes" if you expect thousands of products or use Shopware's advanced search features. You'll need an `elasticsearch` container/service. [Go here](https://developer.shopware.com/docs/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.html) to learn more about Elasticsearch setup. -- answering "no" if you’re just testing locally or have a small dataset. In this case, Shopware will use the MariaDB database for search. - -Shopware projects include files that use a combination of Symfony, Composer, Docker, and Shopware-specific conventions. - -
-Project structure explained (click to expand) - -| Item | Type | Purpose / what it contains | Notes | -|---------------------------|-----------------------------|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| -| **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. | -| **config/** | Directory | Symfony configuration files (framework, database, mail, etc.). | Similar to `config/` in many web frameworks. | -| **custom/** | Directory | Your plugins, themes, or app customizations. | This is where you add new extensions — your “src” for Shopware plugins. | -| **files/** | Directory | Uploaded media and temporary files. | Ignored by git; generated at runtime. | -| **Makefile** | Build helper | Shortcuts for Docker tasks (`make up`, `make setup`, etc.). | Replaces long Docker commands with memorable aliases. | -| **public/** | Web root | The actual web-server-accessible directory (contains `index.php`, assets, etc.). | Like `/dist` in JS frameworks or `/public_html`. | -| **src/** | Source code | Shopware’s core application source. | Where the main PHP codebase lives; not usually edited in a project clone. | -| **symfony.lock** | Symfony dependency snapshot | Records Symfony recipes applied during setup. | Used internally by Symfony Flex; no manual editing. | -| **var/** | Runtime data | Cache, logs, temporary files. | Can safely be deleted (Shopware rebuilds it). | -| **vendor/** | Dependency code | All installed PHP libraries from Composer. | Analogous to `node_modules/`. | - -
- -You’ll mostly interact with these: - -- **Makefile**, which provides convenient shortcuts for common Docker and Shopware commands. It acts as a lightweight wrapper around standard `docker compose` commands. You can still use the underlying Docker commands directly, but it’s recommended to stick with the `make` targets where possible, as they ensure consistent behavior across setups. -- **`custom/`**, to build your own plugins. -- **`bin/console`**, to run Shopware CLI tasks. - -Everything else in your project either supports or configures those layers. - -## Initial setup - -After creating your project, you still need to install Shopware inside the containers. Run the setup commands below to initialize the database, generate configuration files, and create the default admin user. - -First, start the containers: - -```bash -make up -``` - -This command builds (if needed) and starts all required Docker services (web server, database, Mailpit, etc.) in the background. More details about what each component does: - -
-Components explained (click to expand) - -| Name | Type | Purpose | -|---------------------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------| -| **Network `my-project_default`** | Docker network | A private virtual network so all containers can communicate (for example, the web container connects to the database). | -| **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](http://localhost:8025). | -| **Container `my-project-database-1`** | MariaDB service | Runs the Shopware database. Inside the Docker network its host name 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](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](http://localhost:8080). | - -
- -**Tip:** You can check container status anytime with: - -```bash -docker compose ps -``` - -“Healthy” means the service passed its internal health check and is ready to use. - -Once the containers are running, you can install Shopware in one of two ways: - -- **Browser installer**: open to walk through the installation wizard. -- **CLI**: run the following command to perform a quick, non-interactive setup: - -```bash -make setup -``` - -Both methods install Shopware and prepare your environment. The CLI setup automatically creates the database and an admin user with username `admin`, password `shopware`. - -:::info -If you are installing inside the Docker containers (the default when using `make up` and `make setup`), set the database host to `database`. This is the internal service name of the MariaDB container on the Docker network. Inside the containers, `localhost` would refer only to the container itself, not to the database. - -If you connect to the database from your host machine (for example, via Adminer or a local MySQL client), use 127.0.0.1 or `localhost` and the exposed port shown in `docker compose ps`. -::: - -
-Access key explained (click to expand) - -During setup, you’ll see an output similar to this: - -```bash -Access tokens: -+------------+----------------------------+ -| Key | Value | -+------------+----------------------------+ -| Access key | `string of capital letters` | -``` - -This access key is automatically generated for your default Sales Channel (usually *Storefront*). It's used for authenticating requests to the [Store API](../../../concepts/api/store-api)—for example, when fetching product or category data from an external app, headless storefront, or API client. - -Example usage: - -```bash -curl -H "sw-access-key: YOUR_ACCESS_KEY" \ - http://localhost:8000/store-api/product -``` - -You can view or regenerate this key later in the Admin under Sales Channels → [Your Channel] → API Access. - -:::info -The access key is not for logging in to the Admin. It’s for programmatic access to your storefront’s data via the Store API. -::: -
- -If you want to stop the setup, run `make stop`. - -To start it again, use `make up`. - -To stop and remove all containers, run: - -```bash -make down -``` - -This command removes all containers and associated networks. - -If you also want to remove all data and volumes (for example, to perform a full reset of your environment), run: - -```bash -docker compose down -v -``` - -The `-v` flag will delete the containers, networks, and volumes, meaning all stored data will be lost. - -### Known issue on Linux hosts - -If you are using Docker on Linux, your host user id (UID) must be **1000** for file permissions to work correctly inside the containers. You can check your user ID with: - -```bash -id -u -``` - -If it’s not `1000`, you may encounter permission errors when running `make up` or writing to project files. - -## Development - -To run Shopware CLI commands, first open a shell inside the web container: - -```bash -make shell -``` - -This command drops you into the container’s terminal (you’ll see the prompt change). From there, you can execute any Shopware CLI command using `bin/console`. For example, to clear the application cache (not required right now): - -```bash -docker compose exec web bin/console cache:clear -``` - -**Tip**: When you’re inside the container, you only need `bin/console …`. If you prefer to run commands from your host machine instead, use the full Docker prefix: `docker compose exec web bin/console cache:clear`. - -You’ll use the following Makefile commands later on, when you modify frontend or admin code, or develop plugins that affect the UI: - -```bash -# Build the administration (admin panel) -make build-administration - -# Build the storefront (shop frontend) -make build-storefront - -# Start a watcher to rebuild the Administration automatically when files change -make watch-admin - -# Start a watcher for Storefront -make watch-storefront -``` - -These will become part of your everyday development workflow. - -## Verify your installation in the browser (optional) - -Now that Shopware is installed, you can confirm the storefront is working by visiting [http://localhost:8000](http://localhost:8000). - -Shopware’s CLI setup automatically installs a complete, preconfigured demo storefront with sample products and categories. It includes local, disposable demo data so you can explore features or test plugins immediately. - -You can also check out the Shopware Admin dashboard to verify that the Admin is accessible: - -- Log in to the **Admin** at [http://localhost:8000/admin](http://localhost:8000/admin) using `admin / shopware` (default credentials). -- Once logged in, you’ll see the Shopware Admin dashboard and merchant setup wizard. - -As a developer, you can skip the wizard and use the Admin to: - -- confirm your installation and database are running correctly. -- manage extensions or themes you install later. -- inspect system settings and logs. -- verify that changes from your code (for example, new entities or configuration options) appear in the UI. - -## Services - -With Shopware running, here are the services in your local stack and how to access them. Understanding what each one does helps you troubleshoot issues and connect external tools if needed: - -- **Web service (Caddy + PHP-FPM by default, or Nginx + PHP-FPM)**: serves both the storefront and the admin interface. The default image uses Caddy; you can choose Nginx in image variations. -- Storefront: [http://localhost:8000](http://localhost:8000) -- Admin: [http://localhost:8000/admin](http://localhost:8000/admin) *(default credentials: `admin` / `shopware`)* - -- **Database (MariaDB)**: runs on port **3306** inside Docker. The internal hostname is `database`. You can connect from your host using `localhost:3306` if you want to inspect the database directly. - -- **Mailpit**: local mail testing tool, available at [http://localhost:8025](http://localhost:8025). Use this to view emails sent by Shopware (e.g., registration or order confirmations) without needing an external mail server. - -### Changing environment variables - -You can create a `.env` file in the project root to override default environment variables. Changes take effect automatically without restarting containers **except for** the `APP_ENV` variable, which requires: - -```bash -make up -``` - -This command restarts the containers so that the updated environment variable takes effect. - -## Production environments - -If you're preparing to run Shopware in production using Docker, [this page](../../hosting/installation-updates/docker.md) covers production images, environment configuration, and deployment workflows. - -## Detailed configurations - -You can find more detailed configurations for your docker setup in the [Additional Docker Options](docker-options) article. diff --git a/guides/installation/setups/index.md b/guides/installation/setups/index.md deleted file mode 100644 index c1d5c57d19..0000000000 --- a/guides/installation/setups/index.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -nav: - title: Setups - position: 10 - ---- - -# Setups - -Once your system meets the [requirements](../requirements.md), you can choose how you want to run your Shopware 6 development environment. This page helps you understand how each setup works in practice: What it’s best at, what to expect in daily use, and how to switch between them. - -## Docker setup (recommended) - -Docker runs your entire Shopware environment in containers, including PHP, MySQL, Redis, Elasticsearch, and Mailhog. It gives you a production-like stack with minimal manual setup. - -**What to expect** - -- All services run inside containers managed by Docker Compose. -- Great parity between development, CI, and production. -- Easy to reset or rebuild environments (`docker compose down -v`). -- Higher resource usage, but consistent results on any machine. - -**When it shines** - -- You want zero “works on my machine” issues. -- You collaborate with others or use CI/CD pipelines. -- You need full service parity (e.g. caching, queues, search). - -[Docker setup guide →](./docker.md) - -## Symfony CLI setup - -Symfony CLI runs Shopware locally using your host system’s PHP and Composer installation. -It’s lightweight, fast, and easy to debug using your local toolchain. - -**What to expect** - -- Uses your installed PHP, MySQL, and Node.js directly. -- Minimal overhead and startup time. -- Ideal for plugin, theme, or app developers who want rapid iteration. -- You manage local dependencies (e.g. PHP extensions, database) yourself. - -**When it shines** - -- You’re building or testing extensions, not full stacks. -- You prefer editing and debugging locally. -- You’re on a resource-limited machine. - -[Symfony CLI setup guide →](./symfony-cli.md) - -## Devenv setup - -Devenv uses [Nix](https://nixos.org/) to define a reproducible Shopware development environment. -It ensures everyone — across macOS, Linux, and CI — gets the same dependency versions and behavior. - -**What to expect** - -- You define all tools and services in `devenv.yaml`. -- Nix handles installation and version consistency automatically. -- Works well in multi-version or multi-project contexts. -- Slightly steeper learning curve but high reliability. - -**When it shines** - -- You contribute to Shopware core or maintain multiple versions. -- You want reproducibility between developers and CI. -- You value a declarative, version-controlled environment. - -[Devenv setup guide →](./devenv.md) - -## Community and alternative Docker tooling - -If you prefer a more automated or GUI-friendly way to run Docker environments, DDEV and Dockware are both popular within the Shopware community. **Note:** DDEV and Dockware are community-maintained and not officially supported by Shopware. - -### DDEV setup - -[DDEV](https://ddev.com/) is a developer-friendly wrapper around Docker that automates environment setup using simple CLI commands. - -**Why use DDEV** - -- Simplifies Docker configuration: no manual `docker-compose.yml` needed. -- One command (`ddev start`) to start your Shopware environment. -- Easy to switch PHP/MySQL/Node versions per project. -- Integrates well with VS Code and PHPStorm. - -**Use it when** - -- You want a pre-configured, easy-to-use Docker experience. -- You prefer to focus on code, not container details. - -[DDEV with Shopware example →](https://github.com/ddev/test-shopware6) - -### Dockware setup - -[Dockware](https://www.dockware.io/) provides ready-to-run Docker images for quickly spinning up demo stores or full local environments. - -**Why use Dockware** - -- Pre-built images for Shopware 5, 6, and nightly builds. -- Includes all key services: PHP, DB, Elasticsearch, Mailhog, Adminer, etc. -- Great for testing specific versions or quick evaluation. -- Can be used standalone or integrated into CI pipelines. - -**Use it when** - -- You need a running Shopware instance in seconds. -- You’re testing multiple Shopware versions or demos. -- You prefer minimal setup over full customization. - -[Dockware documentation →](https://docs.dockware.io/) - -## Switching between setups - -All setups share the same Shopware [Project Template](../template). Only the runtime environment differs. You can safely switch between setups as long as you keep separate environment configurations. - -To switch setups: - -1. Stop running services (e.g., `docker compose down`, or `symfony server:stop`). -2. Use separate directories for each setup. -3. Reuse the same project template if needed. Each setup has its own configuration files. - -You can always migrate between setups later. Your Shopware project remains the same. - -## Next step - -Choose your preferred setup and follow its related guide. Once your setup is running, you can start developing your shop, app, plugin, or theme. - -## Installing Shopware CLI - -Most developers install the [Shopware CLI](../../../products/cli/index.md), which helps with building, refactoring, validating, and managing Shopware projects and extensions. It works with all setups (Docker, Symfony CLI, Devenv, DDEV, Dockware) and is used in most Shopware upgrade, build, and CI workflows. If you're using the Docker setup, the CLI comes preinstalled and is available in the container shell. diff --git a/guides/installation/template.md b/guides/installation/template.md deleted file mode 100644 index 9c48444336..0000000000 --- a/guides/installation/template.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -nav: - title: Project Template - position: 2 - ---- - -# Project Template - -The Shopware project template is a Composer project that can be used as a starting point for new Shopware Projects, or if you want to develop extensions or themes for Shopware. - -Each official setup option—[Docker](./setups/docker.md), [Symfony CLI](./setups/symfony-cli.md), and [Devenv](./setups/devenv.md)—builds upon this project template, either directly or via a pre-configured environment. See [Installation Overview](./index.md) for a comparison of setup options. - -## Alternative: Using the installer package - -If you have downloaded the [shopware-installer.phar package](https://www.shopware.com/en/download/) instead of using Composer, skip the `composer create-project` step and follow the remaining instructions from the [Project Template](https://developer.shopware.com/docs/guides/installation/template.html) guide. - -This method is equivalent to creating a project using Composer but is suited for environments where Composer is not available (for example, shared hosting or limited enterprise servers). - -## Set up a new project - -To create a new Shopware project, run the following command: - -```bash -composer create-project shopware/production - -# or install a specific version -composer create-project shopware/production:6.6.10.5 -``` - -::: info -Composer `create-project` clones the latest tag from the [Template repository](https://github.com/shopware/template) and installs the dependencies. If you don't have Composer installed, you could also clone the repository itself and run `composer install` in Docker to proceed with the installation. -::: - -This creates a new project in the `` directory. - -The template contains all Shopware bundles like `shopware/administration`, `shopware/storefront` and `shopware/elasticsearch`. If you don't need any, then you can uninstall them with: - -```bash -composer remove shopware/ -``` - -## Installation - -After you have created the project, you have automatically a `.env` file in your project root. This file contains all the environment variables you need to run Shopware. - -If you want to adjust a variable, you should put the variable in a `.env.local` file. This file will override the variables in the `.env` file. - -::: info -The `.env` will be overwritten when the Shopware Web Installer is used for Shopware updates, so it's highly recommended to use a `.env.local` file. -::: - -After you have adjusted the `.env` file, you can run the following command to install Shopware: - -```bash -bin/console system:install --basic-setup -``` - -The flag `--basic-setup` will automatically create an admin user and a default sales channel for the given `APP_URL`. If you haven't created a MySQL Database yet, you can pass the `--create-database` flag to create a new database. - -The Shopware's default Administration credentials are: - -| Username | Password | -|:---------|:-----------| -| `admin` | `shopware` | - -Change these credentials after finishing the installation. - -### Optional packages - -The template is small and does not contain any dev-tooling or integrations like PaaS or Fastly. You can easily add them to your project with the following commands: - -```bash -# Install profiler and other dev tools, eg Faker for demo data generation -composer require --dev shopware/dev-tools - -# Or Install symfony dev tools -composer require --dev symfony/profiler-pack - -# Install PaaS integration -composer require paas --ignore-platform-req=ext-amqp - -# Install Fastly integration -composer require fastly -``` - -### Add Shopware packagist - -Using Shopware Packagist, you can manage all your Shopware Store plugins directly in the `composer.json`. Refer to ["Using Composer for plugin installation in Shopware"](https://www.shopware.com/en/news/using-composer-for-plugin-installation-in-shopware/) blog post for detailed information. - -## Building/watching Administration and Storefront - -The created project contains Bash scripts in `bin/` folder to build and watch the Administration and Storefront. You can run the following commands: - -```bash -./bin/build-administration.sh -./bin/build-storefront.sh -./bin/watch-administration.sh -./bin/watch-storefront.sh -``` - -Use these scripts to build the Administration and Storefront. The `watch` commands will watch for changes in the Administration and Storefront and rebuild them automatically. - -## Update Shopware - -There are two ways to update Shopware: - -* Initially run `bin/console system:update:prepare` to enable the maintenance mode and then update all Composer packages using `composer update --no-scripts`. The `--no-scripts` flag instructs composer to not run any scripts that may reference Shopware CLI commands. They will only be functional after updating the recipes. To disable the maintenance mode, run `bin/console system:update:finish`. - -* To force-update all config files, run `composer recipes:update`. - -## Migrate from the old zip installation to a new project template - -Before Shopware 6.5, we provided a zip file for installation. The zip file contained all dependencies required to run Shopware. This method has been deprecated and replaced with a Composer project template. The Composer project template is way more flexible and allows you to manage extensions together with Shopware itself using Composer. - -To migrate from the old zip installation to the new Composer project template, you can use `shopware-cli project autofix flex` command to migrate it automatically, or you can do it manually by following the steps below. - -### 1. Backup - -Start with a clean git state, stash everything, or make a backup of your files. - -### 2. Adjust root composer.json - -First, adjust your root `composer.json`. Add the following lines to your `composer.json`: - -```json -"extra": { - "symfony": { - "allow-contrib": true, - "endpoint": [ - "https://raw.githubusercontent.com/shopware/recipes/flex/main/index.json", - "flex://defaults" - ] - } -} -``` - -Next, replace all the existing scripts with the following: - -```json -"scripts": { - "auto-scripts": [], - "post-install-cmd": [ - "@auto-scripts" - ], - "post-update-cmd": [ - "@auto-scripts" - ] -} -``` - -Finally, remove the fixed platform as it will now be determined by the required packages. - -```diff -"config": { - "optimize-autoloader": true, -- "platform": { -- "php": "7.4.3" -- }, - "sort-packages": true, - "allow-plugins": { - "composer/package-versions-deprecated": true - } -}, -``` - -### 3. Cleanup the template - -After having installed the new Composer packages, you can clean up the template by removing the following files: - -```bash -rm -r .dockerignore \ - .editorconfig \ - .env.dist \ - .github \ - .gitlab-ci \ - .gitlab-ci.yml \ - Dockerfile \ - docker-compose.yml \ - easy-coding-standard.php \ - PLATFORM_COMMIT_SHA \ - artifacts \ - bin/deleted_files_vendor.sh \ - bin/entrypoint.sh \ - bin/package.sh \ - config/etc \ - src \ - config/secrets \ - config/services \ - config/services.xml \ - config/services_test.xml \ - license.txt \ - phpstan.neon \ - phpunit.xml.dist \ - psalm.xml - -touch .env -``` - -### 4. Install required Composer packages - -To install Symfony Flex, you need to have Composer installed. If you don't have Composer installed, please follow the [official documentation](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-macos). - -To install Symfony Flex, you need to run the following commands and allow both new Composer plugins. - -```bash -composer require "symfony/flex:*" "symfony/runtime:*" - -composer recipe:install --force --reset -``` - -### 5. Review changes - -Review the changes and commit them to your Git repository. All upcoming config changes can be applied with `composer recipes:update`. - -You may need to adjust some environment variables as the names have changed: - -| **Old name** | **New name** | -|-------------------|----------------| -| MAILER_URL | MAILER_DSN | -| SHOPWARE_ES_HOSTS | OPENSEARCH_URL | - -## Known issues - -### `APP_ENV=dev` web_profiler missing extension error - -Prior to Shopware 6.4.17.0, you have to install the Profiler bundle to get `APP_ENV=dev` working with: - -```bash -composer require --dev profiler -``` - -### framework:demo-data is missing faker classes - -Prior to Shopware 6.4.17.0, you have to install some packages to get `framework:demo-data` command working: - -```bash -composer require --dev mbezhanov/faker-provider-collection maltyxx/images-generator -``` diff --git a/guides/installation/setups/devenv-options.md b/guides/legacy-setups/devenv-options.md similarity index 100% rename from guides/installation/setups/devenv-options.md rename to guides/legacy-setups/devenv-options.md diff --git a/guides/installation/setups/devenv.md b/guides/legacy-setups/devenv-setup.md similarity index 99% rename from guides/installation/setups/devenv.md rename to guides/legacy-setups/devenv-setup.md index b7315b21fe..7139cb134a 100644 --- a/guides/installation/setups/devenv.md +++ b/guides/legacy-setups/devenv-setup.md @@ -1,11 +1,11 @@ --- nav: - title: Devenv + title: Setting up Shopware with Devenv position: 20 --- -# Devenv +# Setting up Shopware with Devenv [Devenv](https://devenv.sh) is a Nix-based tool for defining and managing fully reproducible development environments for local workstations or continuous integration (CI) systems. It works like a dependency manager for your entire development stack. diff --git a/guides/legacy-setups/setup-symfony-cli.md b/guides/legacy-setups/setup-symfony-cli.md new file mode 100644 index 0000000000..2a9eac0c65 --- /dev/null +++ b/guides/legacy-setups/setup-symfony-cli.md @@ -0,0 +1,174 @@ +--- +nav: + title: Setting up Shopware with Symfony CLI + position: 30 + +--- + +# Setting up Shopware with Symfony CLI + +Symfony CLI lets you run Shopware 6 locally without Docker. It's a lightweight option that uses your system’s PHP, Composer, and Node.js installations. + +Shopware recommends [Docker](./docker.md) as the default setup for most users because it mirrors production and includes all services out of the box. However, if you already have PHP and a database installed locally, or want a faster, low-overhead workflow, Symfony CLI is a solid alternative. + +## Prerequisites + +Before you begin, make sure your system meets the [Shopware 6 requirements](../requirements.md). You’ll need the following tools installed on your host machine: + +- [Symfony CLI](https://symfony.com/download) +- PHP 8.2 or higher with the required extensions; see the [Requirements page](../requirements.md) for the complete list +- [Composer 2.x](https://getcomposer.org/) +- [Node.js 20+](https://nodejs.org/en/download) and npm +- A running MySQL 8 or MariaDB 11 database (local or remote) + +You’ll also need a working web server. The Symfony CLI can provide one automatically for development. + +> **macOS note:** If you installed PHP via Homebrew, make sure the `intl` extension is enabled: `brew install php-intl` then verify with `php -m | grep intl`. + +Optional tools: + +- [Elasticsearch 8](https://www.elastic.co/elasticsearch/) for product search and indexing +- Docker (for running only the database while keeping PHP local) + +## Create a New Project + +Run this command to create a new Shopware production project: + +```bash +composer create-project shopware/production + +# or specify a version +composer create-project shopware/production:6.6.10.0 +``` + +During project creation, Symfony Flex asks whether you want to use Docker. Choose **Yes** if you want to run the database in a container, or **No** to use a local MySQL/MariaDB server. + +For more details, see the [Shopware Production template documentation](../template). + +## Configure database connection + +After creating the project, define your database settings in a `.env.local` file in the project root: + +```dotenv +DATABASE_URL=mysql://username:password@localhost:3306/dbname +``` + +You can define other environment settings (like `APP_URL`, `MAILER_DSN`, or `SHOPWARE_ES_HOSTS`) in `.env.local` as needed. + +Git ignores `.env.local`, so you can safely define machine-specific settings here without affecting your team’s shared configuration. + +### Using Docker for the database (optional) + +Running the database in a Docker container helps keep your local system clean and ensures version consistency with production environments. If you prefer this instead of installing MySQL or MariaDB locally, start Docker with: + +```bash +docker compose up -d +``` + +This command starts the database container in the background. + +To stop and remove the containers, while preserving the database data, run: + +```bash +docker compose down +``` + +Run `docker compose down -v` to remove the containers and delete all stored data volumes. + +::: info +Tip - Use the `-v` flag only if you want to completely reset the database. +::: + +## Install Shopware + +::: info +Always prefix commands with `symfony` to ensure the correct PHP version and configuration are used. Skipping this can cause issues such as using the wrong PHP binary or failing to connect to the Docker-based MySQL database. +::: + +Run the following command to install Shopware: + +```bash +symfony console system:install --basic-setup +``` + +The `--basic-setup` flag initializes Shopware with sensible defaults. It automatically creates a database schema, an admin user, and a default sales channel for the specified `APP_URL` so you can start testing immediately without manual configuration. Optional: Add the `--create-database` flag if your database doesn’t already exist. + +If you encounter file-permission issues when installing or rebuilding caches, run `symfony console cache:clear` or check directory ownership. + +### Default Administration credentials + +Shopware creates a default Administration user during installation: + +| Username | Password | +|:---------|:-----------| +| `admin` | `shopware` | + +**Tip**: Change these credentials after installation for security. + +## Start the webserver + +The Symfony local web server automatically uses the correct PHP version, reads your `.env` configuration, and exposes HTTPS by default. This makes it more reliable than the built-in PHP server for local development. + +Start the local web server with: + +```bash +symfony server:start +``` + +By default, this starts the server on port `8000`. Access the Shopware Administration at [http://localhost:8000/admin](http://localhost:8000/admin) and the Storefront at [http://localhost:8000](http://localhost:8000). + +To run the server in the background, add the `-d` flag: + +```bash +symfony server:start -d +``` + +This frees up your terminal for other commands. + +### Stopping the Web Server + +To stop the server and all running processes, run: + +```bash +symfony server:stop +``` + +**Tip**: If port 8000 is already in use, start the server on a different port: `symfony server:start --port=8080` + +## Set the PHP version (optional, recommended) + +Specify a PHP version to ensure consistent environments across team members. + +To change the PHP version used by Symfony CLI, create a `.php-version` file in the project root and specify the desired version. For example, to use PHP 8.3, create `.php-version` and add: + +```dotenv +8.3 +``` + +Symfony CLI will now use PHP 8.3 for all commands in this project. Commit this file to your version control system so everyone on your team uses the same PHP version. + +To verify which PHP version is active, run: + +```bash +symfony php -v +``` + +## Adjust PHP configuration (Optional) + +Adjusting PHP settings like `memory_limit` or `max_execution_time` can prevent build or cache warm-up processes from failing, especially during large Administration builds or when working on plugins. + +You can override PHP settings for this project by adding a `php.ini` file in the project root. For example, to increase the `memory_limit` to 512 MB, add: + +```ini +memory_limit = 512M +``` + +To confirm your configuration, run: + +```bash +symfony php -i +``` + +By keeping your `php.ini` in version control, you ensure consistent behavior across development environments and CI pipelines. + +Symfony CLI uses PHP’s built-in web server by default. For better performance, you can configure it to use Nginx or Caddy: see the [web server reference](../../../resources/references/config-reference/server/nginx.md). diff --git a/guides/installation/setups/symfony-cli.md b/guides/legacy-setups/symfony-cli-setup.md similarity index 98% rename from guides/installation/setups/symfony-cli.md rename to guides/legacy-setups/symfony-cli-setup.md index 592147ff99..c0d4b30552 100644 --- a/guides/installation/setups/symfony-cli.md +++ b/guides/legacy-setups/symfony-cli-setup.md @@ -1,11 +1,11 @@ --- nav: - title: Symfony CLI + title: Setting up Shopware with Symfony CLI position: 30 --- -# Symfony CLI Setup +# Setting up Shopware with Symfony CLI Symfony CLI lets you run Shopware 6 locally without Docker. It's a lightweight option that uses your system’s PHP, Composer, and Node.js installations. diff --git a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md index f7d517cc72..0d17c960d7 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md @@ -7,139 +7,11 @@ nav: # Add Custom CLI Commands -To ease development tasks, Shopware contains the Symfony commands functionality. This allows \(plugin-\) developers to define new commands executable via the Symfony console at `bin/console`. The best thing about commands is, that they're more than just simple standalone PHP scripts - they integrate into Symfony and Shopware, so you've got access to all the functionality offered by both of them. +Shopware CLI commands are based on Symfony Console. This means that creating custom commands in Shopware plugins follows the standard Symfony approach. -Creating a command for Shopware 6 via a plugin works exactly like you would add a command to Symfony. Make sure to have a look at the Symfony commands guide: +See the [official Symfony documentation](https://symfony.com/doc/current/console.html) for the full guide. - - -## Prerequisites - -This guide **does not** explain how to create a new plugin for Shopware 6. Head over to our plugin base guide to learn how to create a plugin at first: - - - -The main requirement here is to have a `services.xml` file loaded in your plugin. This can be achieved by placing the file into a `Resources/config` directory relative to your plugin's base class location. - -::: info -Refer to this video on custom **[Creating a CLI command](https://www.youtube.com/watch?v=OL_qNVLLyaI)**. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). -::: - -## Registering your command - -From here on, everything works exactly like in Symfony itself. Commands are recognised by Shopware, once they're tagged with the `console.command` tag in the [dependency injection](dependency-injection) container. So to register a new command, just add it to your plugin's `services.xml` and specify the `console.command` tag: - -```html - - - - - - - - -``` - -Here's a full example `services.xml` which registers your custom command: - -```xml -// /src/Resources/config/services.xml - - - - - - - - - - -``` - -Your command's class should extend from the `Symfony\Component\Console\Command\Command` class, here's an example: - -```php -// /src/Command/ExampleCommand.php -setDescription('Does something very special.'); - } - - // Actual code executed in the command - protected function execute(InputInterface $input, OutputInterface $output): int - { - $output->writeln('It works!'); - - return Command::SUCCESS; - } -} -``` - -This command is of course only a basic example, so feel free to experiment. As stated above, you now have access to all the functionality offered by Symfony and Shopware. - -::: info -For inspiration, maybe have a look at the Symfony documentation - you may for example use [tables](https://symfony.com/doc/current/components/console/helpers/table.html), [progress bars](https://symfony.com/doc/current/components/console/helpers/progressbar.html), or [custom formats](https://symfony.com/doc/current/components/console/helpers/formatterhelper.html). -::: - -### Running commands - -Commands are run via the `bin/console` executable. To list all available commands, run `bin/console list`: - -```text -$: php bin/console list -Symfony 4.4.4 (env: dev, debug: true) - -Usage: - command [options] [arguments] - -Options: - -h, --help Display this help message - -q, --quiet Do not output any message - -V, --version Display this application version - --ansi Force ANSI output - --no-ansi Disable ANSI output - -n, --no-interaction Do not ask any interactive question - -e, --env=ENV The Environment name. [default: "dev"] - --no-debug Switches off debug mode. - -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug - -Available commands: - about Displays information about the current project - help Displays help for a command - list Lists commands - feature - feature:dump Creating json file with feature config for js testing and hot reloading capabilities. - assets - assets:install - bundle - bundle:dump Creates a json file with the configuration for each active Shopware bundle. - cache - cache:clear Clears the cache - cache:pool:clear Clears cache pools - cache:pool:delete Deletes an item from a cache pool - cache:pool:list List available cache pools - cache:pool:prune Prunes cache pools - cache:warmup Warms up an empty cache - [...] -``` - -Each command usually has a namespace like `cache`, so to clear the cache you would execute `php bin/console cache:clear`. If you would like to learn more about commands in general, have a look at [this article](https://symfony.com/doc/current/console.html) in the Symfony documentation. +Commands registered as services in a Shopware plugin are automatically available via `bin/console`. ## More interesting topics diff --git a/index.md b/index.md index 2aab24c2ab..194bb08bb0 100644 --- a/index.md +++ b/index.md @@ -14,4 +14,6 @@ These two sections are complemented by the **References**, which contain structu Visit the [academy](https://academy.shopware.com/collections?category=developer-sw6) for video content. If you have any questions left, you can always ask them on [StackOverflow](https://stackoverflow.com/questions/tagged/shopware6?tab=Newest) or join our awesome community on [Discord](https://discord.com/channels/1308047705309708348/1309107911175176217). +To begin developing, [start here with our installation guide](guides/installation.md). + ![Readme](assets/readme-splash.png) From 8d4e37015446fa8f8e0cb0160839ef3a6e254b8e Mon Sep 17 00:00:00 2001 From: somethings Date: Wed, 11 Feb 2026 10:46:22 +0100 Subject: [PATCH 02/45] Update symfony-cli-setup.md --- guides/legacy-setups/symfony-cli-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/legacy-setups/symfony-cli-setup.md b/guides/legacy-setups/symfony-cli-setup.md index c0d4b30552..8dcb4d8ee4 100644 --- a/guides/legacy-setups/symfony-cli-setup.md +++ b/guides/legacy-setups/symfony-cli-setup.md @@ -43,7 +43,7 @@ composer create-project shopware/production:6.6.10.0 During project creation, Symfony Flex asks whether you want to use Docker. Choose **Yes** if you want to run the database in a container, or **No** to use a local MySQL/MariaDB server. -For more details, see the [Shopware Production template documentation](../template). +For more details, see the [Shopware Production template documentation](../installation/project-overview.md). ## Configure database connection From 59b99a894948deb89b5df2c3e345e760004b803a Mon Sep 17 00:00:00 2001 From: somethings Date: Wed, 11 Feb 2026 10:54:38 +0100 Subject: [PATCH 03/45] Update elasticsearch-setup.md --- .../hosting/infrastructure/elasticsearch/elasticsearch-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md b/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md index 1ced473cc2..08e4ec94f5 100644 --- a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md +++ b/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md @@ -19,7 +19,7 @@ Currently, the implementation for Elasticsearch/Opensearch works in the same way * A supported OpenSearch (or Elasticsearch) server - + * [Running message queue workers in the background](../message-queue) From 0b91b1162886f71a3c90615c49242f869ef13143 Mon Sep 17 00:00:00 2001 From: somethings Date: Wed, 11 Feb 2026 11:03:01 +0100 Subject: [PATCH 04/45] Update symfony-cli-setup.md --- guides/legacy-setups/symfony-cli-setup.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/guides/legacy-setups/symfony-cli-setup.md b/guides/legacy-setups/symfony-cli-setup.md index 8dcb4d8ee4..e82b733021 100644 --- a/guides/legacy-setups/symfony-cli-setup.md +++ b/guides/legacy-setups/symfony-cli-setup.md @@ -9,14 +9,16 @@ nav: Symfony CLI lets you run Shopware 6 locally without Docker. It's a lightweight option that uses your system’s PHP, Composer, and Node.js installations. -Shopware recommends [Docker](./docker.md) as the default setup for most users because it mirrors production and includes all services out of the box. However, if you already have PHP and a database installed locally, or want a faster, low-overhead workflow, Symfony CLI is a solid alternative. +Shopware recommends [Docker](../installation/docker-setup.md) as the default setup for most users because it mirrors production and includes all services out of the box. However, if you already have PHP and a database installed locally, or want a faster, low-overhead workflow, Symfony CLI is a solid alternative. ## Prerequisites -Before you begin, make sure your system meets the [Shopware 6 requirements](../requirements.md). You’ll need the following tools installed on your host machine: +Before you begin, make sure your system meets the [Shopware 6 requirements](../installation/hardware-requirements.md). + +You’ll need the following software installed on your host machine: - [Symfony CLI](https://symfony.com/download) -- PHP 8.2 or higher with the required extensions; see the [Requirements page](../requirements.md) for the complete list +- PHP 8.2 or higher with the required extensions; see our [recommended stack and supported versions](../hosting/index.md#recommended-stack-and-supported-versions) for the complete list - [Composer 2.x](https://getcomposer.org/) - [Node.js 20+](https://nodejs.org/en/download) and npm - A running MySQL 8 or MariaDB 11 database (local or remote) @@ -43,7 +45,7 @@ composer create-project shopware/production:6.6.10.0 During project creation, Symfony Flex asks whether you want to use Docker. Choose **Yes** if you want to run the database in a container, or **No** to use a local MySQL/MariaDB server. -For more details, see the [Shopware Production template documentation](../installation/project-overview.md). +For more details about the Composer-based project template, see the [Shopware Production template](https://github.com/shopware/production). ## Configure database connection From 3328955932144bd7c618a9a9ae2a232c8f21452f Mon Sep 17 00:00:00 2001 From: somethings Date: Wed, 11 Feb 2026 11:07:17 +0100 Subject: [PATCH 05/45] Update symfony-cli-setup.md --- guides/legacy-setups/symfony-cli-setup.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/guides/legacy-setups/symfony-cli-setup.md b/guides/legacy-setups/symfony-cli-setup.md index e82b733021..4d61ed5a34 100644 --- a/guides/legacy-setups/symfony-cli-setup.md +++ b/guides/legacy-setups/symfony-cli-setup.md @@ -179,4 +179,5 @@ Symfony CLI uses PHP’s built-in web server by default. For better performance, You only need to run this step if you’re developing or customizing the frontend (Administration or Storefront). It compiles JavaScript and CSS assets so your changes are visible immediately. - + + From e60052421c907bd47dd4a13ef41dbcf98f7580c0 Mon Sep 17 00:00:00 2001 From: somethings Date: Wed, 11 Feb 2026 11:09:36 +0100 Subject: [PATCH 06/45] Update index.md --- guides/hosting/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/hosting/index.md b/guides/hosting/index.md index 0924c3abc8..d9c32c79d2 100644 --- a/guides/hosting/index.md +++ b/guides/hosting/index.md @@ -40,4 +40,4 @@ Ask your hosting provider for the correct PHP binary and how to adjust `php.ini` - `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 \ No newline at end of file +- `npm -v`: Show npm version From 400c923ab7c8c9625d96143a0bcb72a83968ef0b Mon Sep 17 00:00:00 2001 From: somethings Date: Wed, 11 Feb 2026 11:10:15 +0100 Subject: [PATCH 07/45] Update symfony-cli-setup.md --- guides/legacy-setups/symfony-cli-setup.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/guides/legacy-setups/symfony-cli-setup.md b/guides/legacy-setups/symfony-cli-setup.md index 4d61ed5a34..d7774b1aab 100644 --- a/guides/legacy-setups/symfony-cli-setup.md +++ b/guides/legacy-setups/symfony-cli-setup.md @@ -13,7 +13,7 @@ Shopware recommends [Docker](../installation/docker-setup.md) as the default set ## Prerequisites -Before you begin, make sure your system meets the [Shopware 6 requirements](../installation/hardware-requirements.md). +Before you begin, make sure your system meets the [Shopware 6 requirements](../installation/hardware-requirements.md). You’ll need the following software installed on your host machine: @@ -180,4 +180,3 @@ Symfony CLI uses PHP’s built-in web server by default. For better performance, You only need to run this step if you’re developing or customizing the frontend (Administration or Storefront). It compiles JavaScript and CSS assets so your changes are visible immediately. - From 1efd59a80bbcd2c8478f3314ef9c26c45f950888 Mon Sep 17 00:00:00 2001 From: somethings Date: Wed, 11 Feb 2026 11:10:38 +0100 Subject: [PATCH 08/45] Update add-custom-commands.md --- .../plugins/plugins/plugin-fundamentals/add-custom-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md index 0d17c960d7..0854a286bd 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md @@ -7,7 +7,7 @@ nav: # Add Custom CLI Commands -Shopware CLI commands are based on Symfony Console. This means that creating custom commands in Shopware plugins follows the standard Symfony approach. +Shopware CLI commands are based on Symfony Console. This means that creating custom commands in Shopware plugins follows the standard Symfony approach. See the [official Symfony documentation](https://symfony.com/doc/current/console.html) for the full guide. From ba89e7242f35ebea95256362db8ea383679bee26 Mon Sep 17 00:00:00 2001 From: somethings Date: Wed, 11 Feb 2026 11:14:52 +0100 Subject: [PATCH 09/45] Update docker-setup.md --- guides/installation/docker-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index f31a73ecc7..89ca8adb3f 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -57,7 +57,7 @@ docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-nod This step creates your Shopware project using PHP and Composer inside the Docker image. It generates a ready-to-use setup including `compose.yaml` and a `Makefile`, so you don’t need to locally install PHP or Composer yourself. :::info -The Docker setup installs development dependencies (`require-dev`) and [`shopware/dev-tools`](https://github.com/shopware/dev-tools). This enables the Symfony profiler, [demo data](https://github.com/shopware/SwagPlatformDemoData), linters, and test tooling. +The Docker setup installs development dependencies (`require-dev`) and [`shopware/dev-tools`](https://github.com/shopware/dev-tools). This enables the Symfony profiler, [demo data](https://github.com/shopware/SwagPlatformDemoData), linting tools, and test tooling. ::: Project creation takes a few minutes to complete. In your terminal, this prompt will eventually appear: From d58cd46a62221c17b1e3c948853755dedcd5ffa2 Mon Sep 17 00:00:00 2001 From: somethings Date: Wed, 11 Feb 2026 11:15:14 +0100 Subject: [PATCH 10/45] Update project-overview.md --- guides/installation/project-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md index a03e46e736..28078f1f47 100644 --- a/guides/installation/project-overview.md +++ b/guides/installation/project-overview.md @@ -16,7 +16,7 @@ The Docker setup installs Shopware with development dependencies (`require-dev`) - [`shopware/dev-tools`](https://github.com/shopware/dev-tools) - Symfony profiler - [Demo data](https://github.com/shopware/SwagPlatformDemoData) -- Linters and testing tools +- Linting and testing tools Your local project is ready for debugging, profiling, and extension development out of the box. From 1e8208b3422b7c220509686981ec641f2aa0d690 Mon Sep 17 00:00:00 2001 From: somethings Date: Wed, 11 Feb 2026 11:16:35 +0100 Subject: [PATCH 11/45] Update after-installation.md --- guides/installation/after-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/after-installation.md b/guides/installation/after-installation.md index 61e909b918..c94dd08aff 100644 --- a/guides/installation/after-installation.md +++ b/guides/installation/after-installation.md @@ -231,7 +231,7 @@ For advanced topics like: - image variants - Minio (S3) - OrbStack routing -- production image proxying +- production image proxy configuration - service internals see [Advanced Options](advanced-options.md) From 652f4c2972898a8babe685b137184767fb3f8a88 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:24:47 +0100 Subject: [PATCH 12/45] Update guides/installation/docker-setup.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/docker-setup.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index 89ca8adb3f..4c0236de5a 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -96,16 +96,18 @@ Once the containers are running, install Shopware with this command: make setup ``` +:::info What happens during `make setup`: - The Makefile runs the Shopware installer inside the web container - Shopware is installed automatically (no browser wizard required) - A MariaDB database is created - An admin user is created, with username `admin` and password `shopware` -- Required services (database, search, mail, etc.) are running inside Docker and already configured +- Required services (database, search, mail, etc.) are preconfigured and runs inside the Docker - The Shopware project is configured to connect to the database via the Docker service name `database` - Database credentials are defined in the `compose.yaml` - If search was enabled during project creation, an Elasticsearch-compatible search service runs as part of the Docker stack +::: You verify the installation succeeded by opening . From 7a9685a02c8812fa3dfc828e9aa5afa6d45e5dd4 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:25:23 +0100 Subject: [PATCH 13/45] Update guides/installation/installation-intro.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/installation-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md index e827a07453..cf97356501 100644 --- a/guides/installation/installation-intro.md +++ b/guides/installation/installation-intro.md @@ -13,7 +13,7 @@ Welcome to the Shopware 6 Developer Installation Guide, which will help you set - developing a plugin, app, or theme - contributing to the Shopware core -Our setup is based on [Docker](https://www.docker.com/), a platform that enables developers to develop, ship, and run applications inside containers: lightweight, standalone, and executable packages. Docker enables production-like conditions consistent across teams and CI/CD, and makes it easy to reset or rebuild environments (`docker compose down -v`). When you need you need full service parity (e.g. caching, queues, search), Docker shines. +The Shopware 6 development environment is primarily supported and recommended to be used with [Docker](https://www.docker.com/). This platform enables developers to develop, ship, and run applications inside containers: lightweight, standalone, and executable packages. Docker enables production-like conditions consistent across teams and CI/CD, and makes it easy to reset or rebuild environments. Docker is especially useful when full service parity is required (e.g., caching, queues, search). Our [Docker setup](./docker-setup.md) aims to provide a smooth onboarding experience aligned with modern development practices. It runs your entire Shopware environment in containers, including all backend services (PHP, MySQL, Node, an Elasticsearch-compatible search engine, Redis, Mailhog, etc.). No manual installation required. From 80c323da85597d7cd25cb358113513e10c8725c9 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:25:39 +0100 Subject: [PATCH 14/45] Update guides/installation/installation-intro.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/installation-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md index cf97356501..7e7ef1cc98 100644 --- a/guides/installation/installation-intro.md +++ b/guides/installation/installation-intro.md @@ -15,7 +15,7 @@ Welcome to the Shopware 6 Developer Installation Guide, which will help you set The Shopware 6 development environment is primarily supported and recommended to be used with [Docker](https://www.docker.com/). This platform enables developers to develop, ship, and run applications inside containers: lightweight, standalone, and executable packages. Docker enables production-like conditions consistent across teams and CI/CD, and makes it easy to reset or rebuild environments. Docker is especially useful when full service parity is required (e.g., caching, queues, search). -Our [Docker setup](./docker-setup.md) aims to provide a smooth onboarding experience aligned with modern development practices. It runs your entire Shopware environment in containers, including all backend services (PHP, MySQL, Node, an Elasticsearch-compatible search engine, Redis, Mailhog, etc.). No manual installation required. +The [Docker-based setup](./docker-setup.md) aims to provide a smooth onboarding experience aligned with modern development practices. It runs your entire Shopware environment in containers, including all backend services (PHP, MySQL, Node, an Elasticsearch-compatible search engine, Redis, Mailhog, etc.). No manual installation is required. The pages that follow assume that you're using Docker itself. That said, the Shopware community has produced some related tooling for developers who prefer more automated or GUI-friendly ways to run Docker environments: DDEV and Dockware. Both are **community-maintained** and not officially supported by Shopware. From 997971c8075964441c0582482fe3762e542f75a6 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:27:30 +0100 Subject: [PATCH 15/45] Update guides/installation/docker-setup.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/docker-setup.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index 4c0236de5a..8311ad7c7d 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -109,8 +109,16 @@ What happens during `make setup`: - If search was enabled during project creation, an Elasticsearch-compatible search service runs as part of the Docker stack ::: -You verify the installation succeeded by opening . +Verify that the installation completed successfully by opening . -Use `make up` and `make down` to start or stop your environment. Use `docker compose down -v` to fully reset it. The `-v` flag deletes the containers, networks, and volumes, meaning all stored data will be lost. +Use the following commands to manage the development environment: -On the next page, we'll help you to start developing. +```bash +# Start the environment +make up + +# Stop the environment +make down + +# Fully reset the environment ( "-v" flag removes containers, networks, and volumes - all stored data will be lost) +docker compose down -v From ecc098cac84ef5b67e1f511b3a601318978dbd3c Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:39:28 +0100 Subject: [PATCH 16/45] Update guides/installation/installation-intro.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/installation-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md index 7e7ef1cc98..756a12714e 100644 --- a/guides/installation/installation-intro.md +++ b/guides/installation/installation-intro.md @@ -21,7 +21,7 @@ The pages that follow assume that you're using Docker itself. That said, the Sho ## DDEV -[DDEV](https://ddev.com/) is a developer-friendly wrapper around Docker that automates environment setup using simple CLI commands. Community members enjoy these features: +[DDEV](https://ddev.com/) is a developer-friendly wrapper around Docker that automates environment setup using simple CLI commands. Key features include: - Simplifies Docker configuration: no manual `docker-compose.yml` needed. - One command (`ddev start`) to start your Shopware environment. From 218d3d76a18d3c7b218ef353efe42b127a40328b Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:40:18 +0100 Subject: [PATCH 17/45] Update guides/installation/installation-intro.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/installation-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md index 756a12714e..befedea9d2 100644 --- a/guides/installation/installation-intro.md +++ b/guides/installation/installation-intro.md @@ -28,7 +28,7 @@ The pages that follow assume that you're using Docker itself. That said, the Sho - Easy to switch PHP/MySQL/Node versions per project. - Integrates well with VS Code and PHPStorm. -[DDEV with Shopware example →](https://github.com/ddev/test-shopware6) +For a DDEV-based Shopware example, see [DDEV with Shopware](https://github.com/ddev/test-shopware6) ### Dockware setup From 4b6ed1641ef0aeaa90b65c407790821143e16840 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:40:56 +0100 Subject: [PATCH 18/45] Update guides/installation/installation-intro.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/installation-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md index befedea9d2..60341732cd 100644 --- a/guides/installation/installation-intro.md +++ b/guides/installation/installation-intro.md @@ -30,7 +30,7 @@ The pages that follow assume that you're using Docker itself. That said, the Sho For a DDEV-based Shopware example, see [DDEV with Shopware](https://github.com/ddev/test-shopware6) -### Dockware setup +## Dockware [Dockware](https://www.dockware.io/) provides ready-to-run Docker images for quickly spinning up demo stores or full local environments in seconds. It emphasizes minimal setup over full customization. Community members enjoy these features: From 22c9dab50483b8e25ff790f8330e9beb5c3b5a08 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:41:15 +0100 Subject: [PATCH 19/45] Update guides/installation/installation-intro.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/installation-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md index 60341732cd..f7132072fe 100644 --- a/guides/installation/installation-intro.md +++ b/guides/installation/installation-intro.md @@ -32,7 +32,7 @@ For a DDEV-based Shopware example, see [DDEV with Shopware](https://github.com/d ## Dockware -[Dockware](https://www.dockware.io/) provides ready-to-run Docker images for quickly spinning up demo stores or full local environments in seconds. It emphasizes minimal setup over full customization. Community members enjoy these features: +[Dockware](https://www.dockware.io/) provides ready-to-run Docker images for quickly spinning up demo stores or full local environments in seconds. It emphasizes minimal setup over full customization. Key features include: - Pre-built images for Shopware 5, 6, and nightly builds. - Includes all key services: PHP, DB, Elasticsearch, Mailhog, Adminer, etc. From 11091059c67db3bfe07748cab35859dd7fa89fde Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:41:36 +0100 Subject: [PATCH 20/45] Update guides/installation/installation-intro.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/installation-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md index f7132072fe..fbf8c8157f 100644 --- a/guides/installation/installation-intro.md +++ b/guides/installation/installation-intro.md @@ -34,7 +34,7 @@ For a DDEV-based Shopware example, see [DDEV with Shopware](https://github.com/d [Dockware](https://www.dockware.io/) provides ready-to-run Docker images for quickly spinning up demo stores or full local environments in seconds. It emphasizes minimal setup over full customization. Key features include: -- Pre-built images for Shopware 5, 6, and nightly builds. +- Pre-built images for Shopware 5, Shopware 6, and nightly builds. - Includes all key services: PHP, DB, Elasticsearch, Mailhog, Adminer, etc. - Great for testing specific versions or quick evaluation. - Can be used standalone or integrated into CI pipelines. From 7d7cde55888badb5bcba438987d17eccf313c9ba Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:41:54 +0100 Subject: [PATCH 21/45] Update guides/installation/installation-intro.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/installation-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md index fbf8c8157f..03b1d208b0 100644 --- a/guides/installation/installation-intro.md +++ b/guides/installation/installation-intro.md @@ -39,7 +39,7 @@ For a DDEV-based Shopware example, see [DDEV with Shopware](https://github.com/d - Great for testing specific versions or quick evaluation. - Can be used standalone or integrated into CI pipelines. -[Dockware documentation →](https://docs.dockware.io/) +Refer to [Dockware documentation](https://docs.dockware.io/) for more info. :::info Looking for older installation methods that are no longer recommended? See our [Legacy Installation Guides](./legacy-setups/). From 03e07d2f242bedbb8dfca074aad983a270130100 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:42:11 +0100 Subject: [PATCH 22/45] Update guides/installation/project-overview.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/project-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md index 28078f1f47..b2d5bfcf71 100644 --- a/guides/installation/project-overview.md +++ b/guides/installation/project-overview.md @@ -5,7 +5,7 @@ nav: --- -# Overview: Understanding your Shopware project +# Understanding your Shopware project You’ve just installed Shopware. But what exactly did you get? This page is an explainer to guide you through fundamentals you'll use through the rest of your development workflow. From 043692f37b8716ac8a1c60216feb7cb41cbb2d4a Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:42:33 +0100 Subject: [PATCH 23/45] Update guides/installation/hardware-requirements.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/hardware-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/hardware-requirements.md b/guides/installation/hardware-requirements.md index 3a76abfc67..6085ecba79 100644 --- a/guides/installation/hardware-requirements.md +++ b/guides/installation/hardware-requirements.md @@ -5,7 +5,7 @@ nav: --- -# Hardware requirements +# Hardware Requirements Before setting up your Shopware 6 development environment, make sure your system is ready. Check these basics before installation: From 2d7ad8e8febfd0a1a2549ac7f2261edb1a323602 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:42:57 +0100 Subject: [PATCH 24/45] Update guides/installation/installation-intro.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/installation-intro.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md index 03b1d208b0..d10099b894 100644 --- a/guides/installation/installation-intro.md +++ b/guides/installation/installation-intro.md @@ -44,3 +44,5 @@ Refer to [Dockware documentation](https://docs.dockware.io/) for more info. :::info Looking for older installation methods that are no longer recommended? See our [Legacy Installation Guides](./legacy-setups/). ::: + +Next, check the [hardware requirements](./hardware-requirements.md) to prepare your system. From d25950d42c16915bcd0824f4426f10520de3a172 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:43:19 +0100 Subject: [PATCH 25/45] Update guides/installation/hardware-requirements.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/hardware-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/hardware-requirements.md b/guides/installation/hardware-requirements.md index 6085ecba79..8deeb2cad4 100644 --- a/guides/installation/hardware-requirements.md +++ b/guides/installation/hardware-requirements.md @@ -7,7 +7,7 @@ nav: # Hardware Requirements -Before setting up your Shopware 6 development environment, make sure your system is ready. Check these basics before installation: +Before setting up the Shopware 6 development environment, ensure your system meets the following basic requirements. - 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) From 7fb892c6fb8236b9b89f6bbf4c8d3daeb9bff3ca Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:43:49 +0100 Subject: [PATCH 26/45] Update guides/installation/hardware-requirements.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/hardware-requirements.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guides/installation/hardware-requirements.md b/guides/installation/hardware-requirements.md index 8deeb2cad4..dd5e30541e 100644 --- a/guides/installation/hardware-requirements.md +++ b/guides/installation/hardware-requirements.md @@ -9,10 +9,10 @@ nav: Before setting up the Shopware 6 development environment, ensure your system meets the following basic requirements. -- 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) -- You have at least 8 GB RAM (16 GB recommended) and 10 GB free disk space -- You have a reliable Internet connection for dependency downloads +- Unix-based system (macOS or Linux), or Windows with WSL 2 or Docker for full compatibility +- Administrative/root privileges (if required within the organization) +- At least 8 GB RAM (16 GB recommended) and 10 GB free disk space +- Reliable internet connection for dependency downloads These recommendations ensure smooth local development regardless of your setup: From db0a0176aac47133e2cde03268d9ddda056e8c3b Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:44:25 +0100 Subject: [PATCH 27/45] Update guides/installation/hardware-requirements.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/hardware-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/hardware-requirements.md b/guides/installation/hardware-requirements.md index dd5e30541e..384b8c349f 100644 --- a/guides/installation/hardware-requirements.md +++ b/guides/installation/hardware-requirements.md @@ -14,7 +14,7 @@ Before setting up the Shopware 6 development environment, ensure your system mee - At least 8 GB RAM (16 GB recommended) and 10 GB free disk space - Reliable internet connection for dependency downloads -These recommendations ensure smooth local development regardless of your setup: +## System requirements | Component | Recommended | |:---------------------|:-------------------------------------------------------------| From f09e574eed28d8fb0e0ca44ea8b728fa6baf7577 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:44:48 +0100 Subject: [PATCH 28/45] Update guides/installation/hardware-requirements.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/hardware-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/hardware-requirements.md b/guides/installation/hardware-requirements.md index 384b8c349f..ec0bd865f1 100644 --- a/guides/installation/hardware-requirements.md +++ b/guides/installation/hardware-requirements.md @@ -26,7 +26,7 @@ Before setting up the Shopware 6 development environment, ensure your system mee ## Permissions and networking - 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: +- On Linux, you may need to add your user to the `docker` group using the below command: ```bash sudo usermod -aG docker $USER From bf38c99210506223d22ccb489cff0174461f485a Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:49:36 +0100 Subject: [PATCH 29/45] Update guides/installation/docker-setup.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/docker-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index 8311ad7c7d..74c70e2a04 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -5,7 +5,7 @@ nav: --- -# Docker setup +# Docker Setup This guide is for developing Shopware stores and extensions. By the end of this page, you'll have a running empty Shopware instance and can immediately start working in the [Administration](https://developer.shopware.com/docs/concepts/framework/architecture/administration-concept.html). From c5eb0be64c6f0cd8706169ac9d6ab2920a7a3276 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:51:07 +0100 Subject: [PATCH 30/45] Update installation-intro.md --- guides/installation/installation-intro.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md index d10099b894..38855f0958 100644 --- a/guides/installation/installation-intro.md +++ b/guides/installation/installation-intro.md @@ -39,8 +39,6 @@ For a DDEV-based Shopware example, see [DDEV with Shopware](https://github.com/d - Great for testing specific versions or quick evaluation. - Can be used standalone or integrated into CI pipelines. -Refer to [Dockware documentation](https://docs.dockware.io/) for more info. - :::info Looking for older installation methods that are no longer recommended? See our [Legacy Installation Guides](./legacy-setups/). ::: From a63582d7187fe7ab5ba2b1de583002413a9235b9 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 14:52:48 +0100 Subject: [PATCH 31/45] Apply suggestion from @sushmangupta Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/docker-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index 74c70e2a04..ecfeed17dd 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -7,7 +7,7 @@ nav: # Docker Setup -This guide is for developing Shopware stores and extensions. By the end of this page, you'll have a running empty Shopware instance and can immediately start working in the [Administration](https://developer.shopware.com/docs/concepts/framework/architecture/administration-concept.html). +This guide is for developing Shopware stores and extensions. By the end of this section, you will have an empty *running* Shopware instance and can immediately start developing. :::info [Go here](../../hosting/installation-updates/docker.md) for information about using Docker for production. To contribute to the Shopware platform itself, visit our [Contributing.md guide](https://github.com/shopware/shopware/blob/trunk/CONTRIBUTING.md). From 244b391adb98fde328fdee13178bd343484c8721 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 15:53:40 +0100 Subject: [PATCH 32/45] Update guides/installation/installation-intro.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/installation-intro.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md index 38855f0958..752f807c85 100644 --- a/guides/installation/installation-intro.md +++ b/guides/installation/installation-intro.md @@ -17,7 +17,9 @@ The Shopware 6 development environment is primarily supported and recommended to The [Docker-based setup](./docker-setup.md) aims to provide a smooth onboarding experience aligned with modern development practices. It runs your entire Shopware environment in containers, including all backend services (PHP, MySQL, Node, an Elasticsearch-compatible search engine, Redis, Mailhog, etc.). No manual installation is required. -The pages that follow assume that you're using Docker itself. That said, the Shopware community has produced some related tooling for developers who prefer more automated or GUI-friendly ways to run Docker environments: DDEV and Dockware. Both are **community-maintained** and not officially supported by Shopware. +The pages that follow assume that you're using Docker itself. + +The Shopware community has produced some related tooling for developers who prefer more automated or GUI-friendly ways to run Docker environments: [DDEV](#DDEV) and Dockware(#Dockware setup). Both are **community-maintained** and not officially supported by Shopware. ## DDEV From c96e55b226e653573b796ab3381f966aa17759e0 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 15:54:09 +0100 Subject: [PATCH 33/45] Update guides/installation/docker-setup.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/docker-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index ecfeed17dd..fc8fb79229 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -60,7 +60,7 @@ This step creates your Shopware project using PHP and Composer inside the Docker The Docker setup installs development dependencies (`require-dev`) and [`shopware/dev-tools`](https://github.com/shopware/dev-tools). This enables the Symfony profiler, [demo data](https://github.com/shopware/SwagPlatformDemoData), linting tools, and test tooling. ::: -Project creation takes a few minutes to complete. In your terminal, this prompt will eventually appear: +Project creation takes a few minutes to complete. When prompted in the terminal, you will see: `Do you want to use Elasticsearch? (y/N)` From 2546aa814af81c31ab2e08af5ffc1e8b8a425ac5 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 15:58:16 +0100 Subject: [PATCH 34/45] Update guides/installation/docker-setup.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/docker-setup.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index fc8fb79229..23d89e9a4f 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -82,7 +82,9 @@ make up This command starts Shopware and all required services (web server, database, search, Mailpit, etc.) in the background. Docker images already include all required PHP extensions and services, so the system-check step of the installer is always fulfilled. -**Tip:** You can check container status anytime with: +:::info +You can check the container status anytime with the below command: +::: ```bash docker compose ps From 433c0a3e7f666374f323a3d05d80db72aaab2a35 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 16:00:19 +0100 Subject: [PATCH 35/45] Update guides/installation/docker-setup.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/docker-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index 23d89e9a4f..46e41b8cc5 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -10,7 +10,7 @@ nav: This guide is for developing Shopware stores and extensions. By the end of this section, you will have an empty *running* Shopware instance and can immediately start developing. :::info -[Go here](../../hosting/installation-updates/docker.md) for information about using Docker for production. To contribute to the Shopware platform itself, visit our [Contributing.md guide](https://github.com/shopware/shopware/blob/trunk/CONTRIBUTING.md). +For information about using Docker in production, see [Docker for production](../../hosting/installation-updates/docker.md). To contribute to the Shopware platform itself, visit the [Contributing.md guide](https://github.com/shopware/shopware/blob/trunk/CONTRIBUTING.md). ::: ## Prerequisites From 934ae82d2ffcea103c2cc6b03e73896784fc6b84 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 16:12:18 +0100 Subject: [PATCH 36/45] Update guides/installation/docker-setup.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/docker-setup.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index 46e41b8cc5..7b4cd95709 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -15,12 +15,16 @@ For information about using Docker in production, see [Docker for production](.. ## Prerequisites -- [Docker](https://docs.docker.com/get-started/get-docker/) or [OrbStack](https://docs.orbstack.dev/quick-start) is installed and running. OrbStack is a fast, free (for personal use) Docker-compatible replacement on macOS. - - Ensure Docker has permission to bind to local ports (typically:80 or:8080) and is not already bound to conflicting ports -- `make` is installed on your machine (`apt install make` on Ubuntu, `brew install make` on macOS) -- `Docker Compose` is installed on your machine. Docker Desktop provides it automatically. If you're using OrbStack or something else, you can follow the official [Docker Compose installation guide](https://docs.docker.com/compose/install/). -- Enough disk and network capacity to pull images (~500MB+ per image depending on tags) -- [Git](https://git-scm.com/) installed and available in your `PATH` +- Install and run either [Docker](https://docs.docker.com/get-started/get-docker/) or [OrbStack](https://docs.orbstack.dev/quick-start). OrbStack is a fast, Docker-compatible alternative for macOS (free for personal use). +- Ensure Docker has permission to bind to local ports (typically `:80` or `:8080`) and that no conflicting services are already using these ports. +- Install `make`: + +```bash +# Ubuntu +apt install make + +# macOS +brew install make This setup comes preinstalled with the [Shopware CLI](../../../products/cli/index.md), which helps with building, refactoring, validating, and managing Shopware projects and extensions. It works with all setups and is used in most Shopware upgrade, build, and CI workflows. The CLI is available in the container shell. From 7f0d63e8f31dc5debd9ada5d74d63e1248eccba9 Mon Sep 17 00:00:00 2001 From: somethings Date: Fri, 13 Feb 2026 16:12:50 +0100 Subject: [PATCH 37/45] Update guides/installation/docker-setup.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/docker-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index 7b4cd95709..c81c918a41 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -26,7 +26,7 @@ apt install make # macOS brew install make -This setup comes preinstalled with the [Shopware CLI](../../../products/cli/index.md), which helps with building, refactoring, validating, and managing Shopware projects and extensions. It works with all setups and is used in most Shopware upgrade, build, and CI workflows. The CLI is available in the container shell. +This Docker setup includes the [Shopware CLI](../../../products/cli/index.md), which helps build, refactor, validate, and manage Shopware projects and extensions. It works with all setups and is used in most Shopware upgrade, build, and CI workflows. The CLI is available in the container shell. ## Pre-pull the image (optional) From 5e94713b5648e82f0f834df797df21375b1c64e2 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Fri, 13 Feb 2026 16:28:20 +0100 Subject: [PATCH 38/45] Update guides/installation/docker-setup.md --- guides/installation/docker-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index c81c918a41..e103609fb1 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -46,7 +46,7 @@ Create an empty directory for your project and navigate into it: mkdir my-project && cd my-project `` -Now create a new project: +Create a new project: ```bash docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup From 62d22e389f9e7ddae031e3ca7abfe73dfcead8e4 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Fri, 13 Feb 2026 16:29:16 +0100 Subject: [PATCH 39/45] Update guides/installation/docker-setup.md --- guides/installation/docker-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index e103609fb1..a6ebf76816 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -40,7 +40,7 @@ If you skip this step, Docker will automatically download the image during proje ## Create a new Shopware project -Create an empty directory for your project and navigate into it: +Create an empty directory for your project and navigate to it: ```bash mkdir my-project && cd my-project From a366eed25d47a87c9655c49db5464b74cd34865f Mon Sep 17 00:00:00 2001 From: sushmangupta Date: Mon, 16 Feb 2026 17:35:44 +0100 Subject: [PATCH 40/45] Content changes and redirect updates --- .gitbook.yaml | 9 +- guides/installation/advanced-options.md | 2 +- guides/installation/after-installation.md | 67 +++---- guides/installation/docker-setup.md | 6 +- guides/installation/hardware-requirements.md | 10 +- .../{installation-intro.md => index.md} | 14 +- guides/installation/project-overview.md | 43 ++++- guides/legacy-setups/devenv-setup.md | 4 +- guides/legacy-setups/setup-symfony-cli.md | 174 ------------------ 9 files changed, 103 insertions(+), 226 deletions(-) rename guides/installation/{installation-intro.md => index.md} (89%) delete mode 100644 guides/legacy-setups/setup-symfony-cli.md diff --git a/.gitbook.yaml b/.gitbook.yaml index 81ec21a937..010d572c46 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -90,4 +90,11 @@ redirects: products/extensions/migration-assistant/concept.html: products/extensions/migration-assistant/concept/index.html products/extensions/migration-assistant/guides.html: products/extensions/migration-assistant/guides/index.html products/cli/project-commands/project-config-sync.html: resources/tooling/fixture-bundle/index.html - products/sales-agent/deployment.html: products/sales-agent/best-practices/app-deployment/hosted-with-ubuntu-server.html \ No newline at end of file + products/sales-agent/deployment.html: products/sales-agent/best-practices/app-deployment/hosted-with-ubuntu-server.html + guides/installation/hardware-requirements.html: guides/installation/requirements.html + guides/installation/docker-setup.html: guides/installation/setups/docker.html + guides/installation/project-overview.html: guides/installation/template.html + guides/installation/advanced-options.html: guides/installation/setups/docker-options.html + guides/legacy-setups/devenv-setup.html: guides/installation/setups/devenv.html + guides/legacy-setups/symfony-cli-setup.html: guides/installation/setups/symfony-cli.html + guides/legacy-setups/devenv-options.html: guides/installation/setups/devenv-options.html \ No newline at end of file diff --git a/guides/installation/advanced-options.md b/guides/installation/advanced-options.md index 4f64eb40af..7aa3b23526 100644 --- a/guides/installation/advanced-options.md +++ b/guides/installation/advanced-options.md @@ -7,7 +7,7 @@ nav: # Advanced options -This page covers optional and advanced Docker configuration for Shopware projects. You can refer to information here once your local environment is running and you want to customize your environment, mirror production more closely, or support advanced workflows. +This page covers optional and advanced Docker configuration for Shopware projects. You can refer to this section, once your local environment is running and you want to customize your environment, mirror production more closely, or support advanced workflows. ## Customizing the runtime environment diff --git a/guides/installation/after-installation.md b/guides/installation/after-installation.md index c94dd08aff..5562cd7caf 100644 --- a/guides/installation/after-installation.md +++ b/guides/installation/after-installation.md @@ -5,24 +5,23 @@ nav: --- -# After installation +# After Installation - Start Development -You now have a running Shopware instance. This page explains what you typically do next, in the order most developers need it. +You now have a running Shopware instance. This section outlines the typical next steps for development. -## Start developing -### Administration & Storefront +## Access administration and storefront - Storefront: [http://localhost:8000](http://localhost:8000) - Administration: [http://localhost:8000/admin](http://localhost:8000/admin) *(default credentials: `admin` / `shopware`)* -Most day-to-day work happens in: +Common development areas: - `custom/`: your plugins and themes - `bin/console`: application CLI (Symfony console) - the Administration UI -### Using the Shopware CLI +## Using the Shopware CLI To run CLI commands, open a shell inside the web container: @@ -46,17 +45,19 @@ Development and automation tasks are handled in the CLI, including: - adjusting system configuration - developing plugins and themes -**Tip**: Inside the container, you only need `bin/console …`. But if you prefer to run commands from your host machine instead, you can use the full Docker prefix: `docker compose exec web bin/console cache:clear`. +:::info +Inside the container, you only need `bin/console …`. But if you prefer to run commands from your host machine instead, you can use the full Docker prefix: `docker compose exec web bin/console cache:clear`. +::: -Please note that some setup tasks are done in the Administration UI, including: +## Administration setup tasks -- Opening the **Admin** at -- Signing in or creating a Shopware account; necessary when you want to install Store extensions. -- Connecting to the **Shopware Store** -- Installing plugins or themes from the Store -- Connecting payment methods; not necessary for local development +- Open the **Admin** at `http://localhost:8000/admin` +- Sign in or create a Shopware account; necessary when you want to install Store extensions. +- Connect to the **Shopware Store** +- Install plugins or themes from the Store +- Configure payment methods; not necessary for local development -Basic shop settings such as shop name, default language, and currency can be changed later in the Admin under **Settings > Shop > Basic information**. +Basic shop settings such as shop name, default language, and currency can be changed later in the Admin under **`Settings > Shop > Basic information`**. ## Frontend and Administration development @@ -76,20 +77,24 @@ make watch-admin make watch-storefront ``` -These will become part of your everyday development workflow. Watchers are typically used during active UI development. +These commands become part of everyday development workflow. Watchers are typically used during active UI development. ## Inspecting and debugging locally -If you connect to the database from your host machine—for example, via Adminer or a local MySQL client—use `127.0.0.1` or `localhost` and the exposed port shown in `docker compose ps`. +To connect to the database from your host machine (for example, via Adminer or a local MySQL client), use: -## Local services overview +- Host: `127.0.0.1` or `localhost` +- And the exposed port shown in -With Shopware running, your local setup includes a web service that serves both the storefront and the Administration. By default this uses Caddy with PHP-FPM, but you may use Nginx instead. Knowing which service does what helps when debugging or connecting external tools. +```bash +docker compose ps +``` -### Accessing services +## Local services overview -Your local stack includes: +With Shopware running, your local setup includes +- A web service (serves both the storefront and the administration) - Database (MariaDB): runs on port 3306 inside Docker. - Internal hostname: `database` - Host access: `localhost:3306`, if you want to inspect the database directly. @@ -102,7 +107,7 @@ Inspect ports and services with: docker compose ps ``` -### Enable profiler/debugging for PHP +## Enable profiler/debugging for PHP Once your Shopware environment is running, you may want to enable PHP debugging or profiling to inspect code execution, set breakpoints, or measure performance. The default setup doesn’t include these tools, but you can enable them using Docker overrides. @@ -160,7 +165,7 @@ Use `compose.override.yaml` to: This keeps your changes local and out of version control. -## Working with data & external systems +## Working with data and external systems ### Store API access key @@ -174,16 +179,18 @@ Access tokens: | Access key | `string of capital letters` | ``` -The access key for authenticating requests to the [Store API](../../../concepts/api/store-api)—for example, when fetching product or category data from an external app, headless storefront, or API client. Example usage: +The access key for authenticating requests to the [Store API](../../../concepts/api/store-api) - for example, when fetching product or category data from an external app, headless storefront, or API client. Example usage: ```bash curl -H "sw-access-key: YOUR_ACCESS_KEY" \ http://localhost:8000/store-api/product ``` -You can view or regenerate this key in the Admin under Sales Channels → [Your Channel] → API Access. +You can view or regenerate this key in the Admin under **`Sales Channels > [Your Channel] > API Access`**. + +## Environment configuration -## Connecting to a remote database +### Connecting to a remote database If you want to use a database outside the Docker stack, set `DATABASE_URL` in `.env.local` in the standard form: @@ -207,13 +214,13 @@ Other IDs may cause permission errors when running `make up` or writing to proje ## Preparing for production -If you're preparing to run Shopware in production using Docker, [this page](../../hosting/installation-updates/docker.md) covers production images, environment configuration, and deployment workflows. +If you're preparing to run [Shopware in production using Docker](../../hosting/installation-updates/docker.md) covers production images, environment configuration, and deployment workflows. -## Build and Watch the Administration and Storefront +## Build and watch the administration and Storefront You only need to run this step if you’re developing or customizing the frontend (Administration or Storefront). It compiles JavaScript and CSS assets so your changes are visible immediately. -The created project contains Bash scripts in the `bin/` folder to build and watch the Administration and Storefront. Run the following commands: +The created project contains bash scripts in the `bin/` folder to build and watch the Administration and Storefront. Run the following commands: ```bash ./bin/build-administration.sh @@ -226,12 +233,10 @@ Use these scripts to build the Administration and Storefront. The `watch` comman ## Advanced Docker configuration -For advanced topics like: +For advanced below topics, see [Advanced Options](advanced-options.md) - image variants - Minio (S3) - OrbStack routing - production image proxy configuration - service internals - -see [Advanced Options](advanced-options.md) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index a6ebf76816..ea17adf5ac 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -25,6 +25,7 @@ apt install make # macOS brew install make +``` This Docker setup includes the [Shopware CLI](../../../products/cli/index.md), which helps build, refactor, validate, and manage Shopware projects and extensions. It works with all setups and is used in most Shopware upgrade, build, and CI workflows. The CLI is available in the container shell. @@ -44,7 +45,7 @@ Create an empty directory for your project and navigate to it: ```bash mkdir my-project && cd my-project -`` +``` Create a new project: @@ -128,3 +129,6 @@ make down # Fully reset the environment ( "-v" flag removes containers, networks, and volumes - all stored data will be lost) docker compose down -v +``` + +Next, you can start implementing your changes. However, get a [project overview](./project-overview.md) before that. diff --git a/guides/installation/hardware-requirements.md b/guides/installation/hardware-requirements.md index ec0bd865f1..657cccac96 100644 --- a/guides/installation/hardware-requirements.md +++ b/guides/installation/hardware-requirements.md @@ -23,13 +23,17 @@ Before setting up the Shopware 6 development environment, ensure your system mee | **Disk space** | ~10 GB free for Shopware + services | | **Operating system** | macOS 13+, Windows 10/11 (Pro with WSL 2), or Linux (64-bit) | -## Permissions and networking +## Permissions and networking requirements -- Allow your system’s firewall to let containers or local web servers communicate internally. +- 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 using the below command: ```bash sudo usermod -aG docker $USER ``` -Once your environment meets these requirements, proceed to [setup](./docker-setup.md). +Once your environment meets these requirements, proceed to [Docker setup](./docker-setup.md). + +:::info +For other modes of setup, refer to documentation on [legacy setups](../legacy-setups) that we no longer recommend. +::: diff --git a/guides/installation/installation-intro.md b/guides/installation/index.md similarity index 89% rename from guides/installation/installation-intro.md rename to guides/installation/index.md index 752f807c85..65933749fe 100644 --- a/guides/installation/installation-intro.md +++ b/guides/installation/index.md @@ -7,11 +7,15 @@ nav: # Overview of Shopware 6 Installation +:::info +The installation workflow has been streamlined to focus on a Docker-based setup as the primary approach. Previous installation methods are available in the [Legacy Setups](./legacy-setups) section. +::: + Welcome to the Shopware 6 Developer Installation Guide, which will help you set up a local Shopware 6 development environment whether you’re: -- building a custom shop project -- developing a plugin, app, or theme -- contributing to the Shopware core +- Building a custom shop project +- Developing a plugin, app, or theme +- Contributing to the Shopware core The Shopware 6 development environment is primarily supported and recommended to be used with [Docker](https://www.docker.com/). This platform enables developers to develop, ship, and run applications inside containers: lightweight, standalone, and executable packages. Docker enables production-like conditions consistent across teams and CI/CD, and makes it easy to reset or rebuild environments. Docker is especially useful when full service parity is required (e.g., caching, queues, search). @@ -41,8 +45,4 @@ For a DDEV-based Shopware example, see [DDEV with Shopware](https://github.com/d - Great for testing specific versions or quick evaluation. - Can be used standalone or integrated into CI pipelines. -:::info -Looking for older installation methods that are no longer recommended? See our [Legacy Installation Guides](./legacy-setups/). -::: - Next, check the [hardware requirements](./hardware-requirements.md) to prepare your system. diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md index b2d5bfcf71..2f5e8d5c22 100644 --- a/guides/installation/project-overview.md +++ b/guides/installation/project-overview.md @@ -7,7 +7,7 @@ nav: # Understanding your Shopware project -You’ve just installed Shopware. But what exactly did you get? This page is an explainer to guide you through fundamentals you'll use through the rest of your development workflow. +You’ve just installed Shopware. But what exactly did you get? This section guides you through fundamentals you'll use through the rest of your development workflow. ## Development tooling included @@ -26,17 +26,19 @@ In day-to-day development, you’ll mostly interact with: - **custom/**: where you build your own plugins and themes - **bin/console**: the application CLI that ships with Shopware (Symfony console). It's used for tasks like running migrations, installing plugins, clearing caches, or managing configuration inside your project. -Note: `bin/console` is different from the standalone [Shopware CLI](https://github.com/shopware/shopware-cli) tool used for extension builds and CI workflows. The Docker setup already includes the standalone Shopware CLI inside the container. +:::info +`bin/console` is different from the standalone [Shopware CLI](https://github.com/shopware/shopware-cli) tool used for extension builds and CI workflows. The Docker setup already includes the standalone Shopware CLI inside the container. +::: Most other files in the project either configure the environment or support these core layers. ## Project template -All setups start from the Shopware Project Template: a Composer-based project that installs Shopware as a dependency. It serves as the foundation for new Shopware projects as well as for developing plugins, apps, or themes. This allows you to: +All setups start from the Shopware Project Template - a Composer-based project that installs Shopware as a dependency. It serves as the foundation for new Shopware projects as well as for developing plugins, apps, or themes. This allows you to: -- extend the project with plugins, apps, or themes -- customize configuration and services -- tailor the environment to your development needs +- Extend the project with plugins, apps, or themes +- Customize configuration and services +- Tailor the environment to your development needs ### Components explained @@ -51,7 +53,32 @@ The following table explains the Docker-level components created when you start | **Container `my-project-web-1`** | PHP + Caddy web service | Runs Shopware itself and serves the storefront and Admin UI at [http://localhost:8000](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](http://localhost:8080). | -### Project structure explained +### Project structure + +After installation, your Shopware project contains the following root-level directories and files: + +```text +project-root/ +├── bin/ +├── config/ +├── custom/ +│ ├── plugins/ +│ ├── apps/ +│ └── static-plugins/ +├── files/ +├── public/ +├── src/ +├── var/ +├── vendor/ +├── compose.yaml +├── compose.override.yaml +├── composer.json +├── composer.lock +├── symfony.lock +├── Makefile +├── .env +└── README.md +``` This table outlines the key directories and files in your Shopware project and what they are used for. @@ -71,3 +98,5 @@ This table outlines the key directories and files in your Shopware project and w | **symfony.lock** | Symfony dependency snapshot | Records Symfony recipes applied during setup. | Used internally by Symfony Flex; no manual editing. | | **var/** | Runtime data | Cache, logs, temporary files. | Can safely be deleted (Shopware rebuilds it). | | **vendor/** | Dependency code | All installed PHP libraries from Composer. | Analogous to `node_modules/`. | + +With this understanding move to the next section to make changes. diff --git a/guides/legacy-setups/devenv-setup.md b/guides/legacy-setups/devenv-setup.md index 7139cb134a..a14745b78d 100644 --- a/guides/legacy-setups/devenv-setup.md +++ b/guides/legacy-setups/devenv-setup.md @@ -27,7 +27,9 @@ On the host you only need a minimal toolchain: See the [Shopware 6 requirements](../requirements.md) for general system requirements and supported versions. Devenv will provide the exact runtime versions per project. -> **Note:** If you previously installed Nix using an older single-user script or via a package manager (for example, `brew install nix`), remove it first to prevent permission or path conflicts. Removing `/nix` deletes the global Nix store and may require elevated privileges. Use `sudo` if appropriate and double-check before running destructive commands. +:::info +If you previously installed Nix using an older single-user script or via a package manager (for example, `brew install nix`), remove it first to prevent permission or path conflicts. Removing `/nix` deletes the global Nix store and may require elevated privileges. Use `sudo` if appropriate and double-check before running destructive commands. +::: ## Installation diff --git a/guides/legacy-setups/setup-symfony-cli.md b/guides/legacy-setups/setup-symfony-cli.md deleted file mode 100644 index 2a9eac0c65..0000000000 --- a/guides/legacy-setups/setup-symfony-cli.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -nav: - title: Setting up Shopware with Symfony CLI - position: 30 - ---- - -# Setting up Shopware with Symfony CLI - -Symfony CLI lets you run Shopware 6 locally without Docker. It's a lightweight option that uses your system’s PHP, Composer, and Node.js installations. - -Shopware recommends [Docker](./docker.md) as the default setup for most users because it mirrors production and includes all services out of the box. However, if you already have PHP and a database installed locally, or want a faster, low-overhead workflow, Symfony CLI is a solid alternative. - -## Prerequisites - -Before you begin, make sure your system meets the [Shopware 6 requirements](../requirements.md). You’ll need the following tools installed on your host machine: - -- [Symfony CLI](https://symfony.com/download) -- PHP 8.2 or higher with the required extensions; see the [Requirements page](../requirements.md) for the complete list -- [Composer 2.x](https://getcomposer.org/) -- [Node.js 20+](https://nodejs.org/en/download) and npm -- A running MySQL 8 or MariaDB 11 database (local or remote) - -You’ll also need a working web server. The Symfony CLI can provide one automatically for development. - -> **macOS note:** If you installed PHP via Homebrew, make sure the `intl` extension is enabled: `brew install php-intl` then verify with `php -m | grep intl`. - -Optional tools: - -- [Elasticsearch 8](https://www.elastic.co/elasticsearch/) for product search and indexing -- Docker (for running only the database while keeping PHP local) - -## Create a New Project - -Run this command to create a new Shopware production project: - -```bash -composer create-project shopware/production - -# or specify a version -composer create-project shopware/production:6.6.10.0 -``` - -During project creation, Symfony Flex asks whether you want to use Docker. Choose **Yes** if you want to run the database in a container, or **No** to use a local MySQL/MariaDB server. - -For more details, see the [Shopware Production template documentation](../template). - -## Configure database connection - -After creating the project, define your database settings in a `.env.local` file in the project root: - -```dotenv -DATABASE_URL=mysql://username:password@localhost:3306/dbname -``` - -You can define other environment settings (like `APP_URL`, `MAILER_DSN`, or `SHOPWARE_ES_HOSTS`) in `.env.local` as needed. - -Git ignores `.env.local`, so you can safely define machine-specific settings here without affecting your team’s shared configuration. - -### Using Docker for the database (optional) - -Running the database in a Docker container helps keep your local system clean and ensures version consistency with production environments. If you prefer this instead of installing MySQL or MariaDB locally, start Docker with: - -```bash -docker compose up -d -``` - -This command starts the database container in the background. - -To stop and remove the containers, while preserving the database data, run: - -```bash -docker compose down -``` - -Run `docker compose down -v` to remove the containers and delete all stored data volumes. - -::: info -Tip - Use the `-v` flag only if you want to completely reset the database. -::: - -## Install Shopware - -::: info -Always prefix commands with `symfony` to ensure the correct PHP version and configuration are used. Skipping this can cause issues such as using the wrong PHP binary or failing to connect to the Docker-based MySQL database. -::: - -Run the following command to install Shopware: - -```bash -symfony console system:install --basic-setup -``` - -The `--basic-setup` flag initializes Shopware with sensible defaults. It automatically creates a database schema, an admin user, and a default sales channel for the specified `APP_URL` so you can start testing immediately without manual configuration. Optional: Add the `--create-database` flag if your database doesn’t already exist. - -If you encounter file-permission issues when installing or rebuilding caches, run `symfony console cache:clear` or check directory ownership. - -### Default Administration credentials - -Shopware creates a default Administration user during installation: - -| Username | Password | -|:---------|:-----------| -| `admin` | `shopware` | - -**Tip**: Change these credentials after installation for security. - -## Start the webserver - -The Symfony local web server automatically uses the correct PHP version, reads your `.env` configuration, and exposes HTTPS by default. This makes it more reliable than the built-in PHP server for local development. - -Start the local web server with: - -```bash -symfony server:start -``` - -By default, this starts the server on port `8000`. Access the Shopware Administration at [http://localhost:8000/admin](http://localhost:8000/admin) and the Storefront at [http://localhost:8000](http://localhost:8000). - -To run the server in the background, add the `-d` flag: - -```bash -symfony server:start -d -``` - -This frees up your terminal for other commands. - -### Stopping the Web Server - -To stop the server and all running processes, run: - -```bash -symfony server:stop -``` - -**Tip**: If port 8000 is already in use, start the server on a different port: `symfony server:start --port=8080` - -## Set the PHP version (optional, recommended) - -Specify a PHP version to ensure consistent environments across team members. - -To change the PHP version used by Symfony CLI, create a `.php-version` file in the project root and specify the desired version. For example, to use PHP 8.3, create `.php-version` and add: - -```dotenv -8.3 -``` - -Symfony CLI will now use PHP 8.3 for all commands in this project. Commit this file to your version control system so everyone on your team uses the same PHP version. - -To verify which PHP version is active, run: - -```bash -symfony php -v -``` - -## Adjust PHP configuration (Optional) - -Adjusting PHP settings like `memory_limit` or `max_execution_time` can prevent build or cache warm-up processes from failing, especially during large Administration builds or when working on plugins. - -You can override PHP settings for this project by adding a `php.ini` file in the project root. For example, to increase the `memory_limit` to 512 MB, add: - -```ini -memory_limit = 512M -``` - -To confirm your configuration, run: - -```bash -symfony php -i -``` - -By keeping your `php.ini` in version control, you ensure consistent behavior across development environments and CI pipelines. - -Symfony CLI uses PHP’s built-in web server by default. For better performance, you can configure it to use Nginx or Caddy: see the [web server reference](../../../resources/references/config-reference/server/nginx.md). From 492533351bbdba4ed581d50d1c3c7b9d9b14f0d8 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Feb 2026 17:56:06 +0100 Subject: [PATCH 41/45] Update guides/installation/docker-setup.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/docker-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index ea17adf5ac..c7a80d6805 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -29,7 +29,7 @@ brew install make This Docker setup includes the [Shopware CLI](../../../products/cli/index.md), which helps build, refactor, validate, and manage Shopware projects and extensions. It works with all setups and is used in most Shopware upgrade, build, and CI workflows. The CLI is available in the container shell. -## Pre-pull the image (optional) +## Preload Docker image (optional) If you haven’t yet downloaded the Shopware Docker image, pull it now: From aaf9fe910a4c5bee3486fc5a0f5b859188af0213 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Feb 2026 17:57:51 +0100 Subject: [PATCH 42/45] Update docker-setup.md --- guides/installation/docker-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index c7a80d6805..9382f88017 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -29,7 +29,7 @@ brew install make This Docker setup includes the [Shopware CLI](../../../products/cli/index.md), which helps build, refactor, validate, and manage Shopware projects and extensions. It works with all setups and is used in most Shopware upgrade, build, and CI workflows. The CLI is available in the container shell. -## Preload Docker image (optional) +## Pre-pull Docker image (optional) If you haven’t yet downloaded the Shopware Docker image, pull it now: From cc06a0de0171df39f2f95355ca8d38a03d875c4c Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Feb 2026 18:00:44 +0100 Subject: [PATCH 43/45] Apply suggestion from @sushmangupta Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- guides/installation/docker-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md index 9382f88017..945f1c8956 100644 --- a/guides/installation/docker-setup.md +++ b/guides/installation/docker-setup.md @@ -37,7 +37,7 @@ If you haven’t yet downloaded the Shopware Docker image, pull it now: docker pull ghcr.io/shopware/docker-dev:php8.3-node24-caddy ``` -If you skip this step, Docker will automatically download the image during project creation. That’s normal, but pre-pulling makes the process cleaner and enables you to avoid waiting for large image downloads. +If this step is skipped, Docker automatically downloads the image during project creation. Pre-pulling can make the process cleaner and help avoid waiting for large image downloads. ## Create a new Shopware project From e1e110dcd79e80b7392e0558cff540f6d08155df Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Feb 2026 18:16:51 +0100 Subject: [PATCH 44/45] Update add-custom-commands.md --- .../plugin-fundamentals/add-custom-commands.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md index 0854a286bd..5bba742058 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md @@ -7,9 +7,16 @@ nav: # Add Custom CLI Commands -Shopware CLI commands are based on Symfony Console. This means that creating custom commands in Shopware plugins follows the standard Symfony approach. +Shopware CLI commands are based on [Symfony Console](https://symfony.com/doc/current/console.html). This means that creating custom commands in Shopware plugins follows the standard Symfony approach. -See the [official Symfony documentation](https://symfony.com/doc/current/console.html) for the full guide. +To add a custom command in a Shopware plugin, you must register it as a service in your plugin’s `src/Resources/config/services.xml` and tag it with `console.command`: + +```xml + + + + +``` Commands registered as services in a Shopware plugin are automatically available via `bin/console`. From a9a21a8cd10342ea21b794c10e015eccf0230307 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Feb 2026 18:18:18 +0100 Subject: [PATCH 45/45] Update add-custom-commands.md --- .../plugin-fundamentals/add-custom-commands.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md index 5bba742058..3679193170 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md @@ -11,11 +11,15 @@ Shopware CLI commands are based on [Symfony Console](https://symfony.com/doc/cur To add a custom command in a Shopware plugin, you must register it as a service in your plugin’s `src/Resources/config/services.xml` and tag it with `console.command`: -```xml - - - - +```html + + + + + + + + ``` Commands registered as services in a Shopware plugin are automatically available via `bin/console`.