diff --git a/guides/hosting/configurations/framework/index.md b/guides/hosting/configurations/framework/index.md deleted file mode 100644 index 7d64c4b33..000000000 --- a/guides/hosting/configurations/framework/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -nav: - title: Framework - position: 20 - ---- - -# Framework configurations - -## Overview - -Framework configurations are originated in the [Symfony FrameworkBundle](https://symfony.com/doc/current/reference/configuration/framework.html) and are partially documented in this guide. diff --git a/guides/hosting/configurations/framework/routes.md b/guides/hosting/configurations/framework/routes.md deleted file mode 100644 index 1a80c4db7..000000000 --- a/guides/hosting/configurations/framework/routes.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -nav: - title: Custom routes - position: 10 - ---- - -# Custom routes - -## Overview - -Your default routes in Shopware 6 are defined in the controllers of the core or your plugins. An example could be the wishlist route: - -```php - false], defaults: ['_noStore' => true], methods: ['GET'])] -public function index(Request $request, SalesChannelContext $context): Response -{ - $customer = $context->getCustomer(); - - if ($customer !== null && $customer->getGuest() === false) { - $page = $this->wishlistPageLoader->load($request, $context, $customer); - $this->hook(new WishlistPageLoadedHook($page, $context)); - } else { - $page = $this->guestPageLoader->load($request, $context); - $this->hook(new GuestWishlistPageLoadedHook($page, $context)); - } - - return $this->renderStorefront('@Storefront/storefront/page/wishlist/index.html.twig', ['page' => $page]); -} -``` - -It defines that your wishlist page is available at `/wishlist`. This is fine for an English-only shop, but for a multilingual shop, you might want to have a different route for each language. - -For example, you could have `/wishlist` for English and `/merkliste` for German. - -## Configuration - -To easily configure those routes, you can use the `routes.yaml` file in ROOT/config/routes/routes.yaml. Symfony loads this file, which allows you to define your custom `paths`, in our case, for the wishlist index page. - -```yaml -frontend.wishlist.page: - path: - en-GB: '/wishlist' - de-DE: '/merkliste' - controller: 'Shopware\Storefront\Controller\WishlistController::index' - methods: ['GET'] - defaults: - _noStore: true - _routeScope: ['storefront'] - options: - seo: false -``` - -You can configure the `path` with the **locales** (for example, `de-DE`) your shop uses. - -If you want to learn more about routes in Symfony, check out the [Symfony documentation](https://symfony.com/doc/current/routing.html#creating-routes-as-attributes). diff --git a/guides/hosting/configurations/framework/samesite-protection.md b/guides/hosting/configurations/framework/samesite-protection.md deleted file mode 100644 index 5937478f1..000000000 --- a/guides/hosting/configurations/framework/samesite-protection.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -nav: - title: SameSite protection - position: 10 - ---- - -# SameSite protection - -::: info -This feature has been introduced with Shopware version 6.4.3.1 -::: - -## Overview - -The [SameSite configuration](https://symfony.com/doc/current/reference/configuration/framework.html#cookie-samesite) comes with the Symfony FrameworkBundle and supersedes the removed `sw_csrf` Twig function. -It is widely [available](https://caniuse.com/same-site-cookie-attribute) in modern browsers and is set to `lax` per default. - -For more information, refer to [SameSite cookies site](https://web.dev/articles/samesite-cookies-explained?hl=en) - -## Configuration - -Changes to the `cookie_samesite` attribute can be applied to your `framework.yaml`. The `cookie_secure` ensures that cookies are sent via HTTP or HTTPS, depending on the request's origin. - -```yaml - -framework: - session: - cookie_secure: 'auto' - cookie_samesite: lax -``` - -If you want to deactivate the SameSite protection despite security risks, change the value from `lax` to `null`. For detailed configuration options, check the official [Symfony Docs](https://symfony.com/doc/current/reference/configuration/framework.html#cookie-samesite). diff --git a/guides/hosting/configurations/shopware/index.md b/guides/hosting/configurations/shopware/index.md deleted file mode 100644 index 86d21d83d..000000000 --- a/guides/hosting/configurations/shopware/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -nav: - title: Shopware - position: 10 - ---- - -# Shopware configurations - -## Overview - -The following section guides you on the security, performance or structural configurations specific to Shopware 6. diff --git a/guides/hosting/configurations/shopware/stock.md b/guides/hosting/configurations/shopware/stock.md deleted file mode 100644 index be9399062..000000000 --- a/guides/hosting/configurations/shopware/stock.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -nav: - title: Stock - position: 20 - ---- - -# Stock Configuration - -When running Shopware 6 there are various configuration options you can use to customize your installation. These configurations reside in the general [bundle configuration](../../../../guides/hosting/configurations/). - -Some features of Shopware are only activated when the corresponding feature flag is enabled. Feature flags can be enabled in your project's `.env` file: - -<<< @/docs/snippets/config/stock.sh - -## Enable stock management system - -As of Shopware 6.5.5, the stock management system has been rewritten. The `product.stock` field is now the primary source for real-time product stock values. - -The new system is not enabled by default. To enable it, set the `STOCK_HANDLING` feature flag to `1`. - -<<< @/docs/snippets/config/stock.sh - -In the next major version of Shopware, the new stock management system will become the default. - -## Disable stock management system - -Please note this only applies if you have the `STOCK_HANDLING` feature flag enabled. - -You can completely disable Shopware's default stock management system. When disabled, none of the event subscribers for order transitions will be executed. In practice, this means that none of the subscribers in `Shopware\Core\Content\Product\Stock\OrderStockSubscriber` will be executed. - -To disable, set `shopware.stock.enable_stock_management` to `false`: - -<<< @/docs/snippets/config/stock_disabled.yaml - -For more detailed implementation refer to [Stock](../../../../guides/plugins/plugins/content/stock/) guide section. - - diff --git a/guides/hosting/index.md b/guides/hosting/index.md deleted file mode 100644 index 4572d28d1..000000000 --- a/guides/hosting/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -nav: - title: Hosting - position: 30 - ---- - -# 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. diff --git a/guides/hosting/infrastructure/index.md b/guides/hosting/infrastructure/index.md deleted file mode 100644 index 5ec07a316..000000000 --- a/guides/hosting/infrastructure/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -nav: - title: Infrastructure - position: 40 - ---- - -# Infrastructure - -The Hosting infrastructure for Shopware includes Elasticsearch for advanced search, a database cluster for data storage, a filesystem for media files, a message queue for asynchronous communication, a rate limiter for request management, and a reverse HTTPS proxy for secure communication. - -More detailed information is described in the following sections. diff --git a/guides/hosting/infrastructure/redis.md b/guides/hosting/infrastructure/redis.md deleted file mode 100644 index e7a088ea5..000000000 --- a/guides/hosting/infrastructure/redis.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -nav: - title: Redis - position: 7 - ---- - -# Redis - -[Redis](https://redis.io/docs/latest/get-started/) is an in-memory data storage, that offers high performance and can be used as a cache, message broker, and database. It is a key-value store that supports various data structures like strings, hashes, lists, sets, and sorted sets. -Especially in high-performance and high-throughput scenarios it can give better results, than relying on a traditional relational database. -Therefore, multiple adapter exists in shopware, to offload some tasks from the DB to Redis. - -However, as the data that is stored in Redis differs and also the access patterns to this data differ, it makes sense to use different Redis instances with different configurations for different tasks. - -The data stored in Redis can be roughly classified into those three categories: - -1. Ephemeral data: This data is not critical and can be easily recreated when lost, e.g., caches. -2. Durable, but "aging" data: This data is important and cannot easily be recreated, but the relevance of the data decreases over time, e.g. sessions. -3. Durable and critical data: This data is important and cannot easily be recreated, e.g. carts, number ranges. - -Please note that in current Redis versions, it is not possible to use different eviction policies for different databases in the same Redis instance. Therefore, it is recommended to use separate Redis instances for different types of data. - -## Ephemeral data - -As ephemeral data can easily be restored and is most often used in cases where high performance matters, this data can be stored with no durable persistence. -This means the data is only stored in memory and is lost when the Redis instance is restarted. - -For key eviction policy you should use `volatile-lru`, which only automatically deletes data that is expired, as the application explicitly manages the TTL for each cache item. - -The caching data (HTTP-Cache & Object cache) is what should be stored in this instance. - - - -## Durable, but "aging" data - -As the data stored here is durable and should be persistent, even in the case of a Redis restart, it is recommended to configure the used Redis instance that it will not just keep the data in memory, but also store it on the disk. This can be done by using snapshots (RDB) and Append Only Files (AOF), refer to the [Redis docs](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) for details. - -`allkeys-lru` should be used as key eviction policy here, as by default more recent data is more important than older data, therefore the oldest values should be discarded, when Redis reach the max memory. - -The session data is what should be stored in this instance. - - - -## Durable and critical data - -Again this is durable data, that can not easily be recreated, therefore it should be persisted as well. - -As the data is critical, it is important to use a key eviction policy that will not delete data that is not expired, therefore `volatile-lru` should be used. - -The cart, number range, lock store and increment data is what should be stored in this instance. - -## Configuration - -Starting with v6.6.8.0 Shopware supports configuring different reusable Redis connections in the`config/packages/shopware.yaml` file under the `shopware` section: - -```yaml -shopware: - # ... - redis: - connections: - ephemeral: - dsn: 'redis://host1:port/dbindex' - persistent: - dsn: 'redis://host2:port/dbindex' -``` - -Connection names should reflect the actual connection purpose/type and be unique. Also, the names are used as part of the service names in the container, so they should follow the service naming conventions. After defining connections, you can reference them by name in the configuration of different subsystems. - -It's possible to use environment variables in the DSN string, e.g. if `REDIS_EPHEMERAL` is set to `redis://host1:port`, the configuration could look like this: - -```yaml -shopware: - # ... - redis: - connections: - ephemeral_1: - dsn: '%env(REDIS_EPHEMERAL)%/1' # using database 1 - ephemeral_2: - dsn: '%env(REDIS_EPHEMERAL)%/2' # using database 2 -``` - -### Connection pooling - -In high-load scenarios, it is recommended to use persistent connections to avoid the overhead of establishing a new connection for each request. This can be achieved by setting the `persistent` flag in DSN to `1`: - -```yaml -shopware: - redis: - connections: - ephemeral: - dsn: 'redis://host:port/dbindex?persistent=1' -``` - -Please note that the persistent flag influences connection pooling, not persistent storage of data. - - - - - - - - - - diff --git a/guides/hosting/installation-updates/cluster-setup.md b/guides/hosting/installation-updates/cluster-setup.md deleted file mode 100644 index 61e2d5a3f..000000000 --- a/guides/hosting/installation-updates/cluster-setup.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -nav: - title: Cluster Setup - position: 10 - ---- - -# Cluster Setup - -The setup of high-scaling systems differs from a normal installation of Shopware. They are completely customized stores with individual templates and extensions. - -This guide contains information for everyone who intends to start with such a project. - -## Shopware configuration - -::: info -This configuration is available starting with Shopware version 6.5.6.0 -::: - -To configure Shopware for a cluster setup, you have to set the following configuration in your shopware.yaml file: - -```yaml -shopware: - deployment: - cluster_setup: true -``` - -This option prevents shopware from running operations locally (meaning only on one node in a cluster), that potentially can corrupt the state of the cluster by having the state of the nodes diverge from each other, e.g. clearing symfony cache files at runtime. - -## Symfony Flex template - -Use the [Symfony Flex template](../../installation/template) and pin the Shopware versions in the `composer.json` file. This prevents unwanted updates when deploying (without a composer.lock). - -## Sources - -The following folders are available in the production template: - -- **/src**: Here, the project-specific bundles and sources can be stored. -- **/config**: Here are the .yaml config files and other possible configurations (routing, admin configs, etc). -- **/config/bundles.php**: In this file, all Symfony bundles are defined, which should be included in the project. - -## Third-party sources - -Most big-scale projects have a development team assigned. It is responsible for the stability and performance of the system. The integration of external sources via apps or plugins can be useful but should always be viewed with a critical eye. By including those sources, the development team relinquishes control over parts of the system. We recommend including necessary plugins as Composer packages instead of user-managed plugins. - -## Redis - -We recommend setting up at least five Redis servers for the following resources: - -1. [Session](../performance/session) + [cart](../infrastructure/database-cluster#cart-in-redis) -2. [cache.object](../performance/caches#example-replace-some-cache-with-redis) -3. [Lock](../performance/lock-store) + [Increment storage](../performance/increment) -4. [Number Ranges](../performance/number-ranges) -5. [Message Queue](../infrastructure/message-queue#transport-redis-example) - Instead of setting up a Redis server for `messenger`, you can also work directly with [RabbitMQ](../infrastructure/message-queue#transport-rabbitmq-example) - -The PHP Redis extension provides persistent Redis connections. Persistent connections can help in high load scenarios as each request doesn't have to open and close connections. Using non-persistent Redis connections can also hit the system's maximum open sockets. Because of these limitations, the Redis extension is preferred over Predis. - -When a Redis cluster is in usage, the `php.ini` setting `redis.clusters.cache_slots=1` should be set to skip the cluster node lookup on each connection. - -## Database cluster - -We have compiled some best practices and configurations to allow you to operate Shopware in a clustered database environment. Please refer to the guide below. - - - -## Filesystem - -In a multi-app-server system, manage specific directories over a shared filesystem. This includes assets, theme files, and private as well as public filesystems. The recommendation is to use an S3 compatible bucket. - -For more information, refer to the [filesystems](../infrastructure/filesystem) section of this guide. - -### Shared directories - -Besides the S3 bucket, it is also necessary to create certain directories for the app servers as shared filesystem. - -## Shopware updates + security - -To update your project, we always recommend using a staging environment. However, updates for a project should only be obtained if there are critical problems with the system or if essential features have been provided by Shopware. -Updates of such systems require a certain amount of effort, as issues often arise during deployments to production systems. - -### Security plugin - -For obtaining security fixes, without version upgrades, we provide a dedicated [Security plugin](https://store.shopware.com/swag136939272659f/shopware-6-sicherheits-plugin.html). This is compatible with all Shopware versions and corresponding hot fixes are only included in versions that are affected. - -### Update of composer dependencies - -To ensure the security of your Shopware installation, it's essential to be vigilant about third-party dependencies that might be affected by security vulnerabilities. In that case, a new Shopware version will be released with updated dependencies. If an update to the latest Shopware version in a timely manner is not possible, it is recommended to update the affected dependency manually. This can be done by using the following command: - -```bash - composer update -``` - -To identify any potential security risk in your current dependencies, it's a good practice to regularly run the [`composer audit`](https://getcomposer.org/doc/03-cli.md#audit) command. This command scans your dependencies and alerts you if there are any known vulnerabilities that need to be addressed. - -### Disable auto-update - -Shopware's integrated auto-update functionality should be disabled to prevent unwanted updates. Also, this feature is not multi-app server compatible and should be controlled via deployment. - -```yaml -shopware: - auto_update: - enabled: false -``` - -## Message queue - -On a productive system, the [message queue](../infrastructure/message-queue) should be processed via CLI processes instead of the [Admin worker](../infrastructure/message-queue#admin-worker). This way, messages are completed regardless of logged-in Administration users and CPU load, as messages can be regulated through the amount of worker processes. Furthermore, you can change the transport to another system like [RabbitMQ](https://www.rabbitmq.com/). - -It is recommended to run multiple `messenger:consume` workers. To automatically start the processes again after they stopped because of exceeding the given limits you can use a process control system like [systemd](https://www.freedesktop.org/wiki/Software/systemd/) or [supervisor](http://supervisord.org/running.html). - -### Own queue - -It is also recommended to define your own message queue in addition to the standard message queue. This gives you more control over the load distribution and allows you to prioritize your own processes higher than the data indexing of Shopware. - -## Monitoring - -Likewise, we recommend setting up an appropriate monitoring dashboard with well-known software such as: - -- [Blackfire](https://www.blackfire.io/) -- [Tideways](https://tideways.com/) -- [Datadog](https://www.datadoghq.com/) -- [Elastic](https://www.elastic.co/) - -## Local machines - -It is important to keep the local development environments of the developers similar to the live environments. A development environment without Redis or Elasticsearch is always too far away from reality and often leads to complications after deployment. Therefore, it is advisable to maintain internal documentation on how to deploy the server structure and how to set up local machines. - -## Theme compiling - -The [theme compilation](deployments/build-w-o-db#compiling-the-storefront-without-database) in Shopware by default depends on the settings in the database. However, since a connection to the database is usually not guaranteed during deployment, we recommend configuring static theme compilation. - -## Strong CPU - -For the server setup, pay special attention to CPU speed. This applies to all servers (app, SQL, Elasticsearch, Redis). Usually, it is more optimal to choose a slightly stronger CPU. This has to be determined more precisely depending on the project and load. Experience has shown that systems with powerful CPUs finish processes faster and can release resources sooner. - -## Health Check - -::: info -This feature is available starting with Shopware version 6.5.5.0 -::: - -Use the Shopware-provided Health Check API (`/api/_info/health-check`) to monitor the health of your Shopware app server. It responds with HTTP status `200` when the Shopware Application is working and `50x` when it is not. -For docker, you can use: `HEALTHCHECK CMD curl --fail http://localhost/api/_info/health-check || exit 1` - -## Performance tweaks - -When setting up big-scale projects, there are some settings and conditions that should be taken into account with regard to performance. - -Read more on [performance tweaks](../performance/performance-tweaks). diff --git a/guides/hosting/installation-updates/deployments/build-w-o-db.md b/guides/hosting/installation-updates/deployments/build-w-o-db.md deleted file mode 100644 index 81ef755fc..000000000 --- a/guides/hosting/installation-updates/deployments/build-w-o-db.md +++ /dev/null @@ -1,1378 +0,0 @@ ---- -nav: - title: Building without Database - position: 20 - ---- - -# Building assets of Administration and Storefront without a Database - -It is common to prebuild assets in professional deployments to deploy the build artifact assets to the production environment. This task is mostly done by a CI job that doesn't have access to the production database. Shopware needs access to the database to look up the installed extensions/load the configured theme variables. To be able to build the assets without a database, we can use static dumped files. All extensions need to be required by Composer to be able to be loaded by the `ComposerPluginLoader`. - -::: warning -This guide requires Shopware 6.4.4.0 or higher. -::: - -## Compiling the Administration without database - -By default, Shopware builds the Administration without extensions if there is no database connection. To include the extensions without a database, you will need to use the `ComposerPluginLoader`. This determines the used plugins by looking up the installed project dependencies. To get this working, the plugin needs to be required in the system using `composer req [package/name]`. - -There is a file `bin/ci` which uses the `ComposerPluginLoader` and can be used instead of `bin/console`. -Using this, you can dump the plugins for the Administration with the new file without a database using the command `bin/ci bundle:dump`. It is recommended to call `bin/ci` instead of `bin/console` in the `bin/*.js` scripts, which can be achieved by setting the environment variable `CI=1`. - -## Compiling the Storefront without database - -To compile the Storefront theme, you will need the theme variables from the database. To allow compiling it without a database, it is possible to dump the variables to the private file system of Shopware. This file system interacts with the local folder `files/theme-config` by default, but for it to be compiled, it should be shared such that settings are shared across deployments. This can be achieved, for example, by using a [storage adapter like s3](../../infrastructure/filesystem). The configuration can be dumped using the command `bin/console theme:dump`, or it happens automatically when changing theme settings or assigning a new theme. - -This means that you still **need a dumped configuration from a system with a working database setup**. You then need to copy these files to your setup without a database and follow the steps below. - -By default, Shopware still tries to load configurations from the database. In the next step, you will need to change the loader to `StaticFileConfigLoader`. To change that, you will need to create a new file, `config/packages/storefront.yaml` with the following content: - - ```yaml -storefront: - theme: - config_loader_id: Shopware\Storefront\Theme\ConfigLoader\StaticFileConfigLoader - available_theme_provider: Shopware\Storefront\Theme\ConfigLoader\StaticFileAvailableThemeProvider - theme_path_builder_id: Shopware\Storefront\Theme\MD5ThemePathBuilder - ``` - -This will force the theme compiler to use the static dumped file instead of looking into the database. - -::: info -Warnings about Database errors can still occur but will be caught and should be ignored in this case. -::: - -The dumped files should be found in the directory `files/theme-config` - -### Example - -directory (files/theme-config): - -```text -a729322c1f4e4b4e851137c807b4f363.json -index.json -``` - -index.json - -```json -{"99ef1e95716d43d7be78e9d9921c7163":"a729322c1f4e4b4e851137c807b4f363"} -``` - -
-a729322c1f4e4b4e851137c807b4f363.json - - - - -```json -{ - "extensions": [], - "themeConfig": { - "fields": { - "sw-color-brand-primary": { - "type": "color", - "value": "#ff0000", - "editable": true, - "block": "themeColors", - "order": 100 - }, - "sw-color-brand-secondary": { - "type": "color", - "value": "#3d444d", - "editable": true, - "block": "themeColors", - "order": 200 - }, - "sw-border-color": { - "type": "color", - "value": "#798490", - "editable": true, - "block": "themeColors", - "order": 300 - }, - "sw-background-color": { - "type": "color", - "value": "#fff", - "editable": true, - "block": "themeColors", - "order": 400 - }, - "sw-color-success": { - "type": "color", - "value": "#3cc261", - "editable": true, - "block": "statusColors", - "order": 100 - }, - "sw-color-info": { - "type": "color", - "value": "#26b6cf", - "editable": true, - "block": "statusColors", - "order": 200 - }, - "sw-color-warning": { - "type": "color", - "value": "#ffbd5d", - "editable": true, - "block": "statusColors", - "order": 300 - }, - "sw-color-danger": { - "type": "color", - "value": "#e52427", - "editable": true, - "block": "statusColors", - "order": 400 - }, - "sw-font-family-base": { - "type": "fontFamily", - "value": "'Inter', sans-serif", - "editable": true, - "block": "typography", - "order": 100 - }, - "sw-text-color": { - "type": "color", - "value": "#2b3136", - "editable": true, - "block": "typography", - "order": 200 - }, - "sw-font-family-headline": { - "type": "fontFamily", - "value": "'Inter', sans-serif", - "editable": true, - "block": "typography", - "order": 300 - }, - "sw-headline-color": { - "type": "color", - "value": "#2b3136", - "editable": true, - "block": "typography", - "order": 400 - }, - "sw-color-price": { - "type": "color", - "value": "#2b3136", - "editable": true, - "block": "eCommerce", - "order": 100 - }, - "sw-color-buy-button": { - "type": "color", - "value": "#0b539b", - "editable": true, - "block": "eCommerce", - "order": 200 - }, - "sw-color-buy-button-text": { - "type": "color", - "value": "#fff", - "editable": true, - "block": "eCommerce", - "order": 300 - }, - "sw-logo-desktop": { - "type": "media", - "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png", - "editable": true, - "block": "media", - "order": 100, - "fullWidth": true - }, - "sw-logo-tablet": { - "type": "media", - "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png", - "editable": true, - "block": "media", - "order": 200, - "fullWidth": true - }, - "sw-logo-mobile": { - "type": "media", - "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png", - "editable": true, - "block": "media", - "order": 300, - "fullWidth": true - }, - "sw-logo-share": { - "type": "media", - "value": "", - "editable": true, - "block": "media", - "order": 400 - }, - "sw-logo-favicon": { - "type": "media", - "value": "http:\/\/shopware.local\/media\/d3\/f5\/b7\/1678462492\/favicon.png", - "editable": true, - "block": "media", - "order": 500 - } - }, - "sw-color-brand-primary": { - "extensions": [], - "name": "sw-color-brand-primary", - "type": "color", - "value": "#0b539b", - "editable": true, - "block": "themeColors", - "section": null, - "tab": null, - "order": 100, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-brand-secondary": { - "extensions": [], - "name": "sw-color-brand-secondary", - "type": "color", - "value": "#3d444d", - "editable": true, - "block": "themeColors", - "section": null, - "tab": null, - "order": 200, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-border-color": { - "extensions": [], - "name": "sw-border-color", - "type": "color", - "value": "#798490", - "editable": true, - "block": "themeColors", - "section": null, - "tab": null, - "order": 300, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-background-color": { - "extensions": [], - "name": "sw-background-color", - "type": "color", - "value": "#fff", - "editable": true, - "block": "themeColors", - "section": null, - "tab": null, - "order": 400, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-success": { - "extensions": [], - "name": "sw-color-success", - "type": "color", - "value": "#3cc261", - "editable": true, - "block": "statusColors", - "section": null, - "tab": null, - "order": 100, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-info": { - "extensions": [], - "name": "sw-color-info", - "type": "color", - "value": "#26b6cf", - "editable": true, - "block": "statusColors", - "section": null, - "tab": null, - "order": 200, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-warning": { - "extensions": [], - "name": "sw-color-warning", - "type": "color", - "value": "#ffbd5d", - "editable": true, - "block": "statusColors", - "section": null, - "tab": null, - "order": 300, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-danger": { - "extensions": [], - "name": "sw-color-danger", - "type": "color", - "value": "#e52427", - "editable": true, - "block": "statusColors", - "section": null, - "tab": null, - "order": 400, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-font-family-base": { - "extensions": [], - "name": "sw-font-family-base", - "type": "fontFamily", - "value": "'Inter', sans-serif", - "editable": true, - "block": "typography", - "section": null, - "tab": null, - "order": 100, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-text-color": { - "extensions": [], - "name": "sw-text-color", - "type": "color", - "value": "#2b3136", - "editable": true, - "block": "typography", - "section": null, - "tab": null, - "order": 200, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-font-family-headline": { - "extensions": [], - "name": "sw-font-family-headline", - "type": "fontFamily", - "value": "'Inter', sans-serif", - "editable": true, - "block": "typography", - "section": null, - "tab": null, - "order": 300, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-headline-color": { - "extensions": [], - "name": "sw-headline-color", - "type": "color", - "value": "#2b3136", - "editable": true, - "block": "typography", - "section": null, - "tab": null, - "order": 400, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-price": { - "extensions": [], - "name": "sw-color-price", - "type": "color", - "value": "#2b3136", - "editable": true, - "block": "eCommerce", - "section": null, - "tab": null, - "order": 100, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-buy-button": { - "extensions": [], - "name": "sw-color-buy-button", - "type": "color", - "value": "#0b539b", - "editable": true, - "block": "eCommerce", - "section": null, - "tab": null, - "order": 200, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-buy-button-text": { - "extensions": [], - "name": "sw-color-buy-button-text", - "type": "color", - "value": "#fff", - "editable": true, - "block": "eCommerce", - "section": null, - "tab": null, - "order": 300, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-logo-desktop": { - "extensions": [], - "name": "sw-logo-desktop", - "type": "media", - "value": "18f45736ef6a4beea22d867573bd1af6", - "editable": true, - "block": "media", - "section": null, - "tab": null, - "order": 100, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": true - }, - "sw-logo-tablet": { - "extensions": [], - "name": "sw-logo-tablet", - "type": "media", - "value": "18f45736ef6a4beea22d867573bd1af6", - "editable": true, - "block": "media", - "section": null, - "tab": null, - "order": 200, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": true - }, - "sw-logo-mobile": { - "extensions": [], - "name": "sw-logo-mobile", - "type": "media", - "value": "18f45736ef6a4beea22d867573bd1af6", - "editable": true, - "block": "media", - "section": null, - "tab": null, - "order": 300, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": true - }, - "sw-logo-share": { - "extensions": [], - "name": "sw-logo-share", - "type": "media", - "value": "", - "editable": true, - "block": "media", - "section": null, - "tab": null, - "order": 400, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-logo-favicon": { - "extensions": [], - "name": "sw-logo-favicon", - "type": "media", - "value": "7bf586ac4343480292ebd5f349e16607", - "editable": true, - "block": "media", - "section": null, - "tab": null, - "order": 500, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - } - }, - "name": "Swag Dev Theme", - "previewMedia": "custom\/apps\/SwagDevTheme\/Resources\/app\/storefront\/src\/assets\/images\/showroomPreview.png", - "author": "Shopware AG", - "isTheme": true, - "styleFiles": [ - { - "extensions": [], - "filepath": "@Storefront", - "resolveMapping": [] - } - ], - "scriptFiles": [ - { - "extensions": [], - "filepath": "@Storefront", - "resolveMapping": [] - } - ], - "storefrontEntryFilepath": null, - "basePath": "custom\/apps\/SwagDevTheme\/Resources", - "assetPaths": [ - "custom\/apps\/SwagDevTheme\/Resources\/app\/storefront\/src\/assets" - ], - "viewInheritance": [ - "@Storefront", - "@SwagCustomizedProducts", - "@SwagPayPal", - "@SwagAmazonPay", - "@SwagCmsExtensions", - "@SwagB2bPlatform", - "@SwagDevTheme", - "@Plugins" - ], - "iconSets": { - "showroom": "app\/storefront\/src\/assets\/icon\/showroom" - }, - "technicalName": "SwagDevTheme" -} -``` - - - - - -```json -{ - "extensions": [], - "themeConfig": { - "blocks": { - "themeColors": { - "label": { - "en-GB": "Theme colours", - "de-DE": "Theme-Farben" - } - }, - "typography": { - "label": { - "en-GB": "Typography", - "de-DE": "Typografie" - } - }, - "eCommerce": { - "label": { - "en-GB": "E-Commerce", - "de-DE": "E-Commerce" - } - }, - "statusColors": { - "label": { - "en-GB": "Status messages", - "de-DE": "Status-Ausgaben" - } - }, - "media": { - "label": { - "en-GB": "Media", - "de-DE": "Medien" - } - }, - "unordered": { - "label": { - "en-GB": "Misc", - "de-DE": "Sonstige" - } - } - }, - "fields": { - "sw-color-brand-primary": { - "label": { - "en-GB": "Primary colour", - "de-DE": "Prim\u00e4rfarbe" - }, - "type": "color", - "value": "#ff0000", - "editable": true, - "block": "themeColors", - "order": 100 - }, - "sw-color-brand-secondary": { - "label": { - "en-GB": "Secondary colour", - "de-DE": "Sekund\u00e4rfarbe" - }, - "type": "color", - "value": "#3d444d", - "editable": true, - "block": "themeColors", - "order": 200 - }, - "sw-border-color": { - "label": { - "en-GB": "Border", - "de-DE": "Rahmen" - }, - "type": "color", - "value": "#798490", - "editable": true, - "block": "themeColors", - "order": 300 - }, - "sw-background-color": { - "label": { - "en-GB": "Background", - "de-DE": "Hintergrund" - }, - "type": "color", - "value": "#fff", - "editable": true, - "block": "themeColors", - "order": 400 - }, - "sw-color-success": { - "label": { - "en-GB": "Success", - "de-DE": "Erfolg" - }, - "type": "color", - "value": "#3cc261", - "editable": true, - "block": "statusColors", - "order": 100 - }, - "sw-color-info": { - "label": { - "en-GB": "Information", - "de-DE": "Information" - }, - "type": "color", - "value": "#26b6cf", - "editable": true, - "block": "statusColors", - "order": 200 - }, - "sw-color-warning": { - "label": { - "en-GB": "Notice", - "de-DE": "Hinweis" - }, - "type": "color", - "value": "#ffbd5d", - "editable": true, - "block": "statusColors", - "order": 300 - }, - "sw-color-danger": { - "label": { - "en-GB": "Error", - "de-DE": "Fehler" - }, - "type": "color", - "value": "#e52427", - "editable": true, - "block": "statusColors", - "order": 400 - }, - "sw-font-family-base": { - "label": { - "en-GB": "Fonttype text", - "de-DE": "Schriftart Text" - }, - "type": "fontFamily", - "value": "'Inter', sans-serif", - "editable": true, - "block": "typography", - "order": 100 - }, - "sw-text-color": { - "label": { - "en-GB": "Text colour", - "de-DE": "Textfarbe" - }, - "type": "color", - "value": "#2b3136", - "editable": true, - "block": "typography", - "order": 200 - }, - "sw-font-family-headline": { - "label": { - "en-GB": "Fonttype headline", - "de-DE": "Schriftart \u00dcberschrift" - }, - "type": "fontFamily", - "value": "'Inter', sans-serif", - "editable": true, - "block": "typography", - "order": 300 - }, - "sw-headline-color": { - "label": { - "en-GB": "Headline colour", - "de-DE": "\u00dcberschriftfarbe" - }, - "type": "color", - "value": "#2b3136", - "editable": true, - "block": "typography", - "order": 400 - }, - "sw-color-price": { - "label": { - "en-GB": "Price", - "de-DE": "Preis" - }, - "type": "color", - "value": "#2b3136", - "editable": true, - "block": "eCommerce", - "order": 100 - }, - "sw-color-buy-button": { - "label": { - "en-GB": "Buy button", - "de-DE": "Kaufen-Button" - }, - "type": "color", - "value": "#0b539b", - "editable": true, - "block": "eCommerce", - "order": 200 - }, - "sw-color-buy-button-text": { - "label": { - "en-GB": "Buy button text", - "de-DE": "Kaufen-Button Text" - }, - "type": "color", - "value": "#fff", - "editable": true, - "block": "eCommerce", - "order": 300 - }, - "sw-logo-desktop": { - "label": { - "en-GB": "Desktop", - "de-DE": "Desktop" - }, - "helpText": { - "en-GB": "Displayed on viewport sizes above 991px and as a fallback on smaller viewports, if no other logo is set.", - "de-DE": "Wird bei Ansichten \u00fcber 991px angezeigt und als Alternative bei kleineren Aufl\u00f6sungen, f\u00fcr die kein anderes Logo eingestellt ist." - }, - "type": "media", - "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png", - "editable": true, - "block": "media", - "order": 100, - "fullWidth": true - }, - "sw-logo-tablet": { - "label": { - "en-GB": "Tablet", - "de-DE": "Tablet" - }, - "helpText": { - "en-GB": "Displayed between a viewport of 767px to 991px", - "de-DE": "Wird zwischen einem viewport von 767px bis 991px angezeigt" - }, - "type": "media", - "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png", - "editable": true, - "block": "media", - "order": 200, - "fullWidth": true - }, - "sw-logo-mobile": { - "label": { - "en-GB": "Mobile", - "de-DE": "Mobil" - }, - "helpText": { - "en-GB": "Displayed up to a viewport of 767px", - "de-DE": "Wird bis zu einem Viewport von 767px angezeigt" - }, - "type": "media", - "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png", - "editable": true, - "block": "media", - "order": 300, - "fullWidth": true - }, - "sw-logo-share": { - "label": { - "en-GB": "App & share icon", - "de-DE": "App- & Share-Icon" - }, - "type": "media", - "value": "", - "editable": true, - "block": "media", - "order": 400 - }, - "sw-logo-favicon": { - "label": { - "en-GB": "Favicon", - "de-DE": "Favicon" - }, - "type": "media", - "value": "http:\/\/shopware.local\/media\/d3\/f5\/b7\/1678462492\/favicon.png", - "editable": true, - "block": "media", - "order": 500 - } - }, - "sw-color-brand-primary": { - "extensions": [], - "name": "sw-color-brand-primary", - "label": { - "en-GB": "Primary colour", - "de-DE": "Prim\u00e4rfarbe" - }, - "helpText": null, - "type": "color", - "value": "#0b539b", - "editable": true, - "block": "themeColors", - "section": null, - "tab": null, - "order": 100, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-brand-secondary": { - "extensions": [], - "name": "sw-color-brand-secondary", - "label": { - "en-GB": "Secondary colour", - "de-DE": "Sekund\u00e4rfarbe" - }, - "helpText": null, - "type": "color", - "value": "#3d444d", - "editable": true, - "block": "themeColors", - "section": null, - "tab": null, - "order": 200, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-border-color": { - "extensions": [], - "name": "sw-border-color", - "label": { - "en-GB": "Border", - "de-DE": "Rahmen" - }, - "helpText": null, - "type": "color", - "value": "#798490", - "editable": true, - "block": "themeColors", - "section": null, - "tab": null, - "order": 300, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-background-color": { - "extensions": [], - "name": "sw-background-color", - "label": { - "en-GB": "Background", - "de-DE": "Hintergrund" - }, - "helpText": null, - "type": "color", - "value": "#fff", - "editable": true, - "block": "themeColors", - "section": null, - "tab": null, - "order": 400, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-success": { - "extensions": [], - "name": "sw-color-success", - "label": { - "en-GB": "Success", - "de-DE": "Erfolg" - }, - "helpText": null, - "type": "color", - "value": "#3cc261", - "editable": true, - "block": "statusColors", - "section": null, - "tab": null, - "order": 100, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-info": { - "extensions": [], - "name": "sw-color-info", - "label": { - "en-GB": "Information", - "de-DE": "Information" - }, - "helpText": null, - "type": "color", - "value": "#26b6cf", - "editable": true, - "block": "statusColors", - "section": null, - "tab": null, - "order": 200, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-warning": { - "extensions": [], - "name": "sw-color-warning", - "label": { - "en-GB": "Notice", - "de-DE": "Hinweis" - }, - "helpText": null, - "type": "color", - "value": "#ffbd5d", - "editable": true, - "block": "statusColors", - "section": null, - "tab": null, - "order": 300, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-danger": { - "extensions": [], - "name": "sw-color-danger", - "label": { - "en-GB": "Error", - "de-DE": "Fehler" - }, - "helpText": null, - "type": "color", - "value": "#e52427", - "editable": true, - "block": "statusColors", - "section": null, - "tab": null, - "order": 400, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-font-family-base": { - "extensions": [], - "name": "sw-font-family-base", - "label": { - "en-GB": "Fonttype text", - "de-DE": "Schriftart Text" - }, - "helpText": null, - "type": "fontFamily", - "value": "'Inter', sans-serif", - "editable": true, - "block": "typography", - "section": null, - "tab": null, - "order": 100, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-text-color": { - "extensions": [], - "name": "sw-text-color", - "label": { - "en-GB": "Text colour", - "de-DE": "Textfarbe" - }, - "helpText": null, - "type": "color", - "value": "#2b3136", - "editable": true, - "block": "typography", - "section": null, - "tab": null, - "order": 200, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-font-family-headline": { - "extensions": [], - "name": "sw-font-family-headline", - "label": { - "en-GB": "Fonttype headline", - "de-DE": "Schriftart \u00dcberschrift" - }, - "helpText": null, - "type": "fontFamily", - "value": "'Inter', sans-serif", - "editable": true, - "block": "typography", - "section": null, - "tab": null, - "order": 300, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-headline-color": { - "extensions": [], - "name": "sw-headline-color", - "label": { - "en-GB": "Headline colour", - "de-DE": "\u00dcberschriftfarbe" - }, - "helpText": null, - "type": "color", - "value": "#2b3136", - "editable": true, - "block": "typography", - "section": null, - "tab": null, - "order": 400, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-price": { - "extensions": [], - "name": "sw-color-price", - "label": { - "en-GB": "Price", - "de-DE": "Preis" - }, - "helpText": null, - "type": "color", - "value": "#2b3136", - "editable": true, - "block": "eCommerce", - "section": null, - "tab": null, - "order": 100, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-buy-button": { - "extensions": [], - "name": "sw-color-buy-button", - "label": { - "en-GB": "Buy button", - "de-DE": "Kaufen-Button" - }, - "helpText": null, - "type": "color", - "value": "#0b539b", - "editable": true, - "block": "eCommerce", - "section": null, - "tab": null, - "order": 200, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-color-buy-button-text": { - "extensions": [], - "name": "sw-color-buy-button-text", - "label": { - "en-GB": "Buy button text", - "de-DE": "Kaufen-Button Text" - }, - "helpText": null, - "type": "color", - "value": "#fff", - "editable": true, - "block": "eCommerce", - "section": null, - "tab": null, - "order": 300, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-logo-desktop": { - "extensions": [], - "name": "sw-logo-desktop", - "label": { - "en-GB": "Desktop", - "de-DE": "Desktop" - }, - "helpText": { - "en-GB": "Displayed on viewport sizes above 991px and as a fallback on smaller viewports, if no other logo is set.", - "de-DE": "Wird bei Ansichten \u00fcber 991px angezeigt und als Alternative bei kleineren Aufl\u00f6sungen, f\u00fcr die kein anderes Logo eingestellt ist." - }, - "type": "media", - "value": "18f45736ef6a4beea22d867573bd1af6", - "editable": true, - "block": "media", - "section": null, - "tab": null, - "order": 100, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": true - }, - "sw-logo-tablet": { - "extensions": [], - "name": "sw-logo-tablet", - "label": { - "en-GB": "Tablet", - "de-DE": "Tablet" - }, - "helpText": { - "en-GB": "Displayed between a viewport of 767px to 991px", - "de-DE": "Wird zwischen einem viewport von 767px bis 991px angezeigt" - }, - "type": "media", - "value": "18f45736ef6a4beea22d867573bd1af6", - "editable": true, - "block": "media", - "section": null, - "tab": null, - "order": 200, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": true - }, - "sw-logo-mobile": { - "extensions": [], - "name": "sw-logo-mobile", - "label": { - "en-GB": "Mobile", - "de-DE": "Mobil" - }, - "helpText": { - "en-GB": "Displayed up to a viewport of 767px", - "de-DE": "Wird bis zu einem Viewport von 767px angezeigt" - }, - "type": "media", - "value": "18f45736ef6a4beea22d867573bd1af6", - "editable": true, - "block": "media", - "section": null, - "tab": null, - "order": 300, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": true - }, - "sw-logo-share": { - "extensions": [], - "name": "sw-logo-share", - "label": { - "en-GB": "App & share icon", - "de-DE": "App- & Share-Icon" - }, - "helpText": null, - "type": "media", - "value": "", - "editable": true, - "block": "media", - "section": null, - "tab": null, - "order": 400, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - }, - "sw-logo-favicon": { - "extensions": [], - "name": "sw-logo-favicon", - "label": { - "en-GB": "Favicon", - "de-DE": "Favicon" - }, - "helpText": null, - "type": "media", - "value": "7bf586ac4343480292ebd5f349e16607", - "editable": true, - "block": "media", - "section": null, - "tab": null, - "order": 500, - "sectionOrder": null, - "blockOrder": null, - "tabOrder": null, - "custom": null, - "scss": null, - "fullWidth": null - } - }, - "name": "Swag Dev Theme", - "previewMedia": "custom\/apps\/SwagDevTheme\/Resources\/app\/storefront\/src\/assets\/images\/showroomPreview.png", - "author": "Shopware AG", - "isTheme": true, - "styleFiles": [ - { - "extensions": [], - "filepath": "@Storefront", - "resolveMapping": [] - } - ], - "scriptFiles": [ - { - "extensions": [], - "filepath": "@Storefront", - "resolveMapping": [] - } - ], - "storefrontEntryFilepath": null, - "basePath": "custom\/apps\/SwagDevTheme\/Resources", - "assetPaths": [ - "custom\/apps\/SwagDevTheme\/Resources\/app\/storefront\/src\/assets" - ], - "viewInheritance": [ - "@Storefront", - "@SwagCustomizedProducts", - "@SwagPayPal", - "@SwagAmazonPay", - "@SwagCmsExtensions", - "@SwagB2bPlatform", - "@SwagDevTheme", - "@Plugins" - ], - "iconSets": { - "showroom": "app\/storefront\/src\/assets\/icon\/showroom" - }, - "technicalName": "SwagDevTheme" -} -``` - - - - -
- -### Partially compiling the Storefront - -You can also build just the Javascript bundle using `CI=1 SHOPWARE_SKIP_THEME_COMPILE=true PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true bin/build-storefront.sh` (without the need for the above loader) in your CI. After that, run `bin/console theme:dump` on your production system when the database is available. This will happen automatically if theme variables are changed via the admin panel. diff --git a/guides/hosting/installation-updates/index.md b/guides/hosting/installation-updates/index.md deleted file mode 100644 index 873315fea..000000000 --- a/guides/hosting/installation-updates/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -nav: - title: Installation & Updates - position: 10 - ---- - -# Installation and Updates - -This section will brief you on cluster setup for custom stores, Shopware 6 production template, and deployment to an infrastructure. diff --git a/guides/hosting/performance/index.md b/guides/hosting/performance/index.md deleted file mode 100644 index 6c5701549..000000000 --- a/guides/hosting/performance/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -nav: - title: Performance - position: 30 - ---- - -# Performance - -By fine-tuning cache usage, optimizing session and storage management, and employing efficient locking mechanisms, you can significantly improve the overall performance of your online store. Optimizing hosting performance involves considering these factors and implementing appropriate strategies to enhance the speed, scalability, and reliability of your Shopware store. diff --git a/guides/hosting/performance/lock-store.md b/guides/hosting/performance/lock-store.md deleted file mode 100644 index 75f45e880..000000000 --- a/guides/hosting/performance/lock-store.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -nav: - title: Lock Storage - position: 50 - ---- - -# Lock store - -Shopware uses [Symfony's lock component](https://symfony.com/doc/5.4/lock.html) to implement locking functionality. -By default, Symfony will use a local lock store. This means in multi-machine (cluster) setups, naive file locks will break the system; therefore, it is highly recommended to use one of the [supported remote stores](https://symfony.com/doc/5.4/components/lock.html#available-stores). - -## Using Redis as a lock store - -As Redis can already be used for [caching](./caches), [increment store](./increment), and [session storage](./session), you can also use that Redis host as a remote lock store. -To use Redis, first you need to create a named redis connection as described in the [Redis configuration guide](../infrastructure/redis#configuration). -Then, you can configure the lock store to use that connection. Create a `config/packages/lock.yaml` file with the following content: - -```yaml -framework: - lock: 'shopware.redis.connection.connection_name' -``` - -Alternatively, you can use the DSN directly in the configuration file, but this is not recommended as it does not allow connection reuse and not prefixing locks keys with the value of the `REDIS_PREFIX` environment variable. - -```yaml -framework: - lock: 'redis://host:port' -``` - -## Other lock stores - -As Shopware uses [Symfony's lock component](https://symfony.com/doc/5.4/lock.html), all lock stores supported by Symfony can be used. -Keep in mind that you should always use a remote store if you host Shopware in a cluster setup. -For a list of all available lock stores, refer to [Symfony's documentation](https://symfony.com/doc/5.4/components/lock.html#available-stores). -There is also more detailed information on the [configuration options](https://symfony.com/doc/5.4/lock.html#configuring-lock-with-frameworkbundle). diff --git a/guides/hosting/performance/session.md b/guides/hosting/performance/session.md deleted file mode 100644 index 421083fc8..000000000 --- a/guides/hosting/performance/session.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -nav: - title: Session - position: 30 - ---- - -# Shopware Session - -Shopware, by default, uses the session storage configured in PHP. On most installations, this is the file system. In smaller setups, you will not need to take care of sessions. However, for larger setups using clustering or with a lot of traffic, you will probably configure alternative session storage, such as Redis, to reduce the load on the database. - -## Session adapters - -### Configure Redis using PHP.ini - -By default, Shopware uses the settings configured in PHP. You can reconfigure the Session config directly in your `php.ini`. Here is an example of configuring it directly in PHP. - -```ini -session.save_handler = redis -session.save_path = "tcp://host:6379?database=0" -``` - -Please refer to the official [PhpRedis documentation](https://github.com/phpredis/phpredis#php-session-handler) for all possible options. - -### Configure Redis using Shopware configuration - -If you don't have access to the php.ini configuration, you can configure it directly in Shopware itself. For this, create a `config/packages/redis.yml` file with the following content: - -```yaml -# config/packages/redis.yml -framework: - session: - handler_id: "redis://host:port/0" -``` - -### Redis configuration - -As the information stored here is durable and should be persistent, even in the case of a Redis restart, it is recommended to configure the used Redis instance that it will not just keep the data in memory, but also store it on the disk. This can be done by using snapshots (RDB) and Append Only Files (AOF), refer to the [Redis docs](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) for details. - -As key eviction policy you should use `allkeys-lru`, which only automatically deletes the last recently used entries when Redis reaches max memory consumption. For a detailed overview of Redis key eviction policies see the [Redis docs](https://redis.io/docs/latest/develop/reference/eviction/). - -### Other adapters - -Symfony also provides PHP implementations of some adapters: - -- [PdoSessionHandler](https://github.com/symfony/symfony/blob/6.3/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/PdoSessionHandler.php) -- [MemcachedSessionHandler](https://github.com/symfony/symfony/blob/6.3/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/MemcachedSessionHandler.php) -- [MongoDbSessionHandler](https://github.com/symfony/symfony/blob/6.3/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/MongoDbSessionHandler.php) - -To use one of these handlers, you must create a new service in the dependency injection and set the `handler_id` to the service id. - -Example service definition: - -```xml - - - -``` - -Example session configuration: - -```yaml -# config/packages/redis.yml -framework: - session: - handler_id: "session.db" -``` diff --git a/guides/hosting/performance/caches.md b/guides/installation/configurations/caches.md similarity index 100% rename from guides/hosting/performance/caches.md rename to guides/installation/configurations/caches.md diff --git a/guides/hosting/performance/cart-storage.md b/guides/installation/configurations/cart-storage.md similarity index 100% rename from guides/hosting/performance/cart-storage.md rename to guides/installation/configurations/cart-storage.md diff --git a/guides/hosting/infrastructure/database-cluster.md b/guides/installation/configurations/database-cluster.md similarity index 100% rename from guides/hosting/infrastructure/database-cluster.md rename to guides/installation/configurations/database-cluster.md diff --git a/guides/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md b/guides/installation/configurations/elasticsearch/elasticsearch-debugging.md similarity index 100% rename from guides/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md rename to guides/installation/configurations/elasticsearch/elasticsearch-debugging.md diff --git a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md b/guides/installation/configurations/elasticsearch/elasticsearch-setup.md similarity index 100% rename from guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md rename to guides/installation/configurations/elasticsearch/elasticsearch-setup.md diff --git a/guides/hosting/infrastructure/elasticsearch/index.md b/guides/installation/configurations/elasticsearch/index.md similarity index 100% rename from guides/hosting/infrastructure/elasticsearch/index.md rename to guides/installation/configurations/elasticsearch/index.md diff --git a/guides/hosting/configurations/shopware/environment-variables.md b/guides/installation/configurations/environment-variables.md similarity index 99% rename from guides/hosting/configurations/shopware/environment-variables.md rename to guides/installation/configurations/environment-variables.md index 116baf5ca..b9ae4abd0 100644 --- a/guides/hosting/configurations/shopware/environment-variables.md +++ b/guides/installation/configurations/environment-variables.md @@ -1,7 +1,7 @@ --- nav: title: Environment Variables - position: 50 + position: -5000 --- diff --git a/guides/hosting/infrastructure/reverse-http-cache.md b/guides/installation/configurations/external-http-cache.md similarity index 80% rename from guides/hosting/infrastructure/reverse-http-cache.md rename to guides/installation/configurations/external-http-cache.md index cbf7831b8..824e79361 100644 --- a/guides/hosting/infrastructure/reverse-http-cache.md +++ b/guides/installation/configurations/external-http-cache.md @@ -1,32 +1,31 @@ --- nav: - title: Reverse HTTP Cache + title: External HTTP Cache position: 40 --- -# Reverse HTTP Cache +# External HTTP Cache ## Overview -A reverse HTTP cache is a cache server placed before the web shop. +An external HTTP cache is a cache server placed before the web shop. If you are not familiar with HTTP caching, please refer to the [HTTP cache](../../../concepts/framework/http_cache) concept. -The reverse http cache needs the following capabilities to function fully with Shopware: +The external HTTP cache needs the following capabilities to function fully with Shopware: * Able to differentiate the request with multiple cookies -* Allow clearing the cache using a web request for a specific site or with `/` for all pages +* Allow tagging the cache items with surrogate keys +* Allow invalidating the cache items by surrogate keys ::: info In this guide, we will use Varnish as an example for HTTP cache. ::: -### The example Setup with Varnish +## Varnish -::: warning -This setup is compatible with Shopware version 6.4 and higher -::: +### The example Setup with Varnish -![Http cache](../../../assets/hosting-infrastructure-reverseHttpCache.svg) +![Http cache](../../../../assets/hosting-infrastructure-reverseHttpCache.svg) ### Shopware Varnish Docker image @@ -35,14 +34,6 @@ It contains the Shopware default VCL (Varnish Configuration Language). The conta ### Configure Shopware -:::warning -From version v6.6.x onwards, this method is deprecated and will be removed in v6.7.0. -Utilising Varnish with Redis involves LUA scripts to determine URLs for the BAN request. -This can cause problems depending on the setup or network. -Furthermore, Redis clusters are not supported. -Therefore, it is advisable to opt for the [Varnish with `XKey`](#configure-varnish) integration instead. -::: - First, we need to activate the reverse proxy support in Shopware. To enable it, we need to create a new file in `config/packages/storefront.yaml`: @@ -62,19 +53,9 @@ shopware: Also set `SHOPWARE_HTTP_CACHE_ENABLED=1` in your `.env` file. -::: info -The configuration key changed from `storefront.reverse_proxy` up to Shopware 6.5.x to `shopware.http_cache.reverse_proxy` starting with Shopware 6.6.0.0. -So you will need to adjust your config while upgrading. -If you look for the old documentation and examples, you can find it [here](https://developer.shopware.com/docs/v6.5/guides/hosting/infrastructure/reverse-http-cache.html) -::: #### Trusted proxies -::: info -Since Shopware 6.6, the `TRUSTED_PROXIES` environment variable is no longer taken into account out of the box. -Make sure to create a Symfony configuration to make it configurable again, as shown in the [trusted_env.yaml example](https://github.com/shopware/recipes/blob/main/shopware/docker/0.1/config/packages/trusted_env.yaml). -::: - For the most part, using Symfony and Varnish doesn't cause any problem. But, when a request passes through a proxy, certain request information is sent using either the *standard Forwarded* header or *X-Forwarded* headers. For example, instead of reading the `REMOTE_ADDR` header (which will now be the IP address of your reverse proxy), the user's true IP will be stored in a standard Forwarded: for="..." header or an *X-Forwarded-For* header. @@ -84,12 +65,6 @@ Whether or not the client connects via HTTPS, the client's port and the hostname Go through [Proxies](https://symfony.com/doc/current/deployment/proxies.html) section for more information. -### Varnish Docker Image - -Shopware offers a Varnish Docker image that is pre-configured to work with Shopware. -Find the [image](https://github.com/shopware/varnish-shopware) here. -The image is based on the official Varnish image and contains the Shopware default VCL with few configurations as environment variables. - ### Configure Varnish Varnish `XKey` is a cache key module that allows you to use Varnish with surrogate keys. @@ -154,7 +129,7 @@ If you don't see the `Cache-Control: public` header or the `Xkey` header, you ne For more details, please refer to the [Varnish documentation](https://www.varnish-software.com/developers/tutorials/logging-cache-hits-misses-varnish/) on logging cache hits and misses. -## Configure Fastly +## Fastly Fastly is supported since Shopware 6.4.11.0 is out-of-the-box with some configurations. To enable it, we need to create a new file in `config/packages/storefront.yaml` @@ -214,7 +189,7 @@ For manual deployment, you can find the VCL Snippets here: -### Cache Invalidations +## Cache Invalidations The Reverse Proxy Cache shares the same invalidation mechanism as the Object Cache and has the same tags. So, when a product is invalidated, the object cache and the HTTP cache will also be invalidated. diff --git a/guides/hosting/infrastructure/filesystem.md b/guides/installation/configurations/filesystem.md similarity index 100% rename from guides/hosting/infrastructure/filesystem.md rename to guides/installation/configurations/filesystem.md diff --git a/guides/hosting/performance/increment.md b/guides/installation/configurations/increment.md similarity index 100% rename from guides/hosting/performance/increment.md rename to guides/installation/configurations/increment.md diff --git a/guides/hosting/configurations/index.md b/guides/installation/configurations/index.md similarity index 100% rename from guides/hosting/configurations/index.md rename to guides/installation/configurations/index.md diff --git a/guides/hosting/infrastructure/message-queue.md b/guides/installation/configurations/message-queue.md similarity index 70% rename from guides/hosting/infrastructure/message-queue.md rename to guides/installation/configurations/message-queue.md index febc5d06a..f3477dc3f 100644 --- a/guides/hosting/infrastructure/message-queue.md +++ b/guides/installation/configurations/message-queue.md @@ -29,12 +29,12 @@ It is recommended to use a third-party message queue to support multiple consume ## Execution methods -### CLI worker - ::: info -The CLI worker is the recommended way to consume messages. +The Admin Worker is enabled by default, but it's recommended to disable it and use the CLI worker in production systems. ::: +### CLI worker + You can configure the command just to run a certain amount of time and to stop if it exceeds a certain memory limit like: ```bash @@ -62,56 +62,6 @@ shopware: enable_admin_worker: false ``` -::: warning -Make sure to set up the CLI worker also for the failed queue. Otherwise, failed messages will not be processed. -::: - -#### systemd example - -We assume the services to be called `shopware_consumer`. - -Create a new file `/etc/systemd/system/shopware_consumer@.service` - -```bash -[Unit] -Description=Shopware Message Queue Consumer, instance %i -PartOf=shopware_consumer.target - -[Service] -Type=simple -User=www-data # Change this to webserver's user name -Restart=always -# Change the path to your shop path -WorkingDirectory=/var/www/html -ExecStart=php /var/www/html/bin/console messenger:consume --time-limit=60 --memory-limit=512M async low_priority - -[Install] -WantedBy=shopware_consumer.target -``` - -Create a new file `/etc/systemd/system/shopware_consumer.target` - -```bash -[Install] -WantedBy=multi-user.target - -[Unit] -Description=shopware_consumer service -``` - -Enable multiple instances. Example for three instances: -`systemctl enable shopware_consumer@{1..3}.service` - -Enable the dummy target: -`systemctl enable shopware_consumer.target` - -At the end start the services: -`systemctl start shopware_consumer.target` - -#### supervisord example - -Please refer to the [Symfony documentation](https://symfony.com/doc/current/messenger.html#supervisor-configuration) for the setup. - ### Admin worker The admin worker, if used, can be configured in the general `shopware.yml` configuration. If you want to use the admin worker, you have to specify each transport that was previously configured. The poll interval is the time in seconds that the admin worker polls messages from the queue. After the poll interval is over, the request terminates, and the Administration initiates a new request. @@ -122,7 +72,6 @@ shopware: admin_worker: enable_admin_worker: true poll_interval: 30 - transports: ["async", "low_priority"] ``` ## Sending mails over the message queue @@ -161,42 +110,6 @@ Sometimes, it also makes sense to route messages to a different transport to lim ## Configuration -### Message bus - -The message bus is used to dispatch your messages to your registered handlers. While dispatching your message, it loops through the configured middleware for that bus. The message bus used inside Shopware can be found under the service tag `messenger.bus.default`. It is mandatory to use this message bus if your messages should be handled inside Shopware. However, if you want to send messages to external systems, you can define your custom message bus for that. - -You can configure an array of buses and define one default bus in your `framework.yaml`. - -```yaml -// /src/Core/Framework/Resources/config/packages/framework.yaml -framework: - messenger: - default_bus: my.messenger.bus - buses: - my.messenger.bus: -``` - -For more information on this check the [Symfony docs](https://symfony.com/doc/current/messenger/multiple_buses.html). - -### Transport - -A [transport](https://symfony.com/doc/current/messenger.html#transports-async-queued-messages) is responsible for communicating with your 3rd party message broker. You can configure multiple transports and route messages to multiple or different transports. Supported are all transports that are either supported by [Symfony](https://symfony.com/doc/current/messenger.html#transport-configuration) itself. If you don't configure a transport, messages will be processed synchronously like in the Symfony event system. - -You can configure an amqp transport directly in your `framework.yaml` and simply tell Symfony to use your transports. - -In a simple setup you only need to set the transport to a valid DSN like: - -```yaml -// /src/Core/Framework/Resources/config/packages/queue.yaml -framework: - messenger: - transports: - my_transport: - dsn: "%env(MESSENGER_TRANSPORT_DSN)%" -``` - -For more information on this check the [symfony docs](https://symfony.com/doc/current/messenger.html#transport-configuration). - ### Routing You can route messages to different transports. For that, just configure your routing in the `framework.yaml`. @@ -229,7 +142,3 @@ shopware: The `shopware.messenger.routing_overwrite` config option accepts the same format as the `framework.messenger.routing` option, but it will overwrite the routing for the given message class instead of adding to it. This is especially useful if there is a default routing already configured based on a message interface, but you need to change the routing for a specific message. - -::: info -This configuration option was added in Shopware 6.6.4.0 and 6.5.12.0. -::: diff --git a/guides/hosting/performance/number-ranges.md b/guides/installation/configurations/number-ranges.md similarity index 100% rename from guides/hosting/performance/number-ranges.md rename to guides/installation/configurations/number-ranges.md diff --git a/guides/hosting/infrastructure/rate-limiter.md b/guides/installation/configurations/rate-limiter.md similarity index 96% rename from guides/hosting/infrastructure/rate-limiter.md rename to guides/installation/configurations/rate-limiter.md index d0c17b6cd..966e8a0ee 100644 --- a/guides/hosting/infrastructure/rate-limiter.md +++ b/guides/installation/configurations/rate-limiter.md @@ -7,10 +7,6 @@ nav: # Rate Limiter -::: info -This functionality is available starting with Shopware 6.4.6.0. -::: - ## Overview Shopware 6 provides certain rate limits by default that reduces the risk of brute-force attacks for pages like login or password reset. diff --git a/guides/installation/deployments/cluster-setup.md b/guides/installation/deployments/cluster-setup.md new file mode 100644 index 000000000..785358f6c --- /dev/null +++ b/guides/installation/deployments/cluster-setup.md @@ -0,0 +1,176 @@ +--- +nav: + title: Cluster Setup + position: 5 + +--- + +# Cluster Setup + +The setup of multiple app servers / instances is a common requirement for high-availability and high-traffic scenarios. In this guide we provide best practices and recommendations for such setups. + +## Typical architecture + +```mermaid +flowchart LR + %% Client + B[Browser] + + %% Entry / Load Balancer with TLS termination + subgraph LB[Load Balancer] + HA[HAProxy] + end + + %% App tier + subgraph APP[App Server] + direction TB + A1[App-1] + A2[App-2] + end + + %% Data/infra services + subgraph REDIS[Redis Cluster] + direction TB + R1[(Redis-1)] + R2[(Redis-2)] + end + + subgraph RMQ[RabbitMQ Cluster] + direction TB + Q1[(RabbitMQ-1)] + Q2[(RabbitMQ-2)] + end + + subgraph ES[Elasticsearch Cluster] + direction TB + E1[(ES-1)] + E2[(ES-2)] + end + + %% New: MySQL cluster + subgraph MYSQL[MySQL Cluster] + direction TB + M1[(MySQL-1)] + M2[(MySQL-2)] + end + + %% Routing + B -->|HTTPS :443| HA + HA -->|HTTP| A1 + HA -->|HTTP| A2 + + %% App → Redis + A1 <-->|TCP 6379| R1 + A2 <-->|TCP 6379| R2 + + %% App → RabbitMQ + A1 -->|AMQP :5672| Q1 + A2 -->|AMQP :5672| Q2 + + %% App → Elasticsearch + A1 -->|REST :9200| E1 + A2 -->|REST :9200| E2 + + %% App → MySQL + A1 -->|MySQL :3306| M1 + A2 -->|MySQL :3306| M2 + + %% Styles + classDef lb fill:#f6d365,stroke:#333,stroke-width:1px; + classDef app fill:#d4f1f4,stroke:#333,stroke-width:1px; + classDef redis fill:#ffd6e7,stroke:#333,stroke-width:1px; + classDef rmq fill:#e7f6d5,stroke:#333,stroke-width:1px; + classDef es fill:#f0e6ff,stroke:#333,stroke-width:1px; + classDef mysql fill:#fff2cc,stroke:#333,stroke-width:1px; + classDef client fill:#e8e8e8,stroke:#333,stroke-width:1px; + + class HA lb; + class A1,A2,A3 app; + class R1,R2,R3 redis; + class Q1,Q2,Q3 rmq; + class E1,E2,E3 es; + class M1,M2,M3 mysql; + class B client; +``` + +::: info +If you use an external cache server like Varnish / Fastly, that would be placed between the client and the load balancer. +::: + +## Shopware configuration + +To configure Shopware for a cluster setup, you have to set the following configuration in your shopware.yaml file: + +```yaml +shopware: + deployment: + # Cache clearing only deletes object cache files, no Symfony cache files on node + cluster_setup: true + # Disables the extension management in the administration + runtime_extension_management: false + auto_update: + # Disables updates via the administration + enabled: false +``` + +This option prevents Shopware from running operations locally (meaning only on one node in a cluster), that potentially can corrupt the state of the cluster by having the state of the nodes diverge from each other, e.g. clearing symfony cache files at runtime. + +## Sharing services + +In a clustered environment, it is important to share certain services across all nodes to ensure consistency and reliability. This includes: + +- **Cache**: Implement a distributed cache solution (e.g. Redis) to share cached data between nodes. +- **File storage**: Use a shared file storage solution (e.g. S3) to ensure all nodes have access to the same files. +- **Sessions**: Store sessions in a shared storage (e.g. Redis) to allow users to maintain their sessions across different nodes. + +## Session storage + +By default, Shopware uses the settings configured in PHP. You can reconfigure the Session config directly in your `php.ini`. Here is an example of configuring it directly in PHP. + +::: warning +When using Redis for session storage, ensure that the Redis instance is configured for durability and persistence, as session data should not be lost in case of a Redis restart. + +::: + +```ini +session.save_handler = redis +session.save_path = "tcp://host:6379?database=0" +``` + +Please refer to the official [PhpRedis documentation](https://github.com/phpredis/phpredis#php-session-handler) for all possible options. + +### Configure Redis using Shopware configuration + +If you don't have access to the php.ini configuration, you can configure it directly in Shopware itself. For this, create a `config/packages/redis.yml` file with the following content: + +```yaml +# config/packages/redis.yml +framework: + session: + handler_id: "redis://host:port/0" +``` + +## Lock Storage + +Shopware uses a locking mechanism to prevent race conditions and ensure that certain operations are only performed by one node at a time. By default Shopware uses files in the local filesystem for locking, which does not work in a clustered environment. Therefore, it is recommended to use a remote lock store like Redis. + +```yaml +# config/packages/framework.yaml +framework: + lock: 'redis://host:port/0' +``` + +See also the official [Symfony documentation](https://symfony.com/doc/current/lock.html#configuring) for more available options. + + +## Database cluster + +If you need high availability for your database, you can set up a database cluster. This typically involves setting up multiple database instances with replication and failover mechanisms. + + + +## Performance tweaks + +Besides the generally sharing of services, there are some performance tweaks that can be applied in a clustered environment: + + diff --git a/guides/hosting/installation-updates/deployments/deployment-helper.md b/guides/installation/deployments/deployment-automation.md similarity index 87% rename from guides/hosting/installation-updates/deployments/deployment-helper.md rename to guides/installation/deployments/deployment-automation.md index 2e7b075d8..4228ad138 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper.md +++ b/guides/installation/deployments/deployment-automation.md @@ -1,15 +1,15 @@ --- nav: - title: Deployment Helper - position: 15 + title: Deployment Automation + position: 5 --- -# Deployment Helper +# Deployment Automation -The Deployment Helper is a tool that unifies the steps executed after the Code has been uploaded to the server. +For deployment, we recommend using the Deployment Helper, which is a tool that unifies the steps executed after the code has been uploaded to the server. On a traditional deployment, you would run it after the files have been uploaded. -When using a Containerized environment, you would run Deployment Helper with the new source code and then switch over the traffic. +When using a containerized environment, you would run the Deployment Helper with the new source code and then switch over the traffic. ## Installing the Deployment Helper @@ -220,19 +220,3 @@ and deploy the changes. The extension will be uninstalled and is inactive. 2.) Remove the extension from source code After the deployment, you can remove the extension from the source code, remove the entry from the `.shopware-project.yml` file and deploy the changes again. - -## Usage examples - -### Container - -In a Docker environment, you have a base image with a running PHP Webserver. -From that image you make a new image with your Shopware source code. -To prepare the Shopware source code, you can run [shopware-cli project ci](../../../../products/cli/) to install the dependencies and build the assets. -On deployment, you spawn a second container or init a container, which runs the Deployment Helper. -The Deployment Helper sets up Shopware when it is not installed, installs the extensions and runs the one-time tasks. - -### SFTP / Deployer - -When using SFTP or Deployer, you clone the repository to the CI/CD server, run the [shopware-cli project ci](../../../../products/cli/) command to install the dependencies and build the assets. -Then you upload the source code to the server and run the Deployment Helper on the server. -The Deployment Helper sets up Shopware when it is not installed, installs the extensions and runs the one-time tasks. diff --git a/guides/hosting/installation-updates/deployments/deployment-with-deployer.md b/guides/installation/deployments/deployment-with-deployer.md similarity index 100% rename from guides/hosting/installation-updates/deployments/deployment-with-deployer.md rename to guides/installation/deployments/deployment-with-deployer.md diff --git a/guides/hosting/installation-updates/docker.md b/guides/installation/deployments/deployment-with-docker.md similarity index 97% rename from guides/hosting/installation-updates/docker.md rename to guides/installation/deployments/deployment-with-docker.md index 0eb431125..51d6a714d 100644 --- a/guides/hosting/installation-updates/docker.md +++ b/guides/installation/deployments/deployment-with-docker.md @@ -1,26 +1,16 @@ --- nav: - title: Docker Image + title: Deployment with Docker position: 10 --- -# Docker Image +# Deployment with Docker Shopware provides a Docker image to run Shopware 6 in a containerized environment for production intent. The Docker image is based on the official PHP image and includes the required PHP extensions and configurations to run Shopware 6. But it does not contain Shopware itself. It's intended to be used together with your existing Shopware project, copy the project into the image, build it, and run it. -If you don't have yet a Shopware project, you can create a new one with: - -::: info -You can create a Project with a specific Shopware version by specifying the version like: `composer create-project shopware/production:6.6.7.0 ` -::: - -```bash -composer create-project shopware/production -cd -composer require shopware/docker -``` +If you don't have yet a Shopware project, you can create one using the [Setup](./setup). The typical Dockerfile in your project would look like this: diff --git a/guides/installation/deployments/general.md b/guides/installation/deployments/general.md new file mode 100644 index 000000000..59a539d3a --- /dev/null +++ b/guides/installation/deployments/general.md @@ -0,0 +1,30 @@ +--- +nav: + title: General + position: 1 + +--- + +# General + +There are various ways to deploy Shopware. The best way depends on your infrastructure and requirements. Here are some general recommendations: + +- Use a version control system (e.g., Git) to manage your codebase. +- Automate your deployment process using CI/CD tools (e.g., GitHub Actions, GitLab CI, Jenkins). +- Use environment variables to manage configuration settings for different environments (e.g., development, staging, production) in a `.env.local` file or real environment variables. +- Implement proper logging and monitoring to track the performance and health of your application. +- Regularly back up your database and important files. + +## Strong CPU + +For the server setup, pay special attention to CPU speed. This applies to all servers (app, SQL, Elasticsearch, Redis). Usually, it is more optimal to choose a slightly stronger CPU. This has to be determined more precisely depending on the project and load. Experience has shown that systems with powerful CPUs finish processes faster and can release resources sooner. + +## Health Check + +Use the Shopware-provided Health Check API (`/api/_info/health-check`) to monitor the health of your Shopware app server. It responds with HTTP status `200` when the Shopware Application is working and `50x` when it is not. +For Docker, you can use: `HEALTHCHECK CMD curl --fail http://localhost/api/_info/health-check || exit 1` + + +## Next steps + + \ No newline at end of file diff --git a/guides/hosting/installation-updates/deployments/index.md b/guides/installation/deployments/index.md similarity index 100% rename from guides/hosting/installation-updates/deployments/index.md rename to guides/installation/deployments/index.md diff --git a/guides/hosting/configurations/shopware/staging.md b/guides/installation/deployments/staging-mode.md similarity index 96% rename from guides/hosting/configurations/shopware/staging.md rename to guides/installation/deployments/staging-mode.md index efd713c59..afdde3479 100644 --- a/guides/hosting/configurations/shopware/staging.md +++ b/guides/installation/deployments/staging-mode.md @@ -1,13 +1,13 @@ --- nav: - title: Staging + title: Staging mode position: 10 --- -# Staging +# Staging mode -Since Shopware 6.6.1.0, Shopware has an integrated staging mode. This mode prepares the shop to be used in a staging environment. This means the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. +Shopware has an integrated staging mode. This mode prepares the shop to be used in a staging environment. This means the shop is prepared to be used in a test environment, where changes can be made without affecting the live shop. ## The workflow diff --git a/guides/installation/index.md b/guides/installation/index.md index 893e72d66..44a185853 100644 --- a/guides/installation/index.md +++ b/guides/installation/index.md @@ -7,16 +7,24 @@ nav: # Installation Overview -This section discusses ways to set up Shopware on local machines so you can use it as a foundation for your development. +This section covers setting up Shopware for local development and for deployment to external servers. -There are a couple of ways to get Shopware running on your system, together with the most useful services for data storage and the web server. +## Local Setup -## Template +For a local setup, we recommand to go straight to [Setup](./setup.md) which will guide you through the installation process. -Regardless of your choice of setup, all setup methods are based on the [Project template](./template.md). This template is a new Composer project, which requires Shopware itself. Therefore, you can further customize your installation with additional extensions, themes, or configurations. +## Hosting -## Setups +For hosting Shopware on a server, please check the available options below. -The following setups are available for Shopware 6: +### Webspace Hosting / Shopware Hosting Partner - +If you want to host Shopware at a traditional webspace hosting provider, we recommend creating a local installation first using the [Setup](./setup.md) guide and then [using Deployer](./deployments/deployment-with-deployer.md) to deploy your code to the server. + +### PaaS Hosting + +If you want to host Shopware on a Shopware PaaS see [Shopware PaaS section](../../products/paas/index.md) for more information. + +### Containerized Hosting + +If you want to host Shopware in a containerized environment, we recommend creating first a local installation using the [Setup](./setup.md) guide and then [using Docker](./deployments/deployment-with-docker.md) to learn how to build and deploy your containers. diff --git a/guides/hosting/installation-updates/extension-managment.md b/guides/installation/operating/extension-managment.md similarity index 100% rename from guides/hosting/installation-updates/extension-managment.md rename to guides/installation/operating/extension-managment.md diff --git a/guides/hosting/configurations/shopware/html-sanitizer.md b/guides/installation/operating/html-sanitizer.md similarity index 88% rename from guides/hosting/configurations/shopware/html-sanitizer.md rename to guides/installation/operating/html-sanitizer.md index 607120456..eed5eb47a 100644 --- a/guides/hosting/configurations/shopware/html-sanitizer.md +++ b/guides/installation/operating/html-sanitizer.md @@ -7,10 +7,6 @@ nav: # HTML Sanitizer -::: info -This feature has been introduced with Shopware version 6.5. This is exclusively intended for self-hosted shops. However, it's important to note that the implementation is currently not available for cloud stores. -::: - ## Overview HTML sanitizer improves security, reliability and usability of the text editor by removing potentially unsafe or malicious HTML code. It also sanitizes styles and attributes for consistent and correct code rendering regardless of platform and browser. For example, if the `` tag is added, it is automatically removed by the editor after a few seconds and an additional notice appears that some of your inputs have been sanitized. diff --git a/guides/hosting/performance/k6.md b/guides/installation/operating/k6.md similarity index 100% rename from guides/hosting/performance/k6.md rename to guides/installation/operating/k6.md diff --git a/guides/hosting/configurations/observability/logging.md b/guides/installation/operating/logging.md similarity index 100% rename from guides/hosting/configurations/observability/logging.md rename to guides/installation/operating/logging.md diff --git a/guides/hosting/configurations/observability/opentelemetry.md b/guides/installation/operating/opentelemetry.md similarity index 100% rename from guides/hosting/configurations/observability/opentelemetry.md rename to guides/installation/operating/opentelemetry.md diff --git a/guides/hosting/performance/performance-tweaks.md b/guides/installation/operating/performance-tweaks.md similarity index 100% rename from guides/hosting/performance/performance-tweaks.md rename to guides/installation/operating/performance-tweaks.md diff --git a/guides/hosting/installation-updates/performing-updates.md b/guides/installation/operating/performing-updates.md similarity index 78% rename from guides/hosting/installation-updates/performing-updates.md rename to guides/installation/operating/performing-updates.md index e57d7b9fb..4a6a73e19 100644 --- a/guides/hosting/installation-updates/performing-updates.md +++ b/guides/installation/operating/performing-updates.md @@ -1,11 +1,11 @@ --- nav: - title: Performing Shopware Updates + title: Performing Updates position: 20 --- -# Performing Shopware Updates +# Performing Updates ## When to update @@ -47,6 +47,7 @@ There are two Shopware update types: - **Minor/Patch updates**: These are updates that only contain new features, bug fixes and security patches. They are released every month for the active supported versions. - **Major updates**: These updates are intended to clean up the codebase and introduce breaking changes. They are released once a year. +- **Security updates**: These updates are released as soon as a security vulnerability is found and fixed. They are only available for the active supported versions. ### Minor/Patch updates @@ -62,6 +63,47 @@ For the Hosting environment, it makes sense to update the PHP version to the min For customizations, you should check the [UPGRADE.md](https://github.com/search?q=repo%3Ashopware%2Fshopware+UPGRADE-6+language%3AMarkdown+NOT+path%3A%2F%5Eadr%5C%2F%2F+NOT+path%3A%2F%5Echangelog%5C%2F%2F&type=code&l=Markdown), it contains all breaking changes and migration instructions. Most of the time, it's easier to update to the latest version in a local environment and take a look at what is not working anymore. +### Security updates + +Security updates are released only for the newest minor version of each major version. For obtaining security fixes, without version upgrades, we provide a dedicated [Security plugin](https://store.shopware.com/swag136939272659f/shopware-6-sicherheits-plugin.html). This is compatible with all Shopware versions and corresponding hot fixes are only included in versions that are affected. + +#### Update of composer dependencies + +To ensure the security of your Shopware installation, it's essential to be vigilant about third-party dependencies that might be affected by security vulnerabilities. In that case, a new Shopware version will be released with updated dependencies. If an update to the latest Shopware version in a timely manner is not possible, it is recommended to update the affected dependency manually. This can be done by using the following command: + +```bash + composer update +``` + +To identify any potential security risk in your current dependencies, it's a good practice to regularly run the [`composer audit`](https://getcomposer.org/doc/03-cli.md#audit) command. This command scans your dependencies and alerts you if there are any known vulnerabilities that need to be addressed. + +## Updating from Composer Project + +If you're using the Composer-based setup (as described in our [development setup guide](../../installation/setup)), follow these steps: + +```bash +# Enable maintenance mode +bin/console system:update:prepare + +# Update packages +composer update + +# Update configuration files +composer recipes:update + +# Apply database migrations and finish update +bin/console system:update:finish +``` + +For Docker environments: + +```bash +# Enter container first +make shell + +# Then run the update commands above +``` + ## Final Steps Before you remove the maintenance mode, it is recommended to check the following: diff --git a/guides/hosting/configurations/observability/profiling.md b/guides/installation/operating/profiling.md similarity index 100% rename from guides/hosting/configurations/observability/profiling.md rename to guides/installation/operating/profiling.md diff --git a/guides/hosting/infrastructure/scheduled-task.md b/guides/installation/operating/scheduled-task.md similarity index 100% rename from guides/hosting/infrastructure/scheduled-task.md rename to guides/installation/operating/scheduled-task.md diff --git a/guides/hosting/configurations/shopware/static-system-config.md b/guides/installation/operating/static-system-config.md similarity index 97% rename from guides/hosting/configurations/shopware/static-system-config.md rename to guides/installation/operating/static-system-config.md index 73db618d1..2b1f1b75c 100644 --- a/guides/hosting/configurations/shopware/static-system-config.md +++ b/guides/installation/operating/static-system-config.md @@ -7,10 +7,6 @@ nav: # Static System Configuration -::: info -This feature is available since Shopware 6.6.4.0 -::: - The static system configuration is a feature that allows you to configure system configurations inside the `config/packages` directory and **overwrite** the configuration set in the database. This is useful for setting up configurations that should not be changed by the user, or properly configuring the system for different environments without the need to change the database. ## How it works diff --git a/guides/installation/operating/stock.md b/guides/installation/operating/stock.md new file mode 100644 index 000000000..9b82348aa --- /dev/null +++ b/guides/installation/operating/stock.md @@ -0,0 +1,39 @@ +--- +nav: + title: Stock Management + position: 20 + +--- + +# Stock Management + +When running Shopware 6 there are various configuration options you can use to customize your installation. These configurations reside in the general [bundle configuration](../../../../guides/hosting/configurations/). + +## Stock management system + +As of Shopware 6.5.5, the stock management system has been rewritten. The `product.stock` field is now the primary source for real-time product stock values. + +The new system is **enabled by default** and automatically manages product stock levels. When enabled, Shopware will: + +- **Decrease stock** when orders are placed and order transactions are processed +- **Increase stock** when orders are cancelled or returned +- **Track stock levels** in real-time across all sales channels +- **Prevent overselling** by checking stock availability during checkout + +This ensures accurate inventory management and prevents stock discrepancies. In the next major version of Shopware, this will be the only available stock management system. + +## Disable stock management system + +You can completely disable Shopware's automatic stock management system. When disabled: + +- **Stock levels will not be automatically updated** when orders are placed, cancelled, or returned +- **No stock validation** will occur during checkout (potentially allowing overselling) +- **Manual stock management** will be required to track inventory changes + +To disable, set `shopware.stock.enable_stock_management` to `false`: + +<<< @/docs/snippets/config/stock_disabled.yaml + +For more detailed implementation refer to [Stock](../../../../guides/plugins/plugins/content/stock/) guide section. + + diff --git a/guides/installation/requirements.md b/guides/installation/requirements.md index e695152a0..10a1a88f8 100644 --- a/guides/installation/requirements.md +++ b/guides/installation/requirements.md @@ -1,13 +1,17 @@ --- nav: title: Requirements - position: 1 + position: -30001 --- # Requirements -Before installing Shopware 6, take a quick look at the requirements below to check if your local environment is capable of running it. +::: tip Recommended Approach +Want to skip manual setup? Use our [Docker setup](./setup) which includes all requirements pre-configured. +::: + +These are the requirements for running Shopware 6. If you're using our recommended Docker setup, all of these are already included. ## Operating System @@ -51,53 +55,7 @@ On many shared hosting environments, you have multiple PHP versions installed. M * `ext-xml` * `ext-zip` * `ext-zlib` -* Composer recommended version: 2.2 or higher - -This is how you install PHP and Composer: - - - - - -Add a new software repository to your system to have the latest PHP version. - -```bash -sudo add-apt-repository ppa:ondrej/php - -sudo apt-get install -y php8.3-fpm php8.3-mysql php8.3-curl php8.3-gd php8.3-xml php8.3-zip php8.3-opcache php8.3-mbstring php8.3-intl php8.3-cli - -sudo wget https://getcomposer.org/download/latest-stable/composer.phar -O /usr/local/bin/composer -sudo chmod +x /usr/local/bin/composer -``` - - - - - -Add a new software repository to your system to have the latest PHP version: - -```bash -sudo apt-get install extrepo -sudo extrepo enable sury - -sudo apt-get update -sudo apt-get install -y php8.3-fpm php8.3-mysql php8.3-curl php8.3-gd php8.3-xml php8.3-zip php8.3-opcache php8.3-mbstring php8.3-intl php8.3-cli - -sudo wget https://getcomposer.org/download/latest-stable/composer.phar -O /usr/local/bin/composer -sudo chmod +x /usr/local/bin/composer -``` - - - - - -```bash -brew install php@8.3 composer -``` - - - - +* Composer version: 2.2 or higher ### SQL @@ -111,60 +69,15 @@ brew install php@8.3 composer * Recommended version: 11.4 * Minimum version : 10.11.6 or 11.0.4 -For optimal MySQL performance, it is advisable to set `max_allowed_packet` to a minimum of 32 MB. - -This is how you install MariaDB: - - - - - -```bash -sudo apt install -y mariadb-server -``` - - - - - -The easiest way is to use [Homebrew](https://brew.sh/): - -```bash -brew install mariadb -``` - - - - +For optimal MySQL performance, see [Performance Tweaks](../hosting/performance/performance-tweaks#mysql-configuration). ### JavaScript -* Node.js 22.0.0 or higher - -This is how you install Node.js: - - - - - -```bash -curl -fsSL https://deb.nodesource.com/setup_22.x -o nodesource_setup.sh -sudo -E bash nodesource_setup.sh - -sudo apt-get install -y nodejs -``` - - - - - -```bash -brew install node@22 -``` - - +::: info +Node.js is only required for building custom extensions and themes, not for operating the store itself. It does not need to be available in the **production environment**. +::: - +* Node.js 22.0.0 or higher ## Redis or key/value stores @@ -172,15 +85,12 @@ Shopware uses the Redis Protocol and, therefore, supports the following key/valu * [Valkey (recommended)](https://valkey.io/) * [Redis v7 or higher](https://redis.io) -* [Redict](https://redict.io) -* [KeyDB](https://docs.keydb.dev) -* [Dragonfly](https://www.dragonflydb.io) * Recommended configuration `maxmemory-policy`: `volatile-lfu` ## Webserver -To run Shopware in a development context, the [Symfony CLI](https://symfony.com/doc/current/setup/symfony_server.html) will work nicely. +Any webserver that can serve PHP will work. Here are example configurations for common webservers: @@ -192,8 +102,8 @@ We recommend the following stack: * Webserver: Caddy * PHP: 8.4 -* SQL: MariaDB 11.4 -* Node: 22 +* SQL: MariaDB 11.8 +* Node: 24 * Search: OpenSearch 2.17.1 * Queue: RabbitMQ * Cache: Valkey 8.0 @@ -201,6 +111,14 @@ We recommend the following stack: Recommended PHP ini: -## Setup +## Next Steps + +### Recommended: Docker Setup + +Skip the manual installation and use our pre-configured Docker environment: + + + +### Alternative: Manual Setup -Once the requirements are fulfilled, follow up with the [Template](template) guide to set up Shopware. +If you must install everything manually, you'll need to set up all the services listed above and then follow the Composer installation process described in our [setup guide](./setup#project-structure). diff --git a/guides/installation/setup.md b/guides/installation/setup.md new file mode 100644 index 000000000..e666c702d --- /dev/null +++ b/guides/installation/setup.md @@ -0,0 +1,338 @@ +--- +nav: + title: Setup + position: -30000 +--- + +# Setup + +This guide will help you set up a complete Shopware development environment using Docker. All commands are executed inside Docker containers, requiring no local PHP or Node.js installation. + +::: tip Why Docker? +Our Docker setup provides a **zero-configuration** development environment that works identically for all developers. It includes PHP, MySQL, Node.js, and all required services pre-configured and optimized for Shopware. +::: + +## Prerequisites + +::: info macOS Users +We recommend [OrbStack](https://orbstack.dev) over Docker Desktop for better performance. If you want to stick to Docker Desktop, enable [Docker VMM](https://docs.docker.com/desktop/features/vmm/#docker-vmm) in the settings for improved performance. +::: + +You only need: +- **Docker** - [Installation guide](https://docs.docker.com/get-docker/) +- **Docker Compose** - [Installation guide](https://docs.docker.com/compose/install/) (mostly included with Docker) +- **Make** - `apt install make` (Ubuntu) or `brew install make` (macOS) + +## Quick Start + +### 1. Create your project + +```bash +# Create and enter project directory +mkdir my-shopware-project +cd my-shopware-project + +# Create new Shopware project with Docker +docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup + +# Or install a specific version +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 creates a complete Shopware project with: +- Shopware source code +- `compose.yaml` for Docker services +- `Makefile` with convenience commands +- Pre-configured environment settings + +At this point, you should consider initializing a Git repository to track your project changes. + +```bash +git init +git add . +git commit -m "Initial commit" +``` + +### 2. Start the environment + +```bash +make up +``` + +This starts: +- **Web server** (Nginx/Caddy) on port 8000 +- **MariaDB** on port 3306 +- **Mailpit** (email testing) on port 8025 +- **Adminer** (database management) on port 9080 + +### 3. Install Shopware + +:::warning Default language and currency cannot be changed + +The default installation uses `en-GB` as the language and `EUR` as the currency. The default currency and locale cannot be changed after installation. You can still add additional languages and currencies later. Each product/category will be required to be translated into the default language / currency. +::: + +```bash +make shell + +# Installs Shopware with en-GB locale and default currency EUR +bin/console system:install --basic-setup --create-database --drop-database --force + +# Or with en-US locale and default currency USD +bin/console system:install --basic-setup --create-database --drop-database --force --shop-locale=en-US --shop-currency=USD +``` + +This automatically: +- Creates the database +- Installs Shopware +- Creates admin user (username: `admin`, password: `shopware`) + +Your shop is now running at: +- **Storefront**: +- **Administration**: +- **Mailpit**: +- **Adminer**: + +## Project Structure + +Your Shopware project has this structure: + +``` +my-shopware-project/ +├── bin/ # CLI scripts and commands +├── config/ # Configuration files +├── custom/ # Your plugins and themes +│ ├── plugins/ +│ └── static-plugins/ +├── public/ # Web root +├── var/ # Cache, logs, and generated files +├── vendor/ # Composer dependencies +├── .env # Environment variables +├── .env.local # Environment variables specific to this environment +├── composer.json # Project dependencies +├── compose.yaml # Docker services +└── Makefile # Convenience commands +``` + +### Managing Extensions + +Install plugins and themes via Composer: + +```bash +# Enter container +make shell + +# Install from Shopware Store (requires authentication) +composer require store.shopware.com/swagexampleaddon + +# Install dev tools +composer require --dev shopware/dev-tools + +# Install custom plugin from custom/plugins +composer require my-vendor/my-plugin +``` + +### Environment Variables + +Configure your shop via `.env.local` (not `.env` which gets overwritten): + +```bash +# .env.local +APP_ENV=dev +APP_URL=http://localhost:8000 +DATABASE_URL=mysql://shopware:shopware@database:3306/shopware +``` + +For a complete list of all available environment variables, see [Environment Variables Reference](./configurations/shopware/environment-variables.md). + +## Daily Development + +### Running Commands + +Execute Shopware commands inside the container: + +```bash +# Enter the container shell +make shell + +# Then run any command +bin/console cache:clear +bin/console system:install --basic-setup +``` + +Or directly from your host: + +```bash +docker compose exec web bin/console cache:clear +``` + +### Building Assets + +```bash +# Build administration +make build-administration + +# Build storefront +make build-storefront + +# Watch for changes (hot reload) +make watch-admin +make watch-storefront +``` + +### Managing the Environment + +```bash +make up # Start containers +make stop # Stop containers (data persists) +make down # Remove containers (keeps data) + +# Complete reset (removes all data) +docker compose down -v +``` + +## Configuration + +### Changing PHP/Node Version + +You can choose different PHP, Node.js, and web server combinations by using different Docker images: + +`ghcr.io/shopware/docker-dev:php[VERSION]-node[VERSION]-[WEBSERVER]` + +Available options: +- **PHP**: `8.4`, `8.3`, `8.2` +- **Node**: `node24`, `node22` +- **Web Server**: `caddy`, `nginx` + +Examples: +- `php8.4-node24-caddy` - PHP 8.4, Node 24, Caddy (recommended) +- `php8.3-node24-nginx` - PHP 8.3, Node 24, Nginx +- `php8.2-node22-caddy` - PHP 8.2, Node 22, Caddy + +To change versions, update the image in your initial setup command: + +```bash +docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.4-node24-caddy new-shopware-setup +``` + +### Debugging + +#### Enable XDebug + +Create `compose.override.yaml`: + +```yaml +services: + web: + environment: + XDEBUG_MODE: debug + XDEBUG_CONFIG: client_host=host.docker.internal + PHP_PROFILER: xdebug +``` + +Then restart: `docker compose up -d` + +#### Enable Blackfire + +```yaml +services: + web: + environment: + PHP_PROFILER: blackfire + blackfire: + image: blackfire/blackfire:2 + environment: + BLACKFIRE_SERVER_ID: YOUR_SERVER_ID + BLACKFIRE_SERVER_TOKEN: YOUR_SERVER_TOKEN +``` + +#### Enable Tideways + +```yaml +services: + web: + environment: + PHP_PROFILER: tideways + TIDEWAYS_KEY: YOUR_API_KEY + TIDEWAYS_CONNECTION: tcp://tideways:9135 + tideways: + image: ghcr.io/tideways/daemon +``` + +### Advanced Features + +#### Using OrbStack Routing + +OrbStack users can access services via `.orb.local` domains without port mapping: + +```yaml +# compose.override.yaml +services: + web: + ports: !override [] + environment: + APP_URL: https://web.my-project.orb.local + SYMFONY_TRUSTED_PROXIES: REMOTE_ADDR +``` + +#### Production Image Proxy + +Proxy production images locally when working with production databases: + +```yaml +# compose.override.yaml +services: + imageproxy: + image: ghcr.io/shopwarelabs/devcontainer/image-proxy + ports: + - "8050:80" + environment: + REMOTE_SERVER_HOST: your-production-domain.com +``` + +Then configure Shopware: + +```yaml +# config/packages/media-proxy.yaml +shopware: + filesystem: + public: + url: "http://localhost:8050" +``` + + +## Troubleshooting + +### Linux: Permission Issues + +On Linux, ensure your user ID is 1000: + +```bash +id -u # Should output 1000 +``` + +### Port Conflicts + +If port 8000 is already in use, modify `compose.yaml`: + +```yaml +services: + web: + ports: + - "8080:8000" # Use port 8080 instead +``` + +### Admin Watcher Not Working + +The admin watcher may not work out of the box in some configurations. Use the build command instead: + +```bash +make build-administration +``` + +## Next Steps + +- Learn about [Shopware's architecture](../../concepts/) +- Create your first [extension](../plugins/) +- Build a custom [theme](../plugins/themes/) +- Explore the [API](../../concepts/api/) diff --git a/guides/installation/setups/devenv.md b/guides/installation/setups/devenv.md deleted file mode 100644 index ee860eed1..000000000 --- a/guides/installation/setups/devenv.md +++ /dev/null @@ -1,629 +0,0 @@ ---- -nav: - title: Devenv - position: 30 - ---- - -# Devenv - -## What is devenv? - -Imagine [devenv](https://devenv.sh) to function as a dependency manager for the services and packages that you need to run your application for local development or even in a CI/CD context. - -Similar to other package managers, devenv lets you describe what your environment should look like and locks dependencies to a specific version to help you compose a reproducible setup. - -Devenv not only lets you choose from and install different versions of binaries (e.g., PHP, Node, npm), but it also allows you to configure and run services (like MySQL, Redis, OpenSearch). The binaries and states of the services are stored on a per-project level. - -The main difference to other tools like Docker or a VM is that it neither uses containerization nor virtualization techniques. Instead, the services run natively on your machine. - -## Installation - -### Nix - -As devenv is built on top of Nix, first install Nix with the following command based on your OS: - -```bash -curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install -``` - -#### Using Oh My ZSH? - -You probably won't be able to use the commands below. Use the following steps to continue using [oh my zsh](https://ohmyz.sh/): - -* Open `/etc/zshrc` and look for lines enclosed in `# Nix` and `# End Nix` like so (probably at the end of the file): - - ```bash - # Nix - - # ... content ... - - # End Nix - ``` - -* Copy the lines block enclosed in `# Nix` and `# End Nix` -* Open `~/.zshrc` and add the copied lines to the end of this file -* Initiate the terminal with `source ~/.zshrc` or reboot your terminal for nix to work -* Delete the lines between `# Nix` and `# End Nix` from `/etc/zshrc` - -[Credits: "nixos installation issue,'command not found: nix'", StackOverflow](https://stackoverflow.com/a/70822086/982278) - -### Devenv - -Finally, install/update devenv: - -```bash -nix-env --install --attr devenv -f https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable -``` - -You can find the whole installation guide for devenv in their official documentation: - - - -### Shopware - -Depending on whether you want to set up a fresh Shopware project or contribute to the Shopware core, you have to choose between the Symfony Flex template or the Shopware project. - - - - -First, change to a temporary nix shell providing all necessary packages for composer: - -```bash -nix-shell -p php83 php83Packages.composer -``` - -In that shell, create a new project: - -```bash -composer create-project shopware/production -``` - -Change into the project folder you've just created: - -```bash -cd -``` - -Require devenv: - -```bash -composer require frosh/devenv-meta -``` - -This will create a basic `devenv.nix` file to enable devenv support for Shopware. - - - - -Clone [shopware/shopware](https://github.com/shopware/shopware) and change into the project directory: - -```bash -git clone git@github.com:shopware/shopware.git -``` - - - - -Since the environment is described via a `devenv.nix` file committed to version control, you can now boot up the environment: - -```bash -devenv up -``` - -::: warning -Make sure that the ports for the services are not already in use, or else the command will fail. -::: - -Check your default web services with the following commands: - - - - -```bash -netstat -p tcp -van | grep '^Proto\|LISTEN' -``` - - - - - -```bash -ss -tulpn | grep ':80\|:3306\|:6379' -``` - - - - -Change your `.env` file to the correct database settings: - -```bash -# /.env -DATABASE_URL="mysql://shopware:shopware@127.0.0.1:3306/shopware?sslmode=disable&charset=utf8mb4" -``` - -Start a *new terminal*, navigate to the project directory and run the following command to launch a devenv shell. -This shell includes all necessary programs (php, composer, npm, node, etc.) to initialize Shopware: - -```bash -devenv shell -``` - -In the devenv shell, run the following command to initialize Shopware: - -```bash -bin/console system:install --basic-setup --create-database --force -``` - -Open `http://localhost:8000/admin` in your browser after the installation has finished. -You should see the Shopware admin interface. - -The default credentials are: - -* User: admin -* Password: shopware - -::: info - -When using Windows and WSL2, you need to change the default sales channel domain to `http://localhost:8000`. - -Important: Do use *http*, not https. - -::: - -### Direnv - -If you wish to switch between multiple development environments which use devenv seamlessly, we recommend installing [direnv](https://direnv.net/). - -When you enter a project directory using devenv, direnv will automatically activate the environment for you. -This means you can use the binaries without having to run `devenv shell` manually, though you still have to run `devenv up` to start all services. - -First, install direnv: - - - -The preferred way to install direnv on macOS is using Homebrew: - -```bash -brew install direnv -``` - - - - - -```bash -apt install direnv -``` - - - - -The installation instructions for other OS are available on direnv's [official documentation](https://direnv.net/docs/hook.html). - - - -Afterward, add the following hook to your shell: - - - - - -```bash -// ~/.bashrc -eval "$(direnv hook bash)" -``` - - - - - -```bash -// ~/.zshrc -eval "$(direnv hook zsh)" -``` - - - - - -```bash -// ~/.config/fish/config.fish -direnv hook fish | source -``` - - - - -The installation instructions for other OS are available on direnv's [official documentation](https://direnv.net/docs/hook.html). - - - - -After you change into a project directory using devenv for the first time, you need to allow direnv to load the environment: - -```bash -direnv allow -``` - - - -## Default services - -Here is an overview of services Shopware provides by default and how you can access them: - -| Service | Access | -|----------------|-------------------------------------------------| -| MySQL | `mysql://shopware:shopware@127.0.0.1:3306` | -| Mailhog (SMTP) | `smtp://127.0.0.1:1025` | -| Redis (TCP) | `tcp://127.0.0.1:6379` | - -### Caddy - -Caddy is a powerful, enterprise-ready, open-source web server with automatic HTTPS written in Go. - -[http://127.0.0.1:8000](http://127.0.0.1:8000) - -### Adminer - -Adminer is a full-featured database management tool written in PHP. - -[http://127.0.0.1:9080](http://127.0.0.1:9080) -The default credentials are: - -* User: shopware -* Password: shopware - -### Mailhog - -MailHog is an email testing tool for developers. - -[http://localhost:8025](http://localhost:8025) - -## Customize your setup - -To customize the predefined services to match your needs, e.g., changing the virtual host, database name, or environment variables, you can create `devenv.local.nix` to override the service definitions. -It also allows you to add and configure additional services you might require for your local development. - -::: warning -After changing `devenv.local.nix`, please [reload your environment](#manually-reloading-devenv). -::: - -```nix -// /devenv.local.nix -{ pkgs, config, lib, ... }: - -{ - # Disable a service - services.adminer.enable = false; - - # Use a custom virtual host - services.caddy.virtualHosts."http://shopware.swag" = { - extraConfig = '' - root * public - php_fastcgi unix/${config.languages.php.fpm.pools.web.socket} - file_server - ''; - }; - - # Customize nodejs version - languages.javascript = { - package = pkgs.nodejs-18_x; - }; - - # Override an environment variable - env.APP_URL = "http://shopware.swag:YOUR_CADDY_PORT"; -} -``` - -Refer to the official devenv documentation to get a complete list of all available services and their configuration possibilities: - - - -### Enable Blackfire - -```nix -// /devenv.local.nix -{ pkgs, config, lib, ... }: - -{ - services.blackfire.enable = true; - services.blackfire.server-id = ""; - services.blackfire.server-token = ""; - services.blackfire.client-id = ""; - services.blackfire.client-token = ""; -} -``` - -### Enable XDebug - -```nix -// /devenv.local.nix -{ pkgs, config, lib, ... }: - -{ - # XDebug - languages.php.extensions = [ "xdebug" ]; - languages.php.ini = '' - xdebug.mode = debug - xdebug.discover_client_host = 1 - xdebug.client_host = 127.0.0.1 - ''; -} -``` - -### Use MariaDB instead of MySQL - -```nix -// /devenv.local.nix -{ pkgs, config, lib, ... }: - -{ - services.mysql.package = pkgs.mariadb; -} -``` - -### Use customized MySQL port - -```nix -// /devenv.local.nix -{ pkgs, config, lib, ... }: - -{ - services.mysql.settings = { - mysqld = { - port = 33881; - }; - }; - -} -``` - -### Use customized VirtualHosts port for Caddy - - - - -```nix -// /devenv.local.nix -{ pkgs, config, lib, ... }: - -{ - services.caddy.virtualHosts.":8029" = { - extraConfig = '' - root * public - php_fastcgi unix/${config.languages.php.fpm.pools.web.socket} - file_server - ''; - }; -} -``` - - - - - -```nix -// /devenv.local.nix -{ pkgs, config, lib, ... }: - -{ - services.caddy.virtualHosts."http://shopware.swag:8029" = { - extraConfig = '' - root * public - php_fastcgi unix/${config.languages.php.fpm.pools.web.socket} - file_server - ''; - }; -} -``` - - - - -### Use customized Adminer port - -```nix -// /devenv.local.nix -{ pkgs, config, lib, ... }: - -{ - services.adminer.listen = "127.0.0.1:9084"; -} -``` - -### Use varnish - -```nix -# /devenv.local.nix -{ pkgs, config, lib, ... }: - -{ - # caddy config - services.caddy = { - enable = true; - - # all traffic to localhost is redirected to varnish - virtualHosts."http://localhost" = { - extraConfig = '' - reverse_proxy 127.0.0.1:6081 { - # header_up solves this issue: https://discord.com/channels/1308047705309708348/1309107911175176217 - header_up Host sw.localhost - } - ''; - }; - - # the actual shopware application is served from sw.localhost, - # choose any domain you want. - # you may need to add the domain to /etc/hosts: - # 127.0.0.1 sw.localhost - virtualHosts."http://sw.localhost" = { - extraConfig = '' - # set header to avoid CORS errors - header { - Access-Control-Allow-Origin * - Access-Control-Allow-Credentials true - Access-Control-Allow-Methods * - Access-Control-Allow-Headers * - defer - } - root * public - php_fastcgi unix/${config.languages.php.fpm.pools.web.socket} - encode zstd gzip - file_server - log { - output stderr - format console - level ERROR - } - ''; - }; - }; - - # varnish config - services.varnish = { - enable = true; - package = pkgs.varnish; - listen = "127.0.0.1:6081"; - # enables xkey module - extraModules = [ pkgs.varnishPackages.modules ]; - # it's a slightly adjusted version from the [docs](https://developer.shopware.com/docs/guides/hosting/infrastructure/reverse-http-cache.html#configure-varnish) - vcl = '' - # ... - # Specify your app nodes here. Use round-robin balancing to add more than one. - backend default { - .host = "sw.localhost"; - .port = "80"; - } - # ... - # ACL for purgers IP. (This needs to contain app server ips) - acl purgers { - "sw.localhost"; - "127.0.0.1"; - "localhost"; - "::1"; - } - # ... - ''; - }; -} -``` - -### Use an older package version - -Sometimes you want to pin a service to an older version. -Here is an example to use a specific mysql version. - -```nix -{ - services.mysql = let - mysql8033 = pkgs.mysql80.overrideAttrs (oldAttrs: { - version = "8.0.33"; - # the final url would look like this: https://github.com/mysql/mysql-server/archive/mysql-8.0.33.tar.gz - # make sure the url exists. - # alternatively you could use that url directly via pkgs.fetchurl { url = "xyz"; hash="xyz";}; - # for reference see the [different fetchers](https://ryantm.github.io/nixpkgs/builders/fetchers/#chap-pkgs-fetchers) - src = pkgs.fetchFromGitHub { - owner = "mysql"; - repo = "mysql-server"; - rev = "mysql-8.0.33"; - # leave empty on the first run, you will get prompted with the expected hash - sha256 = "sha256-s4llspXB+rCsGLEtI4WJiPYvtnWiKx51oAgxlg/lATg="; - }; - }); - in - { - enable = true; - package = mysql8033; # use the overridden package - # ... - }; -} -``` - -And another example to use a specific version of rabbitmq-server - -```nix -{ - services.rabbitmq = let - rabbitmq3137 = pkgs.rabbitmq-server.overrideAttrs (oldAttrs: { - version = "3.13.7"; - src = pkgs.fetchurl { - url = "https://github.com/rabbitmq/rabbitmq-server/releases/download/v3.13.7/rabbitmq-server-3.13.7.tar.xz"; - sha256 = "sha256-GDUyYudwhQSLrFXO21W3fwmH2tl2STF9gSuZsb3GZh0="; - }; - }); - in - { - enable = true; - package = rabbitmq3137; # use the overridden package - }; -} -``` - -## Known issues - -### Manually reloading devenv - -If you decided against using direnv, keep in mind that on every change to the `*.nix` files you need to manually reload the environment. Run `exit` to quit the current devenv shell and enter the shell again to reload: - -```bash -devenv shell -``` - -### Fail to start Redis with locale other than en_US - -```bash -14:04:52 redis.1 | 364812:M 07 Nov 2023 14:04:52.999 # Failed to configure LOCALE for invalid locale name. -``` - -You can export a different locale to your shell with the following command: - -```bash -export LANG=en_US.UTF8; -``` - -## FAQ - -### How do I clean up devenv? - -Periodically run `devenv gc` to remove orphaned services, packages and processes and free-up disk space. - -### How do I access the database? - -The MySQL service is exposed under its default port `3306`, see [default services](#default-services). - -Be aware that you cannot connect using the `localhost` socket. Instead, you must use `127.0.0.1`. - -### Where is the database stored? - -The database is stored in the `/.devenv/state/mysql` directory. - -### Where do I find available packages? - -The [NixOS package search](https://search.nixos.org/packages) is a good starting point. - -### Where do I find the binaries? - -The binaries can be found in the `/.devenv/profile/bin` directory. - -This comes in handy if you want to configure interpreters in your IDE. - -### How do I stop all processes at once? - -In case you can't find and stop running devenv processes, you can use the following command to kill them: - -```bash -kill $(ps -ax | grep /nix/store | grep -v "grep" | awk '{print $1}') -``` - -### Are you unable to access in your Browser? - -Try using instead. This mostly applies to when using WSL2. - -### Are you looking for a full test setup with demo data? - -Run the below command: - -```bash -composer setup && APP_ENV=prod bin/console framework:demodata && APP_ENV=prod bin/console dal:refresh:index -``` diff --git a/guides/installation/setups/docker.md b/guides/installation/setups/docker.md deleted file mode 100644 index 4aff8a9fd..000000000 --- a/guides/installation/setups/docker.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -nav: - title: Docker - position: 5 - ---- - -# 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-docker/). - -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 - -::: info -On macOS we recommend OrbStack, instead of Docker Desktop. OrbStack is a lightweight and fast alternative to Docker Desktop, and it is free for personal use. You can follow the official [OrbStack quickstart guide](https://docs.orbstack.dev/quick-start) to install OrbStack. -::: - -- Docker installed on your machine. You can follow the official [Docker installation guide](https://docs.docker.com/get-docker/) to install Docker. -- Docker Compose installed on your machine. You can follow the official [Docker Compose installation guide](https://docs.docker.com/compose/install/) to install Docker Compose. -- make installed on your machine. (`apt install make` on Ubuntu, `brew install make` on macOS) - -## 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: - -```bash -docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup - -# or specific version -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 will create a new Shopware project in the current directory additionally with a `compose.yaml` and a `Makefile`. The difference to regular `composer create-project` is that we use PHP, Composer from the Docker image and do not need to install PHP and Composer on your local machine. - -## Initial Setup - -After the project is created, you can run the initial setup commands to install Shopware itself. - -First, we need to start the containers - -```bash -make up -``` - -This will start the containers in the background. You can install Shopware through the Browser at or through the CLI: - -```bash -make setup -``` - -This will install Shopware itself, create an admin user with username `admin` and password `shopware`. - -:::info -For the Database Configuration step, you should put the host as `database` instead of `localhost`, which is the Docker container name. -::: - -If you want to stop the setup, you can run `make stop` and to start it again, you can run `make up` again. If you want to remove the containers, you can run `make down`. This will remove all containers and **keep the data**. If you want to remove all containers and the data, you can run `docker compose down -v` - -## Development - -To access the Shopware `bin/console`, you have to enter first the container: - -```bash -make shell -``` - -and run then `bin/console` commands. - -You can also run the commands directly from your host machine without entering the container: - -```bash -docker compose exec web bin/console cache:clear -``` - -To build the Administration or Storefront, you can run the following commands: - -```bash -# Build the administration -make build-administration - -# Build the storefront -make build-storefront - -# Start watcher for administration -make watch-admin - -# Start watcher for storefront -make watch-storefront -``` - -## Services - -The setup comes with the following services: - -- Nginx + PHP-FPM at port 8000 -- MariaDB at port 3306 -- Mailpit at port 8025 - -### Enable Profiler/Debugging for PHP - -To enable XDebug, you will need to create a `compose.override.yaml` - -```yaml -services: - web: - environment: - - XDEBUG_MODE=debug - - XDEBUG_CONFIG=client_host=host.docker.internal - - PHP_PROFILER=xdebug -``` - -and then run `docker compose up -d` to apply the changes. - -It also supports `blackfire`, `tideways` and `pcov`. For `tideways` and `blackfire` you will need a separate container like: - -```yaml -services: - web: - environment: - - PHP_PROFILER=blackfire - blackfire: - image: blackfire/blackfire:2 - environment: - BLACKFIRE_SERVER_ID: XXXX - BLACKFIRE_SERVER_TOKEN: XXXX -``` - -## Image Variations - -The Docker image comes in different variations. You can choose the one that fits your needs best. The variations are: - -`ghcr.io/shopware/docker-dev:php(PHP_VERSION)-node(NODE_VERSION)-(WEBSERVER)` - -the Matrix is: - -PHP Versions: - -- `8.4` - PHP 8.4 -- `8.3` - PHP 8.3 -- `8.2` - PHP 8.2 - -Node Versions: - -- `node24` - Node 24 -- `node22` - Node 22 - -Webserver: - -- `caddy` - Caddy as web server -- `nginx` - Nginx as web server - -Example: - -- `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 - -### Using OrbStack Routing - -If you are using OrbStack as your Docker provider, you can use the OrbStack routing feature to access your services without needing to manage port mappings. - -OrbStack generates for each running container a URL like `https://web.orb.local` and allows for easier access to your services without needing to manage port mappings. -This allows running multiple Shopware instances at the same time without port conflicts. - -Create a `compose.override.yaml` with: - -```yaml -services: - web: - ports: !override [] - environment: - APP_URL: https://web.sw.orb.local - SYMFONY_TRUSTED_PROXIES: REMOTE_ADDR - -###> symfony/mailer ### - mailer: - image: axllent/mailpit - environment: - MP_SMTP_AUTH_ACCEPT_ANY: 1 - MP_SMTP_AUTH_ALLOW_INSECURE: 1 -###< symfony/mailer ### - -``` - -The APP_URL environment variable always starts with `web..orb.local` and the rest of the URL is generated by the project name. The project name is the folder name of the project. So if you have a project called `shopware`, the URL will be `https://web.shopware.orb.local`. If you have a project called `shopware-6`, the URL will be `https://web.shopware-6.orb.local`. - -You can also open `https://orb.local` in your browser and see all running containers and their URLs. - -## Proxy Production Images - -Typically, you import for local development a copy of the production database to your local environment. This allows you to test changes with production similar data. However, this can lead to issues that all images are missing in the local environment. To avoid this, you can download all images from the production environment and import them into your local environment. Or set up a proxy server that serves the images from the production environment. - -To do this, you can add a `imageproxy` service to your `compose.override.yaml`: - -```yaml -services: - imageproxy: - image: ghcr.io/shopwarelabs/devcontainer/image-proxy - ports: - - "8050:80" - environment: - # Your production URL. - REMOTE_SERVER_HOST: shopware.com -``` - -This will start a proxy server that serves all images from the production environment. In this case if we request `http://localhost:8050/assets/images.png`, it will load `https://[REMOTE_SERVER_HOST]/assets/images.png` and serve it to the local environment, it will also cache the images locally. - -Next, we need to configure Shopware to use the proxy server. To do this, create a new YAML file `config/packages/media-proxy.yaml` - -```yaml -shopware: - filesystem: - public: - url: "http://localhost:8050" -``` - -This will tell Shopware to use the proxy server URL for all images. - -## Known issues - -### Linux host user-id must be 1000 - -If you are using Docker on Linux, your host user-id must be 1000. This is a known issue with Docker on Linux. You can check your user-id with the following command: - -```bash -id -u -``` diff --git a/guides/installation/setups/index.md b/guides/installation/setups/index.md deleted file mode 100644 index 30cbadcd4..000000000 --- a/guides/installation/setups/index.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -nav: - title: Setups - position: 3000 - ---- - -# Setups - -## Set up your own environment - -Head over to the [Requirements](../requirements) section to install and configure the necessary services like a database and a webserver to a Unix system like Linux, macOS, WSL, etc. - -## Development setup - -::: info -Technically there is no real difference between a Development Setup and a Production Setup, they only differ on performance and security optimizations. -::: - -* [Docker](docker) (beginner-friendly) - This is a Docker setup for Shopware 6. It is a lightweight and easy way to get started with Shopware. It uses Docker Compose to manage the services and is suitable for local development. - -* [Symfony CLI](symfony-cli) - This setup uses the Symfony CLI to run Shopware. It is the default way to run Symfony applications and is also suitable for Shopware. - -* [Devenv](devenv) - This is a setup that manages all necessary services. A description file in the source code manages the versions of these services. This setup works for Linux, WSL, and macOS. - -* [Dockware*](https://dockware.io/getstarted) - This is a managed docker setup for Shopware 6 by Shopware agency [dasistweb](https://www.dasistweb.de/). - -* [DDEV*](https://notebook.vanwittlaer.de/ddev-for-shopware/less-than-5-minutes-install-with-ddev-and-symfony-flex) - Docker-based PHP development environments, works on all platforms and is generic enough to be used for any PHP project. [Project Page](https://ddev.com/) - -> \* These setups are maintained by the community and not directly by Shopware. If you have any questions or issues, please open an issue in the respective repository. - -## Production setup - -### Managed hosting - -Many hosting providers, especially Shopware certified ones, offer a fully pre-configured Hosting environment for Shopware. This is the easiest way to get started with Shopware. You can find a list of certified hosting partners on the [Shopware website](https://www.shopware.com/en/partner/hosting/). You will need to upload your [Shopware project template](../template.md) to the server and run the installation commands. - -If you want to automate the installation process, consider using [Deployer](https://deployer.org/) to deploy the code changes. You can find here the [Deployer documentation](../../hosting/installation-updates/deployments/deployment-with-deployer.md). - -### Container-based hosting - -If you are using containers for your setup, check out the dedicated [Docker guide for production](../../hosting/installation-updates/docker.md). This guide will help you to set up a production ready Docker environment for Shopware 6. - -If you are using Kubernetes, take a look at the [Shopware Kubernetes Operator](https://github.com/shopware/shopware-operator). diff --git a/guides/installation/setups/symfony-cli.md b/guides/installation/setups/symfony-cli.md deleted file mode 100644 index 5aba474f7..000000000 --- a/guides/installation/setups/symfony-cli.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -nav: - title: Symfony CLI - position: 10 - ---- - -# Symfony CLI - -Symfony CLI is a popular tool in the Symfony ecosystem that helps to spawn a local development environment. It is a lightweight and an alternative way to Docker to run the application locally. - -## Prerequisites - -- Symfony CLI installed on your machine. You can follow the official [Symfony CLI installation guide](https://symfony.com/download) to install Symfony CLI. -- PHP, Composer and Node installed locally, see [here](../requirements.md) to install them. - -Shopware requires a Database server, you can install MySQL or MariaDB locally using your system package manager or if Docker is installed, Symfony CLI can run the database server in a container. - -## Create a new project - -```bash -composer create-project shopware/production - -# or install a specific version -composer create-project shopware/production:6.6.10.0 -``` - -Symfony Flex will ask while you create if you want to use Docker or not, choose **Yes** if you want to run the database in a container. If you choose **No**, you need to install MySQL or MariaDB locally. - -## Initial Setup - -### Local - -After the project is created, you need to adjust the `DATABASE_URL` to match your local database server. To do that create a `.env.local` file in the project root and add the following line: - -```dotenv -DATABASE_URL=mysql://username:password@localhost:3306/dbname -``` - -### Docker - -To run the database in a container, you need to start the containers first with: - -```bash -docker compose up -d -``` - -To stop the containers, you can run: - -```bash -docker compose down -``` - -This will stop the containers and remove them. If you want to remove the containers and the data, you can run `docker compose down -v`. -This will remove all containers and the data. -If you want to remove the containers and keep the data, you can run `docker compose down` without the `-v` flag. -This will remove all containers and keep the data. - -## Install Shopware - -::: info -It's important that you prefix all your commands with `symfony` to ensure that the correct PHP version is used. If you don't do this, you might run into issues with the wrong PHP version being used or the Docker MySQL database is not used. -::: - -After that, you can run the following command to install Shopware: - -```bash -symfony 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 didn't create a MySQL Database yet, you can pass the `--create-database` flag to create a new database. - -### Default Administration Credentials - -The Shopware's default Administration credentials are: - -| Username | Password | -|:---------|:-----------| -| `admin` | `shopware` | - -Change these credentials after finishing the installation. - -## Starting the Webserver - -To start the webserver, run the following command: - -```bash -symfony server:start -``` - -This will start the webserver on port 8000. You can access the Shopware Administration at [http://localhost:8000/admin](http://localhost:8000/admin) and the Storefront at [http://localhost:8000](http://localhost:8000). - -If you wish to run it on the background, you can use the `-d` flag: - -```bash -symfony server:start -d -``` - -### Stopping the Webserver - -To stop the webserver, run the following command: - -```bash -symfony server:stop -``` - -This will stop the webserver and all running processes. - -## Change PHP Version - -To change the used PHP version, you need to create a `.php-version` file in the project root and add the desired PHP version to it. For example, to use PHP 8.3, create a file called `.php-version` and add the following line: - -```dotenv -8.3 -``` - -This will set the PHP version to 8.3 for the current project so that any `symfony` commands will use this version. Make sure to commit this change to your version control system to keep track of the PHP version configuration. You can also verify the PHP version by running the command: - -```bash -symfony php -v -``` - -## Changing PHP Configuration - -To change the PHP Configuration, you need to create a `php.ini` file in the project root and add the desired PHP configuration to it. For example, to change the `memory_limit` to `512M`, create a file called `php.ini` and add the following line: - -```ini -memory_limit = 512M -``` - -This will set the `memory_limit` to `512M` for the current project so that any `symfony` commands will use this configuration. Make sure to commit this change to your version control system to keep track of the PHP configuration. -You can also verify the PHP configuration by running the command: - -```bash -symfony php -i -``` - -## Building/Watcher the Administration and Storefront - - diff --git a/guides/installation/template.md b/guides/installation/template.md deleted file mode 100644 index afed90b11..000000000 --- a/guides/installation/template.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -nav: - title: Project Template - position: 2 - ---- - -# Project Template - -The Shopware project template is a Composer project that can be used as starting point for new Shopware Projects, or if you want to develop extensions or themes for Shopware. - -## 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 old zip installation to 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/snippets/config/stock.sh b/snippets/config/stock.sh deleted file mode 100644 index c883fbd54..000000000 --- a/snippets/config/stock.sh +++ /dev/null @@ -1,2 +0,0 @@ -// /.env -STOCK_HANDLING=1