Spryker Documentation

Create discounts based on shipment

Tue, 04 Aug 2026 12:24:33 +0000

This How To guide shows how to do the following:

Activate a discount rule based on a shipment carrier, a shipment method, or a shipment price.
Add a shipment pre-check plugin to checkout.

Activate a discount rule based on a shipment carrier

You can create a discount rule based on a shipment carrier, a shipment method, or a shipment price.

To have a discount calculated based on a shipment method, select the shipment-method rule in the discount UI, Discount calculation. The discount then applies only to the shipment expense with the chosen method. To define that your discount is applied only when the order is delivered by the chosen method, you can select a shipment method rule for Conditions.

The same approach works for a carrier (shipment-carrier) and price (shipment.price). You can combine these rules together based on your requirements.

To activate this feature, follow these steps:

In your project, install the ShipmentDiscountConnector module.
Activate the decision rule and the collector plugins in \Pyz\Zed\Discount\DiscountDependencyProvider:

<?php

namespace Pyz\Zed\Discount;

use Spryker\Zed\ShipmentDiscountConnector\Communication\Plugin\DecisionRule\ShipmentCarrierDecisionRulePlugin;
use Spryker\Zed\ShipmentDiscountConnector\Communication\Plugin\DecisionRule\ShipmentMethodDecisionRulePlugin;
use Spryker\Zed\ShipmentDiscountConnector\Communication\Plugin\DecisionRule\ShipmentPriceDecisionRulePlugin;
use Spryker\Zed\ShipmentDiscountConnector\Communication\Plugin\DiscountCollector\ItemByShipmentCarrierPlugin;
use Spryker\Zed\ShipmentDiscountConnector\Communication\Plugin\DiscountCollector\ItemByShipmentMethodPlugin;
use Spryker\Zed\ShipmentDiscountConnector\Communication\Plugin\DiscountCollector\ItemByShipmentPricePlugin;
...

class DiscountDependencyProvider extends SprykerDiscountDependencyProvider
{

    /**
     * @return \Spryker\Zed\Discount\Dependency\Plugin\DecisionRulePluginInterface[]
     */
    protected function getDecisionRulePlugins()
    {
        return array_merge(parent::getDecisionRulePlugins(), [
            ...
            new ShipmentCarrierDecisionRulePlugin(),
            new ShipmentMethodDecisionRulePlugin(),
            new ShipmentPriceDecisionRulePlugin(),
        ]);
    }

    /**
     * @return \Spryker\Zed\Discount\Dependency\Plugin\CollectorPluginInterface[]
     */
    protected function getCollectorPlugins()
    {
        return array_merge(parent::getCollectorPlugins(), [
            ...
            new ItemByShipmentCarrierPlugin(),
            new ItemByShipmentMethodPlugin(),
            new ItemByShipmentPricePlugin(),
        ]);
    }

}

You are now ready to use the shipment discounts.

Add the checkout shipment precheck plugin to checkout

You can add the shipment precheck plugin to the checkout workflow, which checks if the shipment is active in the order placing. If it’s not, then an error message is displayed, and a customer gets redirected to the shipment step to select another shipment method.

To install a new module, Composer requires spryker/shipment-checkout-connector. This module provides the plugin itself.
Add the \Spryker\Zed\ShipmentCheckoutConnector\Communication\Plugin\Checkout\ShipmentCheckoutPreCheckPlugin plugin to the checkout dependency provider precheck plugin stack:

<?php

namespace Pyz\Zed\Checkout;

	use Spryker\Zed\ShipmentCheckoutConnector\Communication\Plugin\Checkout\ShipmentCheckoutPreCheckPlugin;

	class CheckoutDependencyProvider extends SprykerCheckoutDependencyProvider
	{
	    /**
	       * @param \Spryker\Zed\Kernel\Container $container ’
	       *
	       * @return \Spryker\Zed\Checkout\Dependency\Plugin\CheckoutPreConditionInterface[]
	       */
	      protected function getCheckoutPreConditions(Container $container)
	      {
	          return [
	              ...//other plugins
	              new ShipmentCheckoutPreCheckPlugin()
	          ];
	      }
	}

Install the Configuration Management feature

Mon, 03 Aug 2026 08:48:40 +0000

This document describes how to install the Configuration Management feature. ## Prerequisites Update the required modules: | NAME | VERSION | |----|---------| | Kernel | ^3.82 | | Store | ^1.36 | | Translator | ^1.15 | ## Install feature core ### 1) Install the required modules Install the required modules using Composer: ```bash composer require spryker/configuration:"^1.0.0" --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following modules have been installed: | MODULE | EXPECTED DIRECTORY | | --- | --- | | Configuration | vendor/spryker/configuration | {% endinfo_block %} ### 2) Set up configuration Add the following configuration to extend scope support with store-level configuration: | CONFIGURATION | SPECIFICATION | NAMESPACE | | --- | --- | --- | | ConfigurationConfig | Adds `store` scope to available scopes and defines scope hierarchy (store inherits from global). | Pyz\Shared\Configuration | **src/Pyz/Shared/Configuration/ConfigurationConfig.php** ```php ' SPRYKER_CONFIGURATION_ENCRYPTION_INIT_VECTOR: '' ``` In Cloud, add environment variables using [Parameter Store](/docs/ca/dev/add-variables-in-the-parameter-store). To generate new keys, run: ```bash openssl rand -hex 32 # generates SPRYKER_CONFIGURATION_ENCRYPTION_KEY openssl rand -hex 16 # generates SPRYKER_CONFIGURATION_ENCRYPTION_INIT_VECTOR ``` {% info_block warningBox "Verification" %} 1. Create a setting with `secret: true` in a YAML schema and run `configuration:sync`. 2. Set a value for the secret setting in the Back Office. 3. Check the `spy_configuration_value` table — the stored value must be encrypted (not plain text). 4. Read the value back in the Back Office — it must be decrypted and displayed correctly. {% endinfo_block %} ### 3) Set up the database schema and transfer objects #### 3.1) Set up database schema extension Add event behavior to the `spy_configuration_value` table to enable Publish & Synchronize: **src/Pyz/Zed/Configuration/Persistence/Propel/Schema/spy_configuration.schema.xml** ```xml

``` #### 3.2) Apply database changes and generate transfers ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure that the following changes have been applied by checking your database: | DATABASE ENTITY | TYPE | EVENT | | --- | --- | --- | | spy_configuration_value | table | created | | spy_configuration_storage | table | created | {% endinfo_block %} {% info_block warningBox "Verification" %} Make sure the following changes in transfer objects have been applied: | TRANSFER | TYPE | EVENT | PATH | | --- | --- | --- | --- | | ConfigurationSetting | class | created | src/Generated/Shared/Transfer/ConfigurationSettingTransfer | | ConfigurationValue | class | created | src/Generated/Shared/Transfer/ConfigurationValueTransfer | | ConfigurationScope | class | created | src/Generated/Shared/Transfer/ConfigurationScopeTransfer | | ConfigurationFeature | class | created | src/Generated/Shared/Transfer/ConfigurationFeatureTransfer | | ConfigurationTab | class | created | src/Generated/Shared/Transfer/ConfigurationTabTransfer | | ConfigurationGroup | class | created | src/Generated/Shared/Transfer/ConfigurationGroupTransfer | | ConfigurationConstraint | class | created | src/Generated/Shared/Transfer/ConfigurationConstraintTransfer | | ConfigurationDependency | class | created | src/Generated/Shared/Transfer/ConfigurationDependencyTransfer | | ConfigurationSyncResponse | class | created | src/Generated/Shared/Transfer/ConfigurationSyncResponseTransfer | | ConfigurationSettingCollection | class | created | src/Generated/Shared/Transfer/ConfigurationSettingCollectionTransfer | | ConfigurationScopeCollection | class | created | src/Generated/Shared/Transfer/ConfigurationScopeCollectionTransfer | | ConfigurationValueRequest | class | created | src/Generated/Shared/Transfer/ConfigurationValueRequestTransfer | | ConfigurationValueResponse | class | created | src/Generated/Shared/Transfer/ConfigurationValueResponseTransfer | | ConfigurationValidationRequest | class | created | src/Generated/Shared/Transfer/ConfigurationValidationRequestTransfer | | ConfigurationValidationResponse | class | created | src/Generated/Shared/Transfer/ConfigurationValidationResponseTransfer | | ConfigurationError | class | created | src/Generated/Shared/Transfer/ConfigurationErrorTransfer | | ConfigurationValueCollectionRequest | class | created | src/Generated/Shared/Transfer/ConfigurationValueCollectionRequestTransfer | | ConfigurationValueDeletion | class | created | src/Generated/Shared/Transfer/ConfigurationValueDeletionTransfer | | ConfigurationValueCollectionResponse | class | created | src/Generated/Shared/Transfer/ConfigurationValueCollectionResponseTransfer | | ConfigurationSettingValuesCriteria | class | created | src/Generated/Shared/Transfer/ConfigurationSettingValuesCriteriaTransfer | | ConfigurationSettingValueCollection | class | created | src/Generated/Shared/Transfer/ConfigurationSettingValueCollectionTransfer | | ConfigurationStorage | class | created | src/Generated/Shared/Transfer/ConfigurationStorageTransfer | | ConfigurationFileUpload | class | created | src/Generated/Shared/Transfer/ConfigurationFileUploadTransfer | | ConfigurationFileUploadCollectionRequest | class | created | src/Generated/Shared/Transfer/ConfigurationFileUploadCollectionRequestTransfer | | ConfigurationFileUploadCollectionResponse | class | created | src/Generated/Shared/Transfer/ConfigurationFileUploadCollectionResponseTransfer | {% endinfo_block %} ### 4) Add translations Regenerate the Zed translator cache to pick up the Configuration Management Back Office UI translations: ```bash console translator:generate-cache ``` {% info_block warningBox "Verification" %} 1. Navigate to the Configuration Management page in the Back Office. 2. Verify that all UI labels, buttons, and messages are displayed in the correct locale. 3. Switch to German locale and verify the German translations appear. {% endinfo_block %} ### 5) Configure navigation Add the Configuration Management entry to `config/Zed/navigation.xml`: ```xml Configuration Configuration Management settings configuration manage index 1 ``` Execute the following command to clear the navigation cache: ```bash console navigation:cache:remove ``` {% info_block warningBox "Verification" %} Log in to the Back Office and verify that the **Configuration** menu item appears in the main navigation sidebar. {% endinfo_block %} ### 6) Set up behavior #### 6.1) Register console commands and application plugin Register the configuration sync console command and the application plugin that exposes the Configuration facade as an application service for direct Zed access from the Client layer: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | ConfigurationSyncConsole | Synchronizes configuration schemas from YAML files and generates the merged schema and settings map. | None | Spryker\Zed\Configuration\Communication\Console | | ConfigurationApplicationPlugin | Registers the Configuration facade as an application service for direct access in Zed applications. | None | Spryker\Zed\Configuration\Communication\Plugin\Application | **src/Pyz/Zed/Console/ConsoleDependencyProvider.php** Add the import statements: ```php use Spryker\Zed\Configuration\Communication\Console\ConfigurationSyncConsole; use Spryker\Zed\Configuration\Communication\Plugin\Application\ConfigurationApplicationPlugin; ``` Register the console command in `getConsoleCommands()`: ```php protected function getConsoleCommands(Container $container): array { $commands = [ // ... new ConfigurationSyncConsole(), // ... ]; } ``` Register the application plugin in `getApplicationPlugins()`: ```php protected function getApplicationPlugins(Container $container): array { $applicationPlugins = parent::getApplicationPlugins($container); // ... $applicationPlugins[] = new ConfigurationApplicationPlugin(); return $applicationPlugins; } ``` **src/Pyz/Zed/Application/ApplicationDependencyProvider.php** Add the import statement: ```php use Spryker\Zed\Configuration\Communication\Plugin\Application\ConfigurationApplicationPlugin; ``` Register the application plugin in each Zed application context (`getBackofficeApplicationPlugins()`, `getBackendGatewayApplicationPlugins()`, `getBackendApiApplicationPlugins()`): ```php protected function getBackofficeApplicationPlugins(): array { return [ // ... new ConfigurationApplicationPlugin(), ]; } protected function getBackendGatewayApplicationPlugins(): array { return [ // ... new ConfigurationApplicationPlugin(), ]; } protected function getBackendApiApplicationPlugins(): array { return [ // ... new ConfigurationApplicationPlugin(), ]; } ``` {% info_block warningBox "Verification" %} 1. Run `console configuration:sync` and verify that it outputs the number of processed settings. 2. Verify that configuration values can be read in Zed context via the Client layer without going through storage. {% endinfo_block %} #### 6.2) Set up queue configuration Register the Configuration storage synchronization queue in both message broker implementations. **src/Pyz/Client/RabbitMq/RabbitMqConfig.php** Add the import statement: ```php use Spryker\Shared\Configuration\ConfigurationConstants; ``` Add the queue name to `getSynchronizationQueueConfiguration()`: ```php protected function getSynchronizationQueueConfiguration(): array { return [ // ... ConfigurationConstants::QUEUE_NAME_SYNC_CONFIGURATION, ]; } ``` **src/Pyz/Client/SymfonyMessenger/SymfonyMessengerConfig.php** Add the import statement: ```php use Spryker\Shared\Configuration\ConfigurationConstants; ``` Add the queue name to `getSynchronizationQueueConfiguration()`: ```php protected function getSynchronizationQueueConfiguration(): array { return [ // ... ConfigurationConstants::QUEUE_NAME_SYNC_CONFIGURATION, ]; } ``` {% info_block warningBox "Verification" %} Run `console queue:setup` and verify that the `sync.storage.configuration` queue is created in RabbitMQ. {% endinfo_block %} #### 6.3) Register queue message processor Register the synchronization storage queue message processor for the Configuration sync queue: **src/Pyz/Zed/Queue/QueueDependencyProvider.php** Add the import statements: ```php use Spryker\Shared\Configuration\ConfigurationConstants; ``` Add the processor to `getProcessorMessagePlugins()`: ```php protected function getProcessorMessagePlugins(Container $container): array { return [ // ... ConfigurationConstants::QUEUE_NAME_SYNC_CONFIGURATION => new SynchronizationStorageQueueMessageProcessorPlugin(), ]; } ``` {% info_block warningBox "Verification" %} 1. Save a configuration value in the Back Office. 2. Run `console queue:worker:start --stop-when-empty`. 3. Verify that the `sync.storage.configuration` queue is processed without errors. {% endinfo_block %} #### 6.4) Register publisher plugins Enable Publish & Synchronize for configuration values by registering the publisher plugin: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | ConfigurationValueWritePublisherPlugin | Publishes storefront-visible, non-secret configuration values to `spy_configuration_storage` when `spy_configuration_value` entities are created, updated, or deleted. | None | Spryker\Zed\Configuration\Communication\Plugin\Publisher | **src/Pyz/Zed/Publisher/PublisherDependencyProvider.php** Add the import statement: ```php use Spryker\Zed\Configuration\Communication\Plugin\Publisher\ConfigurationValueWritePublisherPlugin; ``` Register the plugin group in `getPublisherPlugins()`: ```php protected function getPublisherPlugins(): array { return array_merge( // ... $this->getConfigurationStoragePlugins(), ); } ``` Add the new method: ```php /** * @return list<\Spryker\Zed\PublisherExtension\Dependency\Plugin\PublisherPluginInterface> */ protected function getConfigurationStoragePlugins(): array { return [ new ConfigurationValueWritePublisherPlugin(), ]; } ``` {% info_block warningBox "Verification" %} 1. Save a configuration value in the Back Office. 2. Check that the `spy_configuration_storage` table contains the published value. 3. Verify that secret settings are NOT published to storage. {% endinfo_block %} #### 6.5) Register scope identifier provider plugins Register the store scope identifier provider to resolve the current store name as the scope identifier: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | StoreConfigurationScopeIdentifierProviderPlugin | Provides the current store name as the scope identifier for the `store` scope. | Store module installed | Spryker\Zed\Store\Communication\Plugin\Configuration | **src/Pyz/Zed/Configuration/ConfigurationDependencyProvider.php** ```php */ protected function getScopeIdentifierProviderPlugins(): array { return [ new StoreConfigurationScopeIdentifierProviderPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} 1. Navigate to the Configuration Management page in the Back Office. 2. Switch the scope selector to a specific store. 3. Verify that the scope identifier resolves to the store name (for example `DE`, `AT`). {% endinfo_block %} #### 6.6) Register Client-level request expander plugins Register the store scope expander to attach the current store scope to configuration value requests: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | StoreScopeConfigurationValueRequestExpanderPlugin | Expands the configuration value request with the current store scope and store name as scope identifier. | Store module installed | Spryker\Client\Store\Plugin\Configuration | **src/Pyz/Client/Configuration/ConfigurationDependencyProvider.php** ```php

Configuration Management feature

Mon, 03 Aug 2026 08:48:40 +0000

What It Does

Provides a centralized, schema-driven system for managing application settings across scopes (for example global, store, custom-scope). Settings are declared in YAML files, managed via the Back Office UI, to be consumed in different layers (Zed, Yves, Glue) through module Config classes.

Quick Start

1. Declare settings in a YAML schema

# /data/configuration/my-module.configuration.yml
features:
  - key: my_module
    name: My Module
    tabs:
      - key: general
        name: General
        groups:
          - key: display
            name: Display Settings
            scopes: [global, store]
            settings:
              - key: items_per_page
                name: Items Per Page
                type: integer
                default_value: 24
                scopes: [global, store]
                storefront: true
                constraints:
                  - type: required
                    message: Items per page is required
                  - type: min
                    message: Must be at least 1
                    options: { min: 1 }

2. Sync schemas

docker/sdk cli console configuration:sync

3. Consume in your module Config

namespace Spryker\Yves\MyModule;

use Spryker\Yves\Kernel\AbstractBundleConfig;

class MyModuleConfig extends AbstractBundleConfig
{
    protected const int DEFAULT_ITEMS_PER_PAGE = 24;

    protected const string CONFIGURATION_KEY_MY_MODULE_GENERAL_DISPLAY_ITEMS_PER_PAGE = 'my_module:general:display:items_per_page';

    public function getItemsPerPage(): int
    {
        return $this->getModuleConfig(static::CONFIGURATION_KEY_MY_MODULE_GENERAL_DISPLAY_ITEMS_PER_PAGE, static::DEFAULT_ITEMS_PER_PAGE);
    }
}

The getModuleConfig() method is available in Zed, Yves, Glue layers AbstractBundleConfig and is the preferred way to read configuration values.

Reading Configuration Values

The `getModuleConfig()` Method

Every AbstractBundleConfig in Zed, Yves, and Glue provides:

protected function getModuleConfig(
    string $key,
    mixed $default = null,
    array $configurationScopes = [],
): mixed

Parameter	Type	Description
`$key`	string	Compound setting key: `feature:tab:group:setting`
`$default`	mixed	Fallback when value is not found or Configuration module is not installed
`$configurationScopes`	`ConfigurationScopeTransfer[]`	Optional scope context transfers

Layer behavior:

Yves / Glue: Reads from key-value storage via ConfigurationClient (fast, cached)
Zed: Reads from database via ConfigurationFacade (supports secrets, full scope resolution)

Backward Compatible: If the Configuration module is not installed, getModuleConfig() silently returns $default.

Real-World Examples

AvailabilityWidget (Yves) – boolean setting with constant fallback:

class AvailabilityWidgetConfig extends AbstractBundleConfig
{
    protected const bool STOCK_DISPLAY_ENABLED = false;

    public const string STOCK_DISPLAY_MODE_INDICATOR_AND_QUANTITY = 'indicator_and_quantity';

    protected const string CONFIGURATION_KEY_CATALOG_INVENTORY_STOCK_OPTIONS_DISPLAY_STOCK_AVAILABILITY = 'catalog:inventory:stock_options:display_stock_availability';

    protected const string CONFIGURATION_KEY_CATALOG_INVENTORY_STOCK_OPTIONS_STOCK_INFO_OPTIONS = 'catalog:inventory:stock_options:stock_info_options';

    public function isStockDisplayEnabled(): bool
    {
        return $this->getModuleConfig(static::CONFIGURATION_KEY_CATALOG_INVENTORY_STOCK_OPTIONS_DISPLAY_STOCK_AVAILABILITY, static::STOCK_DISPLAY_ENABLED);
    }

    public function getStockDisplayMode(): string
    {
        return $this->getModuleConfig(static::CONFIGURATION_KEY_CATALOG_INVENTORY_STOCK_OPTIONS_STOCK_INFO_OPTIONS, static::STOCK_DISPLAY_MODE_INDICATOR_AND_QUANTITY);
    }
}

BuyBox (Yves) – string setting with enum fallback:

class BuyBoxConfig extends AbstractBundleConfig
{
    public const string SORT_BY_PRICE = 'price';

    protected const string CONFIGURATION_KEY_MARKETPLACE_PDP_BUY_BOX_OFFER_SORT_RULE = 'marketplace:pdp:buy_box:offer_sort_rule';

    public function getSortingStrategy(): string
    {
        return $this->getModuleConfig(static::CONFIGURATION_KEY_MARKETPLACE_PDP_BUY_BOX_OFFER_SORT_RULE, static::SORT_BY_PRICE);
    }
}

Scope-Specific Reads

Pass ConfigurationScopeTransfer objects as the third argument when you need a scope-specific value:

use Generated\Shared\Transfer\ConfigurationScopeTransfer;

public function getItemsPerPage(string $storeName): int
{
    protected const string CONFIGURATION_KEY_MY_MODULE_GENERAL_DISPLAY_ITEMS_PER_PAGE = 'my_module:general:display:items_per_page';

    return $this->getModuleConfig(
        static::CONFIGURATION_KEY_MY_MODULE_GENERAL_DISPLAY_ITEMS_PER_PAGE,
        static::DEFAULT_ITEMS_PER_PAGE,
        [
            (new ConfigurationScopeTransfer())
                ->setKey('store')
                ->setIdentifier($storeName),
        ],
    );
}

Integration Checklist

When integrating Configuration into an existing module:

Identify hardcoded values or constants that should be configurable
Declare them in a YAML schema in data/configuration/
Replace hardcoded access in the module’s Config class with getModuleConfig() calls
Keep the original constant as $default for backward compatibility
Run configuration:sync
Values are now manageable via the Back Office Configuration Management page

YAML Schema Declaration Reference

Schema Validation

YAML schema files support IDE autocompletion via JSON Schema. Add this header to your file:

# yaml-language-server: $schema=../../vendor/spryker/configuration/resources/configuration/configuration-schema-v1.json

The schema file is located at vendor/spryker/configuration/resources/configuration/configuration-schema-v1.json.

Hierarchy

features[]
  tabs[]
    groups[]
      settings[]

Each setting gets a compound key: {featureKey}:{tabKey}:{groupKey}:{settingKey} used for persistence and lookups.

Feature Level

features:
  - key: system                          # Required. Unique feature identifier.
    name: System Configuration           # Required. Display name in backoffice.
    description: Core system settings    # Optional. Feature description (shown as tooltip).
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    status: beta                         # Optional. Status badge (beta, early_access).
    tabs: [...]                          # Required. At least one tab.

Property	Type	Required	Default	Constraints	Description
`key`	string	Yes	–	`^[a-z][a-z0-9_]*$`	Unique identifier. Part of compound setting key.
`name`	string	Yes	–	1-255 chars	Display name in backoffice sidebar.
`description`	string	No	`null`	max 1000 chars	Feature description text. Shown as tooltip in sidebar.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, feature and all children are hidden from the backoffice, search results, and settings map.
`status`	string	No	`null`	`beta`, `early_access`	Status badge displayed next to the feature name. Invalid values are silently ignored.
`tabs`	array	Yes	–	min 1 item	List of tab objects.

Tab Level

tabs:
  - key: general                         # Required. Unique within feature.
    name: General                        # Required. Tab display name.
    icon: settings                       # Optional. Icon class for backoffice tab.
    description: General system settings # Optional. Tab description (shown as tooltip).
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    status: early_access                 # Optional. Status badge.
    groups: [...]                        # Required. At least one group.

Property	Type	Required	Default	Constraints	Description
`key`	string	Yes	–	`^[a-z][a-z0-9_]*$`	Unique within feature. Part of compound setting key.
`name`	string	Yes	–	1-255 chars	Tab label in backoffice.
`icon`	string	No	`null`	max 100 chars	Material Symbols icon name (for example `settings`, `cable`, `trending_up`).
`description`	string	No	`null`	max 1000 chars	Tab description text. Shown as tooltip in sidebar.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, tab and all children are hidden from the backoffice, search results, and settings map.
`status`	string	No	`null`	`beta`, `early_access`	Status badge displayed next to the tab name.
`groups`	array	Yes	–	min 1 item	List of group objects.

Group Level

groups:
  - key: basic                           # Required. Unique within tab.
    name: Basic Settings                 # Required. Group display name.
    description: Basic system config     # Optional. Group description.
    scopes: [global, store]              # Required. Scopes this group is visible for.
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    status: beta                         # Optional. Status badge.
    settings: [...]                      # Required. At least one setting.

Property	Type	Required	Default	Constraints	Description
`key`	string	Yes	–	`^[a-z][a-z0-9_]*$`	Unique within tab.
`name`	string	Yes	–	1-255 chars	Group heading in backoffice.
`description`	string	No	`null`	max 1000 chars	Group description text.
`scopes`	string[]	Yes	`['global']`	min 1 item	Scopes where this group is displayed in backoffice. Setting scopes are constrained to their parent group scopes.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, group and all settings are hidden from the backoffice, search results, and settings map.
`status`	string	No	`null`	`beta`, `early_access`	Status badge displayed next to the group heading.
`settings`	array	Yes	–	min 1 item	List of setting objects.

Setting Level

settings:
  - key: site_name                       # Required. Unique within group.
    name: Site Name                      # Required. Setting label.
    description: The name of the site    # Optional. Displayed below the input.
    note: Changes require cache clear    # Optional. Additional note below description.
    placeholder: Enter your store name   # Optional. Input placeholder text.
    help_text: Appears in page titles    # Optional. Tooltip or help area text.
    template: '@MyModule/Configuration/custom-input.twig'  # Optional. Custom Twig template.
    type: string                         # Required. Data type.
    default_value: My Store              # Optional. Fallback value.
    options:                             # Optional. For select/multiselect/radio types.
      - value: option_a
        label: Option A
    scopes: [global, store]              # Optional. Default: ['global'].
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    status: early_access                 # Optional. Status badge.
    secret: false                        # Optional. Default: false.
    storefront: true                     # Optional. Default: false.
    constraints: [...]                   # Optional. Validation constraints.
    dependencies: [...]                  # Optional. Conditional visibility rules.
    sanitize_xss: {...}                  # Optional. XSS sanitization rules.
    data_object: \My\DataProvider        # Optional. Data provider plugin class.

Property	Type	Required	Default	Constraints	Description
`key`	string	Yes	–	`^[a-z][a-z0-9_]*$`	Unique within group. Part of compound key.
`name`	string	Yes	–	1-255 chars	Input label in backoffice.
`description`	string	No	`null`	max 1000 chars	Help text displayed below the input field.
`note`	string	No	`null`	max 1000 chars	Additional note displayed below the description in italic.
`placeholder`	string	No	`null`	max 255 chars	Placeholder text inside the input field.
`help_text`	string	No	`null`	max 500 chars	Extended help in tooltip or expandable area.
`template`	string	No	`null`	max 255 chars	Custom Twig template. Overrides type-based widget.
`type`	string	Yes	–	See types table	Value data type. Determines backoffice input widget.
`default_value`	mixed	No	`null`	Must match `type`	Fallback when no value is saved at any scope.
`options`	option[]	No	`[]`	For select/multi/radio	Available choices. See Options.
`scopes`	string[]	No	`['global']`	min 1 item	Scopes where this setting can be configured. Constrained to parent group scopes.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, setting is hidden from the backoffice, search results, and settings map.
`status`	string	No	`null`	`beta`, `early_access`	Status badge displayed next to the setting label.
`secret`	boolean	No	`false`	–	When `true`, value is encrypted in database. Never published to storage.
`storefront`	boolean	No	`false`	–	When `true`, value is published to key-value storage for Yves/Glue.
`constraints`	array	No	`[]`	–	Validation rules. See Constraints.
`dependencies`	array	No	`[]`	–	Conditional rules. See Dependencies.
`file_upload`	object	No	`null`	Required when `type: file`	File upload configuration. See File upload fields.
`sanitize_xss`	object	No	`{}`	–	XSS sanitization configuration. See XSS Sanitization.
`data_object`	string	No	`null`	Fully qualified class name	Plugin class implementing `ConfigurationSettingDataProviderPluginInterface`. Provides dynamic data to the setting at render time.

Setting Types

Type	Description	Backoffice Input	Requires `options`
`string`	Single-line text	Text input	No
`integer`	Whole number	Number input	No
`float`	Decimal number	Number input	No
`boolean`	True/false toggle	Checkbox/switch	No
`text`	Multi-line text or structured data	Textarea	No
`color`	Color hex value	Color picker	No
`json`	JSON structure	Code editor	No
`select`	Single choice from list	Dropdown	Yes
`multiselect`	Multiple choices from list	Multi-select	Yes
`radio`	Single choice from list	Radio buttons	Yes
`file`	File upload (stored as public URL)	File upload widget	No, but requires `file_upload` block

File upload fields

Use type: file for settings that accept a file upload (for example, logo images). The Back Office renders a file upload widget. After a successful upload, the public URL of the uploaded file is stored as the setting value. All file validation and storage are handled server-side using a configured Flysystem filesystem service.

When type: file is used, a file_upload block must be present on the setting. It configures the Flysystem service, allowed file types, size limit, and recommended display dimensions.

- key: bo_logo_url
  name: Back Office Logo
  type: file
  file_upload:
    storage_name: 'backoffice-media'
    allowed_mime_types:
      - 'image/png'
      - 'image/jpeg'
      - 'image/gif'
      - 'image/webp'
      - 'image/svg+xml'
    allowed_extensions:
      - '.png'
      - '.jpg'
      - '.jpeg'
      - '.gif'
      - '.webp'
      - '.svg'
    max_file_size: '10M'
    recommended_width_px: 290
    recommended_height_px: 77
  default_value: ''
  scopes: [global, store]
  enabled: true
  secret: false
  storefront: false

`file_upload` properties

Property	Type	Required	Description
`storage_name`	string	Yes	Flysystem filesystem service name. Must be configured in `FileSystemConstants::FILESYSTEM_SERVICE`.
`allowed_mime_types`	string[]	No	List of permitted MIME types. Upload is rejected if the file MIME type is not in the list.
`allowed_extensions`	string[]	No	List of permitted file extensions including the leading dot (for example `.png`).
`max_file_size`	string	No	Maximum allowed file size (for example `10M`, `2048K`). Rejected if exceeded.
`recommended_width_px`	integer	No	Recommended display width in pixels. Shown as a hint in the Back Office UI.
`recommended_height_px`	integer	No	Recommended display height in pixels. Shown as a hint in the Back Office UI.

The stored value is always a public URL returned by the Flysystem service after upload. To render the image in a Twig template, read it with configurationValue() and use it as an src attribute:

{% set logoUrl = configurationValue('theme:logos:logos:yves_logo_url', '') %}
{% if logoUrl is not empty %}
    <img src="{{ logoUrl | e('html_attr') }}" alt="Logo" />
{% endif %}

For Flysystem service setup (S3 in production, local fallback in development and CI), see Install the Basic Shop Theme feature.

Options

Required for select, multiselect, and radio types. Defines available choices.

options:
  - value: indicator_only
    label: Indicator Only
    description: Show only in-stock/out-of-stock indicator
  - value: indicator_and_quantity
    label: Indicator and Quantity
    description: Show indicator and exact stock count

Property	Type	Required	Constraints	Description
`value`	string	Yes	min 1 char	Internal value stored when selected.
`label`	string	Yes	1-255 chars	Display label shown in backoffice.
`description`	string	No	max 500 chars	Additional explanation (for radio buttons).

Secret vs Storefront Behavior

`secret`	`storefront`	Behavior
`false`	`false`	Plain text in database. Accessible only via Zed (`getModuleConfig()` in Zed Config).
`false`	`true`	Plain text. Published to key-value storage. Accessible in all layers via `getModuleConfig()`.
`true`	`false`	Encrypted in database. Decrypted on read in Zed only. Never published to storage.
`true`	`true`	Invalid combination. Secrets are always excluded from storage.

Available Scopes

Built-in scopes (enabled out of the box):

Scope	Description	Requires Identifier
`global`	Application-wide default	No
`store`	Store-specific override (for example DE, AT)	Yes

Default hierarchy: store -> global -> default_value. Values resolve from most specific to least specific.

For adding custom scopes, see Adding Custom Scopes.

Constraints

Validated server-side when saving values through the Back Office.

constraints:
  - type: required
    message: Site name is required
  - type: min
    message: Must be at least 1
    options:
      min: 1
  - type: max
    message: Cannot exceed 100
    options:
      max: 100

Property	Type	Required	Constraints	Description
`type`	string	Yes	See table	Constraint type identifier.
`message`	string	Yes	1-500 chars	Error message shown when validation fails.
`options`	object	No	Depends on type	Constraint-specific parameters.

Built-in Constraint Types

Type	Description	Required Options	Example
`required`	Value must not be blank	–	Mandatory fields
`min`	Minimum numeric value	`min` (number)	`options: { min: 1 }`
`max`	Maximum numeric value	`max` (number)	`options: { max: 100 }`
`range`	Value within numeric range	`min`, `max` (number)	`options: { min: 0, max: 100 }`
`length`	String length limits	`min` and/or `max`	`options: { min: 6, max: 128 }`
`email`	Email format validation	–	Email input fields
`url`	URL format validation	–	URL input fields
`regex`	Pattern matching	`pattern` (string)	`options: { pattern: '^G-[A-Z0-9]{10}$' }`
`choice`	Value from allowed list	`choices` (string[])	`options: { choices: ['a', 'b'] }`

Dependencies

Control conditional visibility of settings in the Back Office UI. A setting with dependencies is only shown when at least one dependency rule matches (OR logic between rules). Each rule uses a when clause with any (OR) or all (AND) condition grouping.

settings:
  - key: stock_info_options
    name: Stock Info Options
    type: radio
    dependencies:
      - when:
          any:
            - setting: catalog:inventory:stock_options:display_stock_availability
              operator: equals
              value: "true"

Multiple conditions with all (AND logic):

    dependencies:
      - when:
          all:
            - setting: system:general:basic:feature_enabled
              operator: equals
              value: "true"
            - setting: system:general:basic:mode
              operator: not_equals
              value: maintenance

Dependency Rule

Property	Type	Required	Description
`when`	object	Yes	Contains `any` or `all` array of conditions.

When Clause

Property	Type	Required	Description
`any`	condition[]	No	Setting is shown if any condition matches (OR).
`all`	condition[]	No	Setting is shown if all conditions match (AND).

One of any or all must be provided.

Condition

Property	Type	Required	Description
`setting`	string	Yes	Compound key of the setting this depends on.
`operator`	string	Yes	Comparison operator.
`value`	string	Yes	Value to compare against.

Dependency Operators

Operator	Description
`equals`	Setting value must equal the given value.
`not_equals`	Setting value must not equal the given value.
`greater_than`	Numeric: value must be greater than expected.
`less_than`	Numeric: value must be less than expected.
`contains`	String: value must contain the expected text.
`in`	Value must be in the given list.

XSS Sanitization

Settings with type: text or type: string can have XSS sanitization applied on save. The sanitize_xss block configures how HTML content is cleaned using the W3C HTML Sanitizer API via spryker/util-sanitize-xss.

settings:
  - key: custom_html_block
    name: Custom HTML Block
    type: text
    sanitize_xss:
      allow_safe_elements: true
      allow_static_elements: false
      force_https_urls: true
      allow_relative_links: false
      allowed_link_schemes:
        - https
        - mailto
      allowed_link_hosts:
        - example.com
      allow_elements:
        a: [href, class]
        strong: []
      allow_attributes:
        data-custom: ['*']

Property	Type	Default	Description
`allow_safe_elements`	boolean	`false`	Allow W3C safe baseline elements.
`allow_static_elements`	boolean	`false`	Allow W3C static baseline elements.
`force_https_urls`	boolean	`false`	Rewrite `http://` URLs to `https://`.
`allow_relative_links`	boolean	`false`	Allow relative link URLs.
`allowed_link_schemes`	string[]	`[]`	Allowed URL schemes (for example `https`, `mailto`).
`allowed_link_hosts`	string[]	`[]`	Allowed link hostnames.
`allow_elements`	object	`{}`	Map of element name to allowed attribute names.
`allow_attributes`	object	`{}`	Map of attribute name to allowed element names (`*` for all).

Status Badges

Features, tabs, groups, and settings can display a status badge in the Back Office UI to indicate lifecycle stage. Badges are informational only and do not affect behavior.

Valid values: beta, early_access. Invalid values are silently ignored during schema normalization.

features:
  - key: ai_recommendations
    status: beta
    tabs:
      - key: model
        status: early_access

Badges render as colored pills next to item names in both the sidebar navigation and content area.

Schema File Locations

Location	Purpose	Loaded By
`{Module Folder}/resources/configuration/`	Core module schemas	`configuration:sync`
`data/configuration/`	Project-level schema overrides	`configuration:sync`

Project schemas override core schemas at the setting level. Settings with the same compound key are completely replaced.

Merged output: data/configuration/merged-schema.php

Backoffice Management

Settings are managed at The Back office > Configuration. The page provides:

Feature sidebar navigation with collapsible feature groups
Tabbed layout per feature
Scope switcher (global, store with identifier)
Input widgets matching setting types (including JSON editor with syntax highlighting)
Status badges on features, tabs, groups, and settings
Inline validation with constraint error messages
“Revert to default” to delete scope-specific overrides
Batch save with per-field error reporting
Global search across all settings (debounced AJAX, filters sidebar navigation)
Override detection: settings overridden by project-level Config classes are shown as read-only with an explanation notice
Dependent settings: conditional visibility with automatic change tracking
Audit logging: all save operations (successful and failed) are logged to the security audit channel

Search

The search input in the top bar filters the sidebar navigation as you type. Search matches against translated names and descriptions at all schema levels (feature, tab, group, setting), as well as setting compound keys. Results are scoped to the currently selected scope.

The search uses a debounced AJAX call to GET /configuration/manage/search?term={term}&scope={scope} which returns matching feature-to-tab mappings. Non-matching features and tabs are hidden in the sidebar.

Override Detection

During configuration:sync, the system scans core Config classes across Yves, Zed, Glue, and Client layers for methods that use getModuleConfig(). If a project-level Config class overrides such a method without calling getModuleConfig(), the setting is flagged as overridden.

Overridden settings in the Back Office:

Input is disabled (read-only)
“Use Default” link is hidden
A notice displays the project class and method responsible for the override

Override warnings are also printed to the console during configuration:sync:

[WARNING] Configuration bypass: catalog:inventory:stock_options:display_stock_availability
  Core:    SprykerShop\Yves\AvailabilityWidget\AvailabilityWidgetConfig::isStockDisplayEnabled
  Project: Pyz\Yves\AvailabilityWidget\AvailabilityWidgetConfig::isStockDisplayEnabled

Twig Integration

The Configuration module exposes three Twig functions that let templates read configuration values directly without going through a PHP Config class. They are available through the following existing plugins — no additional registration is required:

Context	Plugin
Storefront (Yves)	`ShopUiTwigExtension`
Back Office and Merchant Portal (Zed)	`\Spryker\Zed\Twig\Communication\Plugin\Application\TwigApplicationPlugin`

Function	Description
`configurationValue(key, default)`	Returns a single configuration value by compound key.
`configurationValues(keys)`	Returns an associative array of values for a list of compound keys.

`configurationValue`

Returns a single value for the given compound key. Falls back to default if the key has no saved value.

{{ configurationValue('theme:backoffice:colors:bo_main_color', '#1ebea0') }}

<style>
    :root {
        --bo-main-color: {{ configurationValue('theme:backoffice:colors:bo_main_color', '#1ebea0') | e('css') }};
    }
</style>

`configurationValues`

Returns an associative array keyed by compound key. Useful when a template needs several values at once.

{% set colors = configurationValues([
    'theme:backoffice:colors:bo_main_color',
    'theme:logos:logos:backoffice_logo_url',
]) %}
<style>:root { --bo-main-color: {{ colors['theme:backoffice:colors:bo_main_color'] | e('css') }}; }</style>

Scope context

Twig functions read values in the current request’s scope context. Store-specific values are resolved automatically when a store scope is active.

Data Import

Configuration values can be bulk-imported from CSV files using the Spryker DataImport framework.

CSV format

>setting_key,scope,scope_identifier,value
catalog:general:display:items_per_page,global,,24
catalog:general:display:items_per_page,store,DE,48

Column	Required	Description
`setting_key`	Yes	Compound key. Must exist in merged YAML schema.
`scope`	Yes	Must be in `ConfigurationConfig::getAvailableScopes()`.
`scope_identifier`	Conditional	Empty for `global`, required for other scopes.
`value`	Yes	Validated against schema constraints.

Running the import

docker/sdk cli console data:import configuration-value
docker/sdk cli console data:import configuration-value -f path/to/custom.csv

The default CSV file is located at data/import/configuration_value.csv at the project level. A module-level template is also provided.

Behavior

Values are validated with the same constraints as Back Office saves.
Secret settings are skipped with a warning — secrets should only be set via the UI.
Duplicate rows overwrite (upsert behavior).
Audit logging and Publish & Synchronize are triggered per value.
Import runs inside the existing ConfigurationValueWriter transaction, so all validation passes before any persistence.

For setup instructions, see Install the Configuration Management feature.

Console Commands

Command	Description
`configuration:sync`	Merges YAML schemas, generates the settings map, and detects project-level overrides. Run after any schema change.
`data:import configuration-value`	Bulk-imports configuration values from CSV.

Common Issues

Symptom	Cause	Solution
`getModuleConfig()` always returns default	Setting `storefront: false`	Yves/Glue can only read storefront-enabled settings. Set `storefront: true` or use Zed Config.
`getModuleConfig()` always returns default	Configuration module not installed	Expected behavior. Method gracefully falls back to `$default`.
Value returns `null` despite being saved	Key mismatch	Compound key format is `feature:tab:group:setting`. Verify all four segments match the YAML schema.
All values return `null` after a deployment, but the Back Office still displays them	Settings map missing in the deployed container	`data/configuration/settings-map.php` and `merged-schema.php` are excluded from the Git repository and the Docker image, so a fresh container has no settings map and every value resolves to `null` before decryption. The Back Office reads the stored row directly, which is why the UI and the runtime resolver disagree. Add `configuration:sync` to the cloud install recipes. See Install the Configuration Management feature.
Secret value empty in Yves	Expected behavior	Secrets are never published to storage. Access only via Zed.
Changes not visible after YAML edit	Schema not synced	Run `configuration:sync` after YAML changes.
Store-specific value not applied	Missing scope context	Pass `ConfigurationScopeTransfer` in third argument or register request expander plugins. See Adding Custom Scopes.
Setting visible despite `enabled: false`	Schema not synced	Run `configuration:sync`. The `enabled` flag is evaluated during sync and filtering.
Override notice on a setting	Project Config class bypasses `getModuleConfig()`	The project-level Config method overrides the core method without calling `getModuleConfig()`. Refactor the method to use `getModuleConfig()` or accept the override.

Upcoming major module releases

Fri, 31 Jul 2026 12:22:38 +0000

This document lists all upcoming [major module releases](/docs/dg/dev/architecture/module-api/semantic-versioning-major-vs.-minor-vs.-patch-release.html). Major module relesases may require additional development effort during an upgrade, so we recommend planning ahead. | MODULE | DATE | REASON FOR THE MAJOR VERSION | | --- | --- | --- | | ShopUi 2.0.0 | Aug 03 2026 | The frontend builder for Yves moves from the project's `frontend/` directory into the ShopUi module. Projects must point the `yves:*` npm scripts at the builder in the module, replace `frontend/settings.js` with `frontend/yves.settings.mts`, and run Node.js 24 or later. |

Install the SSP File Management feature

Fri, 31 Jul 2026 11:58:02 +0000

{% include pbc/all/install-features/latest/install-the-ssp-file-management-feature.md %}

Configure services

Thu, 30 Jul 2026 16:52:11 +0000

This document describes how to configure services shipped by default.

Prerequisites

Install or update the Docker SDK to the latest version:

git clone https://github.com/spryker/docker-sdk.git ./docker

Service versions

When configuring a service, you need to define its version. The Docker SDK supports the following service versions:

SERVICE	ENGINE	VERSIONS	ARM SUPPORT	NOTE
datab	postgres	17	✓
		10	✓
		11	✓
		12	✓
	mysql	5.7
		8.4
		mariadb-10.2	✓
		mariadb-10.3	✓
		mariadb-10.4	✓
		mariadb-10.5	✓
		mariadb-10.6	✓
		mariadb-10.11	✓
		mariadb-11.4	✓
		mariadb-11.8	✓
broke	rabbitmq	3.7
		3.8	✓
		3.9	✓
		4.1	✓
session	redis	5.0	✓
	valkey	7.2	✓
key_value_store	redis	5.0	✓
	valkey	7.2	✓
search	elastic	5.6*	✓	Policy and Product End of Life Dates
		6.8	✓	Policy and Product End of Life Dates
		7.6	✓
		7.10	✓
	opensearch	1.3	✓	Support Schedule
scheduler	jenkins	2.176
		2.305	✓
		2.324	✓
		2.516.3	✓
webdriver	phantomjs	latest*
	chromedriver	latest	✓
mail_catcher	mailhog	1.0	✓
swagger	swagger-ui	v3.24	✓
kibana	kibana	5.6*	✓
		6.8	✓
		7.6	✓
		7.10	✓
blackfire	blackfire	latest	✓

Database services

MariaDB is provided as a service by default. MariaDB is about 40% faster on write operations when compared, for example, to PostgreSQL.

You can switch to MySQL or PostgreSQL as described in the following sections.

MariaDB

MariaDB is a community-developed, commercially supported fork of the MySQL relational database management system.

For more details, see MariaDB knowledge base.

Default service

MariaDB is provided as a service by default. You may only need to use this configuration if you are running an older version of the Docker SDK or if you’ve previously switched to another database engine.

Configure MariaDB

To switch the database service to MariaDB, follow these steps:

In deploy.*.yml, adjust the services section:

...
services:
    database:
        engine: mysql
        version: mariadb-11.8
        ...
        endpoints:
            localhost:3306:
...

Bootstrap the docker setup, regenerate demo data, and rebuild the application:

docker/sdk boot deploy.*.yml
docker/sdk clean-data
docker/sdk up --build --data

MySQL

MySQL is an open-source relational database management system based on Structured Query Language (SQL). MySQL allows data to be stored and accessed across multiple storage engines, including InnoDB, CSV, and NDB. Also, MySQL can replicate data and partition tables for better performance and durability.

For more details, see MySQL documentation.

Configure MySQL

To switch the database engine to MySQL, follow these steps:

In deploy.*.yaml, adjust the services section:

...
services:
    database:
        engine: mysql
        ...
        endpoints:
            localhost:3306:
...

Bootstrap the docker setup, regenerate demo data, and rebuild the application:

docker/sdk boot deploy.*.yml
docker/sdk clean-data
docker/sdk up --build --data

PostgreSQL

PostgreSQL is an open-source object-relational database system that uses and extends the SQL language combined with many features that safely store and scale the most complicated data workloads.

For more details, see PostgreSQL documentation.

Configure PostgreSQL

To switch the database engine to PostgreSQL, follow these steps:

In deploy.*.yml, adjust the services section:

...
services:
    database:
        engine: postgres
        version: 17
        ...
        endpoints:
            localhost:5432:
...

Bootstrap the docker setup, regenerate demo data, and rebuild the application:

docker/sdk boot deploy.*.yml
docker/sdk clean-data
docker/sdk up --build --data

Elasticsearch

Elasticsearch is a search engine based on the Lucene library. It provides a distributed, multitenant-capable full-text search engine with an HTTP web interface and schema-free JSON documents.

For more information, see the following documents:

Configure Elasticsearch—describes ElastciSearch configuration in Spryker.
Elasticsearch documentation—provides detailed information about Elasticsearch.

Configure Elasticsearch

In deploy.*.yml, adjust the services section to open the port used for accessing Elasticsearch:

services:
    search:
        engine: elastic
        endpoints:
            localhost:9200
                protocol: tcp

Kibana UI

Kibana is an open-source analytics and visualization platform designed to work with Elasticsearch. You use Kibana to search, view, and interact with data stored in Elasticsearch indices. You can easily perform advanced data analysis and visualize your data in a variety of charts, tables, and maps.

For more information, see Kibana documentation.

In Docker SDK, Kibana UI is provided as a service by default.

Configure Kibana UI

To configure an endpoint for Kibana UI, follow these steps:

In deploy.*.yml, adjust the services section:

services:
    ...
    kibana:
        engine: kibana
        endpoints:
            {custom_endpoint}:

Add the endpoint to the hosts file:

echo "127.0.0.1 {custom_endpoint}" | sudo tee -a /etc/hosts

RabbitMQ

RabbitMQ is a messaging broker—an intermediary for messaging. It gives your applications a common platform to send and receive messages and your messages a safe place to live until received.

Configure RabbitMQ

In deploy.*.yml, adjust the services section to open the port used for accessing RabbitMQ:

services:
    broker:
    ...
        endpoints:
    ...
            localhost:5672:
                protocol: tcp
            api.queue.spryker.local:

Swagger UI

Swagger UI allows anyone—be it your development team or your end consumers—to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for backend implementation and client-side consumption.

For more details, see Swagger UI documentation.

In Docker SDK, Swagger UI is provided as a service by default.

Rest API Reference in Spryker

Spryker provides the basic functionality to generate OpenApi schema specification for REST API endpoints. This document provides an overview of REST API endpoints. For each endpoint, you can find the URL, REST request parameters as well as the appropriate request and response data formats.

Configure Swagger UI

To configure an endpoint for Swagger UI, follow these steps:

In deploy.*.yml, adjust the services section:

services:
    ...
    swagger:
        engine: swagger-ui
        endpoints:
            {custom_endpoint}:

Add the endpoint to the hosts file:

echo "127.0.0.1 {custom_endpoint}" | sudo tee -a /etc/hosts

Redis

Redis is an open-source (BSD licensed), in-memory data structure store used as a database, cache, and message broker. It supports data structures such as strings, hashes, lists, sets, sorted sets with range queries, bitmaps, hyperloglogs, geospatial indexes with radius queries, and streams.

For more information, see Redis documentation.

Configure Redis

In deploy.*.yml, adjust the services section to open the port used for accessing Redis:

services:
    key_value_store:
        engine: redis
        endpoints:
            localhost:16379:
                protocol: tcp

Redis GUI

Redis Commander is a web management tool that provides a graphical user interface to access Redis databases and perform basic operations like view keys as a tree, view CRUD keys, or import and export databases.

Configure Redis GUI

To configure an endpoint for Redis Commander, follow the steps:

In deploy.*.yml, adjust the services section:

services:
...
    redis-gui:
        engine: redis-commander
        endpoints:
            {custom_endpoint}: //redis-commander.spryker.local:

Adjust hosts file:

echo "127.0.0.1 {custom_endpoint}" | sudo tee -a /etc/hosts

MailHog

MailHog is a mail catcher service that is used with Spryker in Docker for Demo and Development environments. Developers use this email testing tool to catch and show emails locally without an SMTP (Simple Mail Transfer Protocol) server.

With the MailHog service, developers can do the following:

Configure an application to use MailHog for SMTP delivery.
View messages in the web UI or retrieve them via JSON API.

By default, the following applies:

http://mail.demo-spryker.com/ is used to see incoming emails.
Login is not required.

Configure MailHog

In deploy.*.yml, adjust the services section to specify a custom endpoint:

services:
        ...
        mail_catcher:
                engine: mailhog
                endpoints:
                          {custom_endpoint}:

Blackfire

Blackfire is a tool used to profile, test, debug, and optimize the performance of PHP applications. It gathers data about consumed server resources like memory, CPU time, and I/O operations. The data and configuration can be checked through the Blackfire web interface.

While we recommend Blackfire for PHP code profiling, Blackfire is not compatible with OpenTelemetry (OTel). If OTel resolves this compatibility in future, we will inform you. Meantime, for profiling needs compatible with OTel, we suggest using tools like Tideways, which can integrate seamlessly with your OTel-based monitoring stack.

Configure Blackfire

To enable Blackfire, follow these steps:

In the image section, adjust deploy.*.yml to enable the Blackfire PHP extension:

image:
    tag: spryker/php:7.4 # Use the same tag you had in `image`
    php:
        ...
        enabled-extensions:
            - blackfire

In deploy.*.yml, adjust the services section to configure the Blackfire client:

services:
    ...
    blackfire:
        engine: blackfire
        server-id: {server_id}
        server-token: {server_token}
        client-id: {client_id}
        client-token: {client-token}

Alternative configuration

Use the following configuration if you are going to change server or client details often or if you don’t want to define them in your deploy file.

To enable Blackfire, follow these steps:

In the image section, adjust deploy.*.yml to enable the Blackfire PHP extension:

image:
    tag: spryker/php:7.4 # Use the same tag you had in `image`
    php:
        ...
        enabled-extensions:
            - blackfire

In the services section, adjust deploy.*.yml to enable the Blackfire service:

services:
    ...
    blackfire:
        engine: blackfire

Pass Blackfire client details:

BLACKFIRE_CLIENT_ID={client_id} BLACKFIRE_CLIENT_TOKEN={client-token} docker/sdk cli

Pass Blackfire server details:

BLACKFIRE_SERVER_ID={client-token} BLACKFIRE_SERVER_TOKEN={server_token} docker/sdk up

You can pass the server details only with the docker/sdk up command.

It is not obligatory to pass all the details as environment variables or define all the details in the deploy file. You can pass the details in any combination.

New Relic

New Relic is a tool used to track the performance of services and the environment to quickly find and fix issues.

The solution consists of a client and a server. The client is used to collect data about applications in an environment and send it to the server for further analysis and presentation. The server is used to aggregate, analyse, and present the data.

Prerequisites

New Relic license key: NEWRELIC_LICENSE
NewRelic account ID: NEWRELIC_ACCOUNT_ID
NewRelic insights key: NEWRELIC_INSIGHTS_KEY
The New Relic module.

Install the New Relic module

While most environments come with New Relic already available, you may need to add the module to your project. Add the module to your composer.json:

composer require spryker-eco/new-relic

SCCOS: Configure New Relic

Adjust deploy.*.yml in the image: section:

image:
    ...
    php:
        ...
        enabled-extensions:
            ...
            - newrelic
    environment:
        ...
        NEWRELIC_CUSTOM_APP_ENVIRONMENT: ENVIRONMENT_VALUE_HERE # staging, dev, production, uat

Push and deploy the changes using one of the following guides:

Submit an infrastructure change request via the Support Portal. Set up a Change Request for existing Parameter Store values and request your values to be set for the following parameters:

NEWRELIC_LICENSE
NEWRELIC_ACCOUNT_ID
NEWRELIC_INSIGHTS_KEY

Once New Relic is enabled, in the New Relic dashboard, you may see either company-staging-newrelic-app or YVES-DE (docker.dev). New Relic displays these APM names by the application name setup in the configuration files.

If you update the name of an application, contact support to update the changes in your APM.

Local: Configure New Relic

In deploy.*.yml, adjust the docker section:

docker:
    newrelic:
        license: {new_relic_license}
      	distributed-tracing:
            enabled: true

In the deploy.*.yml, adjust the image section:

image:
    ...
    php:
        ...
        enabled-extensions:
            ...
            - newrelic

Configure distributed tracing

Distributed tracing follows a single request across all the services it touches and reports each unit of work as a span. Together with transaction traces, which capture the internal breakdown of a single transaction, it shows you where request time is spent and which service or code path causes a slowdown.

The New Relic PHP agent reads its distributed tracing configuration from environment variables, which the spryker/php image renders into newrelic.ini.

Prerequisites

The newrelic PHP extension is enabled in deploy.*.yml, and New Relic is configured as described in SCCOS: Configure New Relic or Local: Configure New Relic.
The spryker/php image includes the New Relic PHP agent 9.21.0 or later. For information about the agent version in your image, see Release notes for spryker-php image.

Distributed tracing environment variables

Distributed tracing and transaction traces are controlled with the following environment variables:

VARIABLE	DESCRIPTION	POSSIBLE VALUES	DEFAULT IN THE IMAGE
`NEWRELIC_DISTRIBUTED_TRACING_ENABLED`	Defines if distributed tracing is active. When disabled, requests are not linked across services and no trace context is propagated.	`1`, `0`	`0`
`NEWRELIC_SPAN_EVENTS_ENABLED`	Defines if span events are reported. Distributed tracing requires span events, so keep this enabled whenever distributed tracing is enabled.	`1`, `0`	`0`
`NEWRELIC_SPAN_EVENTS_MAX_SAMPLES_STORED`	Defines the maximum number of span events reported per harvest cycle. `0` applies the agent default of `2000`.	`0` to `10000`	Not set
`NEWRELIC_TRANSACTION_TRACER_ENABLED`	Defines if the transaction tracer is active. The transaction tracer records detailed traces of individual transactions.	`1`, `0`	`0`
`NEWRELIC_TRANSACTION_TRACER_THRESHOLD`	Defines the response time above which a transaction becomes eligible for tracing. `apdex_f` applies four times the apdex_t value of the application. A duration without a unit is interpreted as milliseconds.	`apdex_f`, or a duration such as `500`, `200ms`, or `1s250ms`	`0`
`NEWRELIC_TRANSACTION_TRACER_STACK_TRACE_THRESHOLD`	Defines the duration above which the agent records a full PHP stack trace for a segment. A value without a unit is interpreted as milliseconds.	A duration such as `500` or `500ms`	Not set
`NEWRELIC_TRANSACTION_TRACER_MAX_SEGMENTS_CLI`	Defines the maximum number of segments the agent records for CLI transactions, such as console commands and queue workers. Lower this value if long-running CLI processes consume too much memory.	A positive integer, for example, `100000`	Not set
`NEWRELIC_DISTRIBUTED_TRACING_EXCLUDE_NEWRELIC_HEADER`	Defines if the proprietary `newrelic` header is excluded from outbound requests, so that only W3C Trace Context headers are sent. Set it to `1` when you trace across services that do not support the New Relic header.	`1`, `0`	`0`

Set every variable explicitly

The spryker/php image overrides several New Relic agent defaults, and variables marked as Not set render as empty values in newrelic.ini. Because of this, the defaults of the New Relic PHP agent do not necessarily apply to your environment. Set every variable you rely on explicitly instead of depending on a default.

The NEWRELIC_TRANSACTION_TRACER_THRESHOLD default of 0 makes every transaction eligible for tracing. In production, set an explicit threshold, such as apdex_f or 500, to limit the volume of transaction traces.

Enable distributed tracing

In deploy.*.yml, adjust the image section:

image:
    tag: spryker/php:8.4
    php:
        enabled-extensions:
            - newrelic

    environment:
        NEWRELIC_DISTRIBUTED_TRACING_ENABLED: 1
        NEWRELIC_SPAN_EVENTS_ENABLED: 1
        NEWRELIC_SPAN_EVENTS_MAX_SAMPLES_STORED: 10000
        NEWRELIC_TRANSACTION_TRACER_ENABLED: 1
        NEWRELIC_TRANSACTION_TRACER_THRESHOLD: apdex_f
        NEWRELIC_TRANSACTION_TRACER_STACK_TRACE_THRESHOLD: 500
        NEWRELIC_TRANSACTION_TRACER_MAX_SEGMENTS_CLI: 100000
        NEWRELIC_DISTRIBUTED_TRACING_EXCLUDE_NEWRELIC_HEADER: 0

Adjust the values to the ones that suit your environment based on the available options in the preceding table.

Apply the changes:

Locally, rebuild the environment:

docker/sdk boot deploy.dev.yml && docker/sdk up

In Spryker Cloud Commerce OS, push and deploy the changes using one of the following guides:
- Deploying in a staging environment
- Deploying in a production environment

Verify the setup. In New Relic, open your APM entity and check that the Distributed tracing page lists recent traces of your application.

Configure New Relic application logging

New Relic application logging, also known as logs in context, lets the New Relic PHP agent collect logging metrics and forward application log records directly to New Relic. Because the agent adds correlation metadata to every forwarded record, you can switch between a log line, the transaction that produced it, and the related error or trace without switching tools.

Spryker applications write logs with Monolog, which the New Relic PHP agent instruments automatically. You do not need to add a log handler or change application code. The logs passed around Monolog, for example directly to stdout/stderr are not captured by the agent.

Distributed tracing is required

Application logging relies on the trace and span identifiers that the agent generates for each request. You must enable distributed tracing for logs in context to work. Set NEWRELIC_DISTRIBUTED_TRACING_ENABLED and NEWRELIC_SPAN_EVENTS_ENABLED to 1 as described in Configure distributed tracing. Without distributed tracing, forwarded log records cannot be correlated with transactions, errors, and traces.

Application logging is an addition to your existing logging setup, not a replacement for it. Log records are still written to your regular log destination. In Spryker Cloud Commerce OS, that destination is Amazon CloudWatch. For more details, see Working with logs.

Prerequisites

The newrelic PHP extension is enabled in deploy.*.yml, and New Relic is configured as described in SCCOS: Configure New Relic or Local: Configure New Relic.
Distributed tracing is enabled as described in Configure distributed tracing.
The spryker/php image includes the New Relic PHP agent 10.3.0 or later. For information about the agent version in your image, see Release notes for spryker-php image.

Application logging environment variables

Application logging is controlled with the following environment variables:

VARIABLE	DESCRIPTION	POSSIBLE VALUES	DEFAULT IN THE IMAGE
`NEWRELIC_APPLICATION_LOGGING_ENABLED`	Defines if the logs in context feature is active. When disabled, the other application logging variables have no effect.	`1`, `0`	Not set
`NEWRELIC_APPLICATION_LOGGING_METRICS_ENABLED`	Defines if logging metrics, such as the number of log records per severity level, are collected and displayed on the APM summary page.	`1`, `0`	Not set
`NEWRELIC_APPLICATION_LOGGING_FORWARDING_ENABLED`	Defines if log records are forwarded to New Relic together with linking metadata.	`1`, `0`	Not set
`NEWRELIC_APPLICATION_LOGGING_FORWARDING_LOG_LEVEL`	Defines the lowest severity level to forward. The agent forwards records of the specified level and all higher severity levels.	`EMERGENCY`, `ALERT`, `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, `DEBUG`	Not set

Data ingest volume

Log forwarding increases the amount of data ingested by New Relic, which can affect your New Relic costs. Lower severity levels, especially INFO and DEBUG, produce a significantly higher volume than WARNING and above. Start with WARNING and lower the level only for the period during which you need the additional detail.

Enable application logging

In deploy.*.yml, adjust the image section:

image:
    tag: spryker/php:8.4
    php:
        enabled-extensions:
            - newrelic

    environment:
        NEWRELIC_DISTRIBUTED_TRACING_ENABLED: 1
        NEWRELIC_SPAN_EVENTS_ENABLED: 1
        NEWRELIC_SPAN_EVENTS_MAX_SAMPLES_STORED: 10000
        NEWRELIC_TRANSACTION_TRACER_ENABLED: 1
        NEWRELIC_APPLICATION_LOGGING_ENABLED: 1
        NEWRELIC_APPLICATION_LOGGING_METRICS_ENABLED: 1
        NEWRELIC_APPLICATION_LOGGING_FORWARDING_ENABLED: 1
        NEWRELIC_APPLICATION_LOGGING_FORWARDING_LOG_LEVEL: WARNING

Adjust the values to the ones that suit your environment based on the available options in the preceding table.

Apply the changes:

Locally, rebuild the environment:

docker/sdk boot deploy.dev.yml && docker/sdk up

In Spryker Cloud Commerce OS, push and deploy the changes using one of the following guides:
- Deploying in a staging environment
- Deploying in a production environment

Verify the setup. In New Relic, open your APM entity and check the following:

The Logs tab contains recent log records from the application.
On the Summary page, the Log chart displays log record counts per severity level.

Disable application logging

To stop collecting and forwarding logs, set NEWRELIC_APPLICATION_LOGGING_ENABLED to 0 and deploy the change:

image:
    ...
    environment:
        ...
        NEWRELIC_APPLICATION_LOGGING_ENABLED: 0

To keep logging metrics on the APM summary page but stop forwarding log records, keep NEWRELIC_APPLICATION_LOGGING_ENABLED set to 1 and set NEWRELIC_APPLICATION_LOGGING_FORWARDING_ENABLED to 0.

For more details about the underlying agent settings, see PHP agent configuration in the New Relic documentation.

Configure YVES, ZED, and GLUE as separate APMs

By default, in the New Relic dashboard, the APM is displayed as company-staging-newrelic-app. To improve visibility, you may want to configure each application as a separate APM. For example, YVES-DE (docker.dev).

To do it, add the NewRelicMonitoringExtensionPlugin by creating the class src/Pyz/Service/Monitoring/MonitoringDependencyProvider.php:

<?php declare(strict_types = 1);
​
/**
 * This file is part of the Spryker Commerce OS.
 * For full license information,  view the LICENSE file that was distributed with this source code.
 */
​
namespace Pyz\Service\Monitoring;
​
use Spryker\Service\Monitoring\MonitoringDependencyProvider as SprykerMonitoringDependencyProvider;
use Pyz\Service\NewRelic\Plugin\NewRelicMonitoringExtensionPlugin;
​
class MonitoringDependencyProvider extends SprykerMonitoringDependencyProvider
{
    /**
     * @return \Spryker\Service\MonitoringExtension\Dependency\Plugin\MonitoringExtensionPluginInterface[]
     */
    protected function getMonitoringExtensions(): array
    {
        return [
            new NewRelicMonitoringExtensionPlugin(),
        ];
    }
}

Next, create the class src/Pyz/Service/NewRelic/Plugin/NewRelicMonitoringExtensionPlugin.php

<?php
​
/**
 * MIT License
 * For full license information,  view the LICENSE file that was distributed with this source code.
 */
​
namespace Pyz\Service\NewRelic\Plugin;
​
use SprykerEco\Service\NewRelic\Plugin\NewRelicMonitoringExtensionPlugin as SprykerNewRelicMonitoringExtensionPlugin;
​
class NewRelicMonitoringExtensionPlugin extends SprykerNewRelicMonitoringExtensionPlugin
{
    /**
     * @param string|null $application
     * @param string|null $store
     * @param string|null $environment
     *
     * @return void
     */
    public function setApplicationName(?string $application = null, ?string $store = null, ?string $environment = null): void
    {
        if (!$this->isActive) {
            return;
        }
​
        // Custom application environment name, or use $environment as fallback
        $environment = getenv('NEWRELIC_CUSTOM_APP_ENVIRONMENT') ?: $environment;
​
        $this->application = $application . '-' . $store . ' (' . $environment . ')';
​
        newrelic_set_appname($this->application, '', false);
    }
}

Some builds have the Monitoring service built into the Yves application. If src/Pyz/Service/Monitoring/MonitoringDependencyProvider.php does not exist, you may want to check src/Pyz/Yves/Monitoring/.
If the class is missing from the Monitoring service, create it.

With new \SprykerEco\Service\NewRelic\Plugin\NewRelicMonitoringExtensionPlugin() being returned with the getMonitoringExtensions() function, the Monitoring class includes New Relic. Now applications are displayed as separate APMs, and an appropriate endpoint or class is displayed with each transaction.

Track deployments

To notify New Relic about new deployments, include the console command \SprykerEco\Zed\NewRelic\Communication\Console\RecordDeploymentConsole in \Pyz\Zed\Console\ConsoleDependencyProvider as follows:

namespace Pyz\Zed\Console;

...
use SprykerEco\Zed\NewRelic\Communication\Console\RecordDeploymentConsole;
...

class ConsoleDependencyProvider extends SprykerConsoleDependencyProvider
{
...
    protected function getConsoleCommands(Container $container): array
    {
        $commands = [
	    ....
            new RecordDeploymentConsole(),
        ];
	....
        return $commands;
    }
....
}

From now on you can use the record deployment functionality built-in in the console command, as follows:

vendor/bin/console newrelic:record-deployment <AppName>

where AppName corresponds to the preconfigured in NewRelicEnv::NEW_RELIC_APPLICATION_ID_ARRAY. For more details, see Upgrade the Monitoring module

Webdriver

PhantomJS is provided as a webdriver service by default, but you can switch to ChromeDriver as described below.

ChromeDriver

ChromeDriver is a thin wrapper on WebDriver and a Chromium headless browser. It is used for automating web page interaction, JavaScript execution, and other testing-related activities. It provides full-control API to make end-to-end testing flexible and comfortable.

Configure ChromeDriver

To enable Chromedriver, adjust deploy.*.yml as follows:

services:
    webdriver:
        engine: chromedriver

PhantomJS

PhantomJS is a headless browser for automating web page interaction. It ships with a WebDriver based on Selenium.

Configure PhantomJS

To enable PhantomJS, adjust deploy.*.yml as follows:

services:
    webdriver:
        engine: phantomjs

Dashboard

Dashboard is a tool that helps to monitor logs in real time. You can monitor logs in all or a particular container.

Configure dashboard

To configure Dashboard, in the services section, adjust deploy.*.yml:

services:
    dashboard:
            engine: dashboard
            endpoints:
                {custom_endpoint}:

Tideways

Tideways is an application profiler used for testing and debugging. Its main functions are profiling, monitoring, and exception tracking.

Configure Tideways

To configure Tideways, do the following:

In deploy.*.yml, adjust the services section:

services:
    tideways:
        apikey: {tideways_api_key}
        engine: tideways
        environment-name: {tideways_environment_name}
        cli-enabled: {true|false}

In the image section of deploy.*.yml, add Tideways to the list of enabled extensions:

image:
    tag: spryker/php:7.4 # the image tag was previously used in `image`
    php:
        ...
        enabled-extensions:
            - tideways

Monitoring

Thu, 30 Jul 2026 14:51:41 +0000

Effective monitoring is crucial for maintaining the health and performance of your Spryker applications. This page provides access to resources and integrations that enable comprehensive monitoring through logs and application performance metrics. ## Application Performance Monitoring Application Performance Monitoring (APM) provides near real-time insights into the performance of your applications, helping you quickly identify and resolve issues. ### Spryker Monitoring based on OpenTelemetry Integrate Spryker monitoring data into your preferred APM tool using OpenTelemetry for flexible and comprehensive application performance monitoring. For more details, see [Spryker Monitoring Integration](/docs/ca/dev/monitoring/spryker-monitoring-integration.html). ### New Relic APM Use New Relic's powerful APM features to monitor and troubleshoot your applications. For more details, see [New Relic](/docs/dg/dev/integrate-and-configure/configure-services.html#new-relic). You can also forward application log records to New Relic and correlate them with transactions, errors, and traces. For more details, see [Configure New Relic application logging](/docs/dg/dev/integrate-and-configure/configure-services.html#configure-new-relic-application-logging). ## Logs with CloudWatch CloudWatch offers robust logging capabilities, allowing you to track, store, and analyze logs from your applications and services. For more information on CloucWatch logs, see [Working with Logs](/docs/ca/dev/monitoring/working-with-logs.html). ## Monitoring issues and informing about alerts Spryker applications are monitored 24/7 by a dedicated team. To learn how monitoring works and what is monitored, see [Monitoring issues and informing about alerts](/docs/ca/dev/monitoring/monitoring-issues-and-informing-about-alerts.html).

Deploy file reference

Thu, 30 Jul 2026 14:51:41 +0000

This reference page describes version 1 of the Deploy file format. This is the newest version.

Glossary

Deploy file: A YAML file defining Spryker infrastructure and services for Spryker tools used to deploy Spryker applications in different environments.
Region: Defines one or more isolated instances of Spryker applications that have only one persistent database to work with; limits the visibility of a project's Stores to operate only with the Stores that belong to a Region; refers to geographical terms like data centers, regions and continents in the real world.
Group: Defines a group of Spryker applications within a Region that is scaled separately from other groups; can be assumed as an auto scaling group in the Cloud.
Store: A store related context a request is processed in.
Application: A Spryker application, like Backoffice(Zed), Backend-Gateway, Yves, GlueStorefront(Glue), GlueBackend or MerchantPortal.
Service: An external storage or utility service. Represents service type and configuration. The configuration can be defined on different levels: project-wide, region-wide, store-specific or endpoint-specific with limitations based on the service type.
Endpoint: A point of access to Application or Service. The key format is domain[:port]. By default, the port for HTTP endpoints is 80 . Port is mandatory for TCP endpoints.

Deploy file structure

The topics below are organized alphabetically for top-level keys and sub-level keys to describe the hierarchy.

You can use the extended YAML syntax according to YAML™ Version 1.2. Find B2B and B2C deploy file examples for development and demo environments in the table:

DEVELOPMENT MODE	DEMO MODE
B2C Demo Shop deploy file	B2C Demo Shop deploy file
B2B Demo Shop deploy file	B2B Demo Shop deploy file

version:

Defines the version of the Deploy file format.

This reference page describes the Deploy file format for versions 1.*.

This variable is optional. If not specified, the default value applies: version: "0.1".

version: 1.0

namespace: spryker-demo
...

namespace:

Defines the namespace to separate different deployments in a single environment.

For example, Docker images, containers and volume names start with a namespace: to avoid intersections between different deployments on a single host machine.

This variable is optional. If not specified, the default value applies: namespace: spryker.

version: 1.0
namespace: spryker-demo

tag:

Defines a tag to separate different boots for a single deployment.

By default, the tag is a randomly generated, unique value.

For example, Docker images and volumes are tagged with a tag: to avoid intersections between different boots for a single deployment on a single host machine. The tag can be set directly in the deploy file to ensure that all the boots of a deployment run with the same images and volumes.

This variable is optional. If not specified, the default value applies: tag: '1.0'.

version: 1.0

tag: '1.0'

version: 1.0

tag: 'custom-one'

environment:

Defines the environment name for Spryker applications mainly to point to specific configuration files, namely config/Shared/config-default_{environment_name}_{store}.php.

The APPLICATION_ENV environment variable is set for all the corresponding Spryker applications.

This variable is optional. If not specified, the default value applies: environment: 'docker'.

version: 1.0

environment: 'docker'

environment-configuration: secrets:

Defines secrets and their configuration:

environment-configuration: secrets: name:—secret’s name.
environment-configuration: secrets: grant:—users’ permissions. limited provides read while public provides read and write permissions. The default one is limited.
environment-configuration: secrets: bucket:—defines what the secret is used for. The acceptable value is app.

environment-configuration: params:

Defines parameters and their configuration:

environment-configuration: params: name:—parameter’s name.
environment-configuration: params: bucket:—defines what the parameter is used for. The acceptable value is app.
environment-configuration: params: default:—parameter’s default value. Accepts string, number, and json values.
environment-configuration: params: grant:—IAM users’ permissions. limited provides read while public provides read and write permissions. The default one is limited.

imports:

Defines any of the following:

Imports of additional deploy files to be included into a build. Supports imports of the same deploy file multiple times. To define a deploy file and dynamic parameters for this type of import, see imports: {import_name}:.

imports:
    {import_name}:
    {import_name}:       

Additional deploy files to be included into a build. To define dynamic parameters for this type of import, see imports: {deploy_file_name}:.

version: 1.0
imports:
    {deploy_file_name}:
    {deploy_file_name}:

An array of additional deploy files to be included into a build. Supports imports of the same deploy file multiple times. To define dynamic parameters for this type of import, see imports: parameters:

imports:
    - template: {deploy_file_name}
    - template: {deploy_file_name}

The files must exist on a project or base layer.

Merged deploy files

If you include a deploy file, the included deploy file is merged with the original one. The final deploy file is used to build the application. To check how the final deploy file looks without stopping containers, run docker config {DEPLOY_FILE_NAME}. For example, if your main deploy file is deploy.dev.yml, run docker config deploy.dev.yml. The command parses the included deploy files and returns the merged file and validation errors, if any.

imports: parameters:

Defines the dynamic parameters to be used when parsing the included deploy file. In the included deploy file, the parameter name should be wrapped in %.

imports:
  - template: {deploy_file_name}
    parameters:
      {dynamic_parameter_name}: '{dynamic_parameter_value}'
      {dynamic_parameter_name}: '{dynamic_parameter_value}'

Example:

imports:
  - template: deploy.porject.yml
    parameters:
      env-name: 'dev'
      locale: 'en'

Affects the included deploy file that it follows in an array of included deploy files. To learn how you can add dynamic parameters for other types of imports, see imports: {import_name}: and imports: {deploy_file_name}:.

imports: {import_name}:

Defines the configuration of the import:

{import_name}: template:—defines the deploy file to be included into a build as part of this import.
{import_name}: parameters:—defines the dynamic parameters to be used when parsing the included deploy file. In the included deploy file, the parameter name should be wrapped in %.

imports:
    {import_name}:
        template: {deploy_file_name}
        parameters:
          {dynamic_parameter_name}: '{dynamic_parameter_value}'
          {dynamic_parameter_name}: '{dynamic_parameter_value}'

Example:

imports:
    base:
        template: deploy.base.template.yml
        parameters:
          env_name: 'dev'
          locale: 'en'

imports: {deploy_file_name}:

Defines the configuration to be used when parsing the included deploy file.

{deploy_file_name}: parameters:—defines the dynamic parameters to be used when parsing the included deploy file. In the included deploy file, the parameter name should be wrapped in %.

version: 1.0
imports:
    {deploy_file_name}:
      parameters:
        {dynamic_parameter_name}: '{dynamic_parameter_value}'
        {dynamic_parameter_name}: '{dynamic_parameter_value}'  

Example:

version: 1.0
imports:
    deploy.base.template.yml:
      parameters:
        env_name: 'dev'
        locale: 'en'

image:

Defines the Docker image configuration to run Spryker applications in.

image:tag

Defines the image tag according to the spryker/php images located at Docker Hub.

This variable is optional. If not specified, the default value applies: image: spryker/php:7.3.

version: 1.0

image:
    tag: spryker/php:7.3

image: environment:

Defines additional environment variables for Spryker applications.

version: 1.0

image:
  environment:
        {env_variable}: {env_variable_value}

image: node:

Defines Node.js settings.

image: node: version:—defines a Node.js version. Supports only major versions that are greater than the default one. The default version is 12.
image: node: npm—defines a npm version. Supports only major versions that are greater than the default one. The default version is 6.
image: node: distro:—defines a Linux distribution for the Node Docker image. Should be equal to your base PHP image. Possible values are alpine and debian. This variable is optional with the default value of alpine.

image:
    ...
    node:
        version: 18
        distro: alpine
        npm: 8

image: php:

Defines PHP settings.

Memory Limits

The maximum recommended PHP memory limit’s 2048M. Going above this limit’s rarely necessary and can lead to stability and performance issues in your environment. Test any configuration change carefully in a non-production setting.

image: php: ini:—defines php.ini configuration.
image: php: enabled-extensions—defines enabled PHP extensions. The following extensions are allowed:
- blackfire
- newrelic
- tideways

image:
    ...
    php:
        ini:
            memory_limit: 2048M
        enabled-extensions:
            - blackfire
            - newrelic
            - tideways

assets:

Defines the configuration of the frontend (nginx) container. Despite its name, this section configures the nginx reverse proxy that handles all incoming HTTP requests to the application, not only static assets. The frontend container does the following:

Proxies dynamic requests to application containers (Yves, Zed, Glue, and others) through FastCGI.
Serves pre-built static assets (JS, CSS, images, fonts).
Applies HTTP response compression to both static files and dynamic responses from applications.

Compression affects all responses

The compression configuration under assets controls nginx compression for all HTTP responses passing through the frontend container. This includes dynamically generated HTML pages, API responses, and other content served by application containers, not only static assets. When compression is misconfigured or disabled, all responses leave the infrastructure uncompressed, which can significantly increase data transfer volume and response latency, especially when a CDN or traffic management solution like Akamai or Cloudflare is used in front of the application. For more details, see CDN and traffic management integration.

assets: image:—defines a Docker image for the frontend container. If not specified, the default value applies: assets: image: nginx:alpine. To enable Brotli compression support, use an image that includes the Brotli nginx module, for example: spryker/nginx-brotli:latest.
assets: mode:—defines a mode for running a static build section from the install recipe. Possible values are production and development. This variable is optional with the default value of development.
assets: compression:—defines compression engines for HTTP responses. Supported engines are gzip and brotli. You can configure both engines simultaneously. The frontend container negotiates the encoding with the client based on the Accept-Encoding request header and responds with the best mutually supported encoding.

Compression engine parameters:

assets: compression: {engine}: static:—controls compression behavior for the engine. Allowed values are as follows:
- true (default)—compresses responses on the fly and serves pre-compressed static files (.gz or .br) when available. This is the recommended setting for most deployments because it ensures both static assets and dynamic responses (HTML, JSON, XML) are compressed.
- only—serves only pre-compressed static files. On-the-fly compression is disabled. Dynamic responses from applications (HTML pages, API responses) are not compressed. Use this only when you want to avoid CPU overhead from on-the-fly compression and you are certain that a downstream service (such as a CDN) handles compression of dynamic content.
- false—disables the compression engine entirely. No compression is applied for this engine.
assets: compression: {engine}: level:—defines a compression level. Allowed range is from 1 (fastest, least compression) to 9 (slowest, best compression). The default is 5.
assets: compression: {engine}: types:—defines additional MIME types to be compressed beyond the defaults. Default types include text/html, text/plain, text/css, text/javascript, application/javascript, application/json, application/xml, image/svg+xml, and others.

Content negotiation:

When a client (browser, CDN, or other HTTP client) sends a request with an Accept-Encoding header, the frontend container selects the best available compression:

If the client sends Accept-Encoding: br and Brotli is enabled, the response is Brotli-compressed.
If the client sends Accept-Encoding: gzip and gzip is enabled, the response is gzip-compressed.
If the client does not send Accept-Encoding or requests an unsupported encoding, the response is sent uncompressed.

The frontend container adds Vary: Accept-Encoding to compressed responses so that intermediary caches (CDNs, proxies) correctly cache different representations.

Example configuration:

assets:
    image: spryker/nginx-brotli:latest
    mode: production
    compression:
        gzip:
            static: true
            level: 5
        brotli:
            static: true
            level: 5

This configuration enables both gzip and Brotli for all responses, including dynamically generated HTML and API responses. With both engines enabled, the frontend container automatically selects the best encoding based on the client’s Accept-Encoding header.

regions:

Defines the list of Regions.

regions: services:—defines settings for Region-specific services:. Only database: and mail: sender: are allowed here.
- regions: services: database:—see database: on this page.
- regions: services: mail: sender:—defines the mail sender configuration. Possible values are name: and email:.
regions: stores:—defines the list of Stores.
regions: stores: services:—defines application-wide, Store-specific settings for Services. Only broker:, key_value_store: and search: are currently allowed here. See services: to learn more.

version: "1.0"

regions:
  REGION-1:
    services:
      # Region-specific services settings

    stores:
      STORE-1:
        services:
          # Store-specific services settings
      STORE-2:
        services:
          # Store-specific services settings

groups:

Defines the list of Groups.

groups: region:—defines the relation to a Region by key.
groups: applications:—defines the list of Applications. See groups: applications: to learn more.

version: "1.0"

groups:
  BACKEND-1:
    region: REGION-1
    applications:
      backoffice_1:
        application: backoffice
        endpoints:
          backoffice.store1.spryker.local:
            store: STORE-1
            services:
              # Application-Store-specific services settings
          backoffice.store2.spryker.local:
            store: STORE-2
            services:
              # Application-Store-specific services settings
  STOREFRONT-1:
    region: REGION-1
    applications:
      yves_1:
        application: yves
        endpoints:
          yves.store1.spryker.local:
            store: STORE-1
            services:
              # Application-Store-specific services settings
          yves.store2.spryker.local:
            store: STORE-2
            services:
              # Application-Store-specific services settings
      glue_1:
        application: glue
        endpoints:
          glue.store1.spryker.local:
            store: STORE-1
          glue.store2.spryker.local:
            store: STORE-2

Applications can be defined as Store-agnostic, as in the example above. Also, applications can be defined as Store-specific by leaving a single endpoint pointing to each application. You can see it in the example below. You can use both approaches to scale applications separately by Store.

version: "1.0"

groups:
  BACKEND-1:
    region: REGION-1
    applications:
      backoffice_store_1:
        application: backoffice
        endpoints:
          backoffice.store1.spryker.local:
            store: STORE-1
      backoffice_store_2:
        application: backoffice
        endpoints:
          backoffice.store2.spryker.local:
            store: STORE-2

groups: applications:

Defines the list of Applications.

The key must be project-wide unique.

Obligatory parameters for application::

groups: applications: application:—defines the type of Application. Possible values are backoffice, backend-gateway, zed, yves, glue-storefront, glue-backend,glue and merchant-portal.
groups: applications: endpoints:—defines the list of Endpoints to access the Application. See groups: applications: endpoints: to learn more.

Optional parameters for application::

groups: applications: application: application:—defines if the application is static. Only static is allowed here.
groups: applications: application: endpoints: endpoint: entry-point:—defines an entry-point, the path to the index directory of the application.
groups: applications: application: endpoints: endpoint: redirect:—defines redirect rules.
groups: applications: application: endpoints: endpoint: redirect: code—defines an HTTP code for a redirect. Allowed values are 301 and 302.
groups: applications: application: endpoints: endpoint: redirect: url—defines a URL to redirect to.
groups: applications: application: endpoints: real-ip: from:—defines gateway IP addresses to fetch the real IP address.
groups: applications: application: endpoints: auth:—defines the basic auth.
groups: applications: application: endpoints: auth: engine:—defines an engine for the basic auth. Only one of the following is allowed per an endpoint: basic or whitelist.
- Basic auth variables:
  - groups: applications: application: endpoints: auth: users:—defines user credentials for basic auth.
    - groups: applications: application: endpoints: auth: users: username:—defines a username for basic auth.
  - groups: applications: application: endpoints: auth: users: password:—defines a password for basic auth.
  - groups: applications: application: endpoints: auth: exclude:—defines the IPs from which clients can access the endpoint bypassing the basic auth.
- Whitelist auth variables:
  - groups: applications: application: endpoints: auth: include:—defines the IPs to allow access from.
groups: applications: application: endpoints: primal:—defines if a ZED endpoint is primal for a store. Yves and Glue applications send Zed RPC calls to the primal endpoint. This variable is optional with the default value of false. If no endpoint is defined as primal for a store, the first endpoint in descending order is considered primal.
groups: applications: application: http: max-request-body-size:—defines the maximum allowed size of the request body that can be sent to the application, in MB. If not specified, the default values apply:
backoffice—10m
- merchant-portal—10m
glue-storefront—10m
glue-backend—10m
glue—2m
yves—1m

...
    applications:
      backoffice:
        application: backoffice
        http:
          max-request-body-size: 20m
        endpoints:
          backoffice.store1.spryker.local:
            store: STORE-1

To disable the validation of request body size against this parameter, set it to 0. We don’t recommended disabling it.

groups: applications: application: limits: workers—defines the maximum number of concurrent child processes a process manager can serve simultaneously.

...
    applications:
      zed:
        application: zed
        limits:
            workers: 4
        ...

In cloud environments, increasing the number of workers requires infrastructure changes. Increasing the number of workers should be thoroughly tested beforehand and may have drastic impact on your application’s resource requirements. Coordinate this change with our Operations team using the Infrastrucute Change Request (Change to existing Parameter Store Variable).
Increase this number if you are getting the following error in logs: server reached pm.max_children setting.
We recommend the following increase steps: 4, 8, 12.

services:

Defines the list of Services and their project-wide settings.

Each service has its own set of settings to be defined. See Services to learn more.

Find common settings for all services below:

engine:—defines a third-party application supported by Spryker that does the job specific for the Service. For example, you can currently set database:engine: to postgres or mysql.
endpoints:—defines the list of Endpoints that point to the Service web interface or port.
version:—defines the version of the service to be installed. If database:engine: is set to mysql, also defines if MySQL or MariaDB is used according to the version. See Database on this page for detailed configuration instructions. This variable is optional. If not specified, the default version applies.

services:
    database:
        engine: postgres
        version: 17
        root:
            username: "root"
            password: "secret"

    broker:
        engine: rabbitmq
        api:
            username: "root"
            password: "secret"
        endpoints:
            queue.spryker.local:

  session:
    engine: redis
    version: 5.0

  key_value_store:
    engine: redis

  search:
    engine: elastic
    version: 6.8

  scheduler:
    engine: jenkins
    version: 2.176
    endpoints:
      scheduler.spryker.local:

  mail_catcher:
    engine: mailhog
    endpoints:
      mail.spryker.local:

After changing a service version, make sure to re-import demo data:

Remove all Spryker volumes:

docker/sdk clean-data

Populate Spryker demo data:

docker/sdk demo-data

You can extend service settings on other levels for specific contexts. See regions: services:, regions: stores: services: and groups: applications: endpoints: services: to learn more.

groups: applications: endpoints:

Defines the list of Endpoints to access the Application.

The format of the key is domain[:port]. The key must be project-wide unique.

groups: applications: endpoints: store: defines the Store as context to process requests within.
groups: applications: endpoints: services: defines the Store-specific settings for services. Only session: is currently allowed here. See Services to learn more.
groups: applications: endpoints: cors-allow-origin: defines a CORS header. It is allowed for glue application only. Possible values are:
- Single domain as a string
- * – allows all domains

Allowing all domains

For security reasons, we recommend allowing all domains only as a temporary workaround. As a permanent solution:

Define the desired domains as separate endpoints with separate CORS headers.
Define the desired domains on the application level

services: endpoints:

Defines the list of Endpoints to access a Service for development or monitoring needs. The format of the key is domain[:port]. The key must be project-wide unique.

services: endpoints: protocol: defines the protocol. Possible values are: tcpand http. The default one is http.

A port must be defined if protocol is set to tcp. The TCP port must be project-wide unique.

docker:

Defines the settings for Spryker Docker SDK tools to make deployment based on Docker containers.

version: 1.0

docker:

  ssl:
    enabled: true

  testing:
    store: STORE-1

  mount:
    baked:

docker: newrelic:

Defines the New Relic configuration.

docker: newrelic: license:—defines a New Relic license. Aquire it from New Relic.
docker: newrelic: appname:—defines a New Relic application name. This variable is optional and does not have a default value.
docker: newrelic: enabled:—defines if Newrelic is enabled. Possible values are true and false. This variable is optional with the default value of true.
docker: newrelic: distributed-tracing: enabled—defines if New Relic distributed tracing is enabled. Possible values are true and false.
docker: newrelic: distributed-tracing: exclude-newrelic-header—defines if New Relic distributed tracing headers are enabled. Possible values are true and false. For information about the headers, see How trace context is passed between applications.
docker: newrelic: distributed-tracing: transaction-tracer-threshold—defines the New Relic transaction tracer threshold. Accepts numeric values starting from 0. For information about the threshold, see Configure transaction traces.

docker:
    newrelic:
        license: eu01xxaa7460e1ea3abdfbbbd34e85c10cd0NRAL

This section covers only a subset of the New Relic agent settings. To configure distributed tracing, transaction traces, or application logging in detail, define the corresponding environment variables in image: environment:. For more details, see Configure distributed tracing and Configure New Relic application logging.

docker: ssl:

Defines configuration for SSL module in Spryker Docker SDK.

If docker: ssl: enabled: is set to true, all endpoints use HTTPS.

This variable is optional. If not specified, the default value applies: enabled: false.

version: 1.0

docker:
  ssl:
    enabled: true

To enable secure connection in your browser, register the self-signed CA certificate from ./docker/generator/openssl/default.crt in your system.

docker: debug:

Defines the configuration for debugging.

If docker: debug: enabled: is set to true, all applications work in debugging mode.

version: 1.0

docker:
  debug:
    enabled: true

docker: debug: xdebug: enabled:—defines if Xdebug is enabled.

docker: maintenance: enabled:

Defines if applications work in maintenance mode. The default value is false.

version: 1.0
docker:
    maintenance:
        enabled: {true | false}

docker: maintenance: whitelist: ips:

Defines the IPs from which the application in the maintenance mode can be accessed.

version: 1.0

docker:
    maintenance:
        enabled: true
        whitelist:
          ips:
              - {IP_ADDRESS}
              - {IP_ADDRESS}

docker: logs:

docker: logs: path: defines the path to the directory with Docker logs. This variable is optional. If not specified, the default value applies: path: '/var/log/spryker.

docker: testing:

Defines the configuration for testing.

docker: testing: store: defines a Store as the context for running tests using specific console commands, like docker/sdk console code:test. This variable is optional. If not specified, the default value applies: store: DE.

docker: mount:

Defines the mode for mounting source files into application containers.

baked:- source files are copied into the image, so they cannot be changed from host machine. This variable is optional. If not specified, the default value applies: baked:baked.
native:- source files are mounted from host machine into containers directly. We recommend using it Linux.
docker-sync:- source files are synced from host machine into containers during runtime. Use it as a workaround solution with MacOS and Windows.
mutagen:- source files are synced from the host machine into running containers. Use it as a workaround for MacOS and Windows.

As mount: is a platform-specific setting. You can define multiple mount modes. Use theplatforms: list to define a mount mode for a platform. Possible platforms are windows, macos, and linux.

The first mount mode matching the host platform is selected by default.

version: 1.0

docker:
  mount:
    native:
      platforms:
        - linux
        mutagen:
            platforms:
                - macos
    docker-sync:
      platforms:
        - windows

composer:

Defines the composer settings to be used during deployment.

mode:—defines whether packages should be installed from the require or require-dev section of composer.json. Possible values are --no-dev and -dev. This variable is optional. If not specified, the default values apply:

[Development mode]: mode: --dev
- [Demo mode]: mode: --no-dev

autoload:—defines composer autoload options. Possible values are --optimize and --classmap-authoritative. This variable is optional. If not specified, the default values apply:

Development mode: autoload: --optimize
- Demo mode: autoload: --classmap-authoritative

Services

You can configure and use external tools that are shipped with Spryker in Docker as services. If a service has a dedicated configuration, it’s configured and run when the current environment is set up and executed.

The following services are supported:

blackfire
broker
dashboard
database
key_value_store
kibana
mail_catcher
Key-value store (Redis or Valkey)-gui
scheduler
search
session
swagger
tideways
webdriver

blackfire:

An application profiler Service used for testing and debugging.

Project-wide
- blackfire: engine:—possible value is blackfire.
- blackfire: server-id:—defines the server id used to authenticate with Blackfire. Use it only if you have a shared agent between multiple environments.
- blackfire: server-token:—defines the server token used to authenticate with Blackfire. Use it only if you have a shared agent between multiple environments.
- blackfire: client-id:—defines the client ID from the Client ID/Client Token credentials pair.
- blackfire: client-token:—defines the client Token from the Client ID/Client Token credentials pair.

broker:

A message broker Service.

Project-wide
- broker: engine:—possible values is rabbitmq.
- broker: api: username, database: api: password:—defines the credentails for the message broker’s API.
- broker: endpoints:—defines the service’s port or/and web-interface that can be accessed via given endpoints.
Store-specific
- broker: namespace:—defines a namespace (virtual host).
- broker: username:, broker: password:—defines the credentials to access the namespace (virtual host) defined by broker: namespace:.

dashboard:

A real-time log monitoring Service.

Project-wide
- dashboard: engine:—possible value is dashboard.
- dashboard: endpoints:—defines the service’s port and web interface that can be accessed via given endpoints.

database:

An SQL database management system Service.

SCCOS

In Spryker Cloud Commerse OS, database: root: username: and database: root: password: are generated automatically for security reasons. You do not need to define them for cloud environments.

Project-wide
- database: engine:—possible values are postgresand mysql.
- database: version:—defines the version of the database engine. If database:engine: is set to mysql, also defines if MySQL or MariaDB is used according to the version. See Database on this page for detailed configuration instructions.
- database: root: username:, database: root: password:—defines the user with root privileges.
- database: endpoints:—defines the service’s port that can be accessed via given endpoints.
Region-specific
- database: database:—defines database name.
- database: username:, database: password:—defines database credentials.

key_value_store:

A key-value store Service for storing business data.

Project-wide
- key_value_store: engine:—possible value is: redis.
- key_value_store: replicas: number:—defines the number of replicas. The default value is 0.
- session: endpoints:—defines the service’s port that can be accessed via given endpoints.
Store-specific
- key_value_store: namespace:—defines a namespace (number for Redis).

kibana:

A Service to visualize Elasticsearch data and navigate the Elastic Stack.

Project-wide
- kibana: engine:—possible value is: kibana.
- kibana: endpoints:—defines the service’s port and web interface that can be accessed via given endpoints.

mail_catcher:

A mail catcher Service used to catch all outgoing emails for development or testing needs.

Project-wide
- mail_catcher: engine:—possible value is mailhog.
- mail_catcher: endpoints:-defines the service’s port and web interface that can be accessed via given endpoints.

redis-gui:

A Service that provides a graphical user interface to access Redis databases.

Project-wide
- redis-gui: engine:—possible value is redis-commander.
- redis-gui: endpoints:—defines the service’s port and web interface that can be accessed via given endpoints.

scheduler:

A scheduler Service used to run application-specific jobs periodically in the background.

Project-wide
- scheduler: engine:—possible value is jenkins.
- scheduler: endpoints:—defines the service’s port and web interface that can be accessed via given endpoints.

search:

A search Service that provides a distributed, multitenant-capable full-text search engine.

Project-wide
- search: engine:—possible value is elastic.
- search: endpoints:—defines the service’s port and web interface that can be accessed via given endpoints.

session:

A key-value store Service for storing session data.

Project-wide
- session: engine:—possible values is redis.
- session: endpoints:—defines the service’s port that can be accessed via given endpoints.
Endpoint-specific
- session: namespace:—defines a namespace (number for Redis).

swagger:

The swagger-ui Service used to run Swagger UI to develop API endpoints.

Project-wide
- swagger: engine:–possible value is swagger-ui.
- swagger-ui: endpoints:—defines the service’s port or/and web interface that can be accessed via given endpoints.

tideways:

An application profiler Service for testing and debugging.

Project-wide
- tideways: apikey:—defines the api-key to authenticate with Tideways.
- tideways: environment-name:—defines the environment name of your environment on Tideways. This variable is optional with the default value of production.
- tideways: cli-enabled:—defines if profiling of CLI script is enabled. This variable is optional with the default value of false.

webdriver:

A Service to control user agents.

Project-wide
- webdriver: engine:—possible values are chromedriver, phantomjs. This variable is optional with the default value of phantomjs.

Change log

Initial reference document is introduced.

Install the Basic Shop Theme feature

Wed, 29 Jul 2026 07:53:15 +0000

This document describes how to install the Basic Shop Theme feature. The feature lets Business Admins configure logos, theme colors, and custom CSS for the Storefront, Back Office, and Merchant Portal directly from the Back Office. ## Prerequisites Before installing this feature, install and configure the following: | NAME | VERSION | INTEGRATION GUIDE | |------|---------|-------------------| | Configuration Management feature | ^0.1.0 | [Install the Configuration Management feature](/docs/dg/dev/integrate-and-configure/integrate-confguration-feature.html) | | Spryker Core | ^3.82 | — | ## Install feature core ### 1) Install the required modules Install the required modules using Composer: ```bash composer require spryker/gui:"^3.0.0" spryker/zed-ui:"^2.0.0" spryker-shop/shop-ui:"^1.0.0" symfony/html-sanitizer:"^7.4" --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following modules have been installed: | MODULE | EXPECTED DIRECTORY | |--------|-------------------| | Gui | vendor/spryker/gui | | ZedUi | vendor/spryker/zed-ui | | ShopUi | vendor/spryker-shop/shop-ui | | symfony/html-sanitizer | vendor/symfony/html-sanitizer | {% endinfo_block %} ### 2) Sync the theme configuration schema Run the configuration sync command to register the theme settings in the Back Office: ```bash console configuration:sync ``` {% info_block warningBox "Verification" %} 1. Log in to the Back Office. 2. Navigate to **Configuration**. 3. Verify that the **Theme** feature appears in the sidebar with four tabs: **Storefront**, **Back Office**, **Merchant Portal**, and **Logos**. {% endinfo_block %} ### 3) Set up behavior The `configurationValue()` and `configurationValues()` Twig functions are made available by existing plugins that are already registered in a standard Spryker installation: - **Storefront (Yves)**: `ShopUiTwigExtension` - **Back Office and Merchant Portal (Zed)**: `\Spryker\Zed\Twig\Communication\Plugin\Application\TwigApplicationPlugin` No additional Twig plugin registration is required. #### 3.1) Register ACL plugins for Merchant Portal Register the ACL entity configuration and rule expander plugins so that Merchant Portal users can read theme configuration values through the ACL layer: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | |--------|---------------|---------------|-----------| | ConfigurationValueAclEntityConfigurationExpanderPlugin | Expands the ACL entity configuration with `ConfigurationValue` entity rules for Merchant Portal access. | None | Spryker\Zed\Configuration\Communication\Plugin\AclMerchantPortal | | ConfigurationValueMerchantAclEntityRuleExpanderPlugin | Expands the Merchant ACL entity rule set to allow Merchant Portal users to read published configuration values. | None | Spryker\Zed\Configuration\Communication\Plugin\AclMerchantPortal | **src/Pyz/Zed/AclMerchantPortal/AclMerchantPortalDependencyProvider.php** Add the import statements: ```php use Spryker\Zed\Configuration\Communication\Plugin\AclMerchantPortal\ConfigurationValueAclEntityConfigurationExpanderPlugin; use Spryker\Zed\Configuration\Communication\Plugin\AclMerchantPortal\ConfigurationValueMerchantAclEntityRuleExpanderPlugin; ``` Register the plugins in the respective methods: ```php protected function getAclEntityConfigurationExpanderPlugins(): array { return [ // ... new ConfigurationValueAclEntityConfigurationExpanderPlugin(), ]; } protected function getMerchantAclEntityRuleExpanderPlugins(): array { return [ // ... new ConfigurationValueMerchantAclEntityRuleExpanderPlugin(), ]; } ``` {% info_block warningBox "Verification" %} Log in to the Merchant Portal and navigate to any page. Verify there are no ACL-related errors in the application log. {% endinfo_block %} ### 4) Configure media filesystems The logo upload feature requires three Flysystem filesystem services: one per application context. Configure them in your shared config and provide local overrides for development and CI environments. #### 4.1) Add filesystem services to the shared config Add the three media filesystem services to `config/Shared/config_default.php`. In production, they read from S3 using the `SPRYKER_S3_PUBLIC_ASSETS_*` environment variables. **config/Shared/config_default.php** Add the three media filesystem entries inside the existing `$config[FileSystemConstants::FILESYSTEM_SERVICE]` array. To enable an IAM role configuration, use `IamAws3v3FilesystemBuilderPlugin`: ```php $config[FileSystemConstants::FILESYSTEM_SERVICE] = [ 'backoffice-media' => [ 'sprykerAdapterClass' => IamAws3v3FilesystemBuilderPlugin::class, 'bucket' => getenv('SPRYKER_S3_PUBLIC_ASSETS_BUCKET') ?: '', 'region' => getenv('AWS_REGION') ?: '', 'path' => '/backoffice-media', ], 'storefront-media' => [ 'sprykerAdapterClass' => IamAws3v3FilesystemBuilderPlugin::class, 'bucket' => getenv('SPRYKER_S3_PUBLIC_ASSETS_BUCKET') ?: '', 'region' => getenv('AWS_REGION') ?: '', 'path' => '/storefront-media', ], 'merchant-portal-media' => [ 'sprykerAdapterClass' => IamAws3v3FilesystemBuilderPlugin::class, 'bucket' => getenv('SPRYKER_S3_PUBLIC_ASSETS_BUCKET') ?: '', 'region' => getenv('AWS_REGION') ?: '', 'path' => '/merchant-portal-media', ], ]; ``` {% info_block warningBox "IAM authentication required" %} These filesystems authenticate through the IAM role attached to the workload, which resolves AWS credentials automatically. Access keys (`key` and `secret`) are not supported. If your project was set up from older documentation using access keys, migrate to this configuration. For more details, see [AWS S3 filesystem builder plugins](/docs/dg/dev/backend-development/data-manipulation/data-ingestion/structural-preparations/flysystem.html#aws-s3-filesystem-builder-plugins). {% endinfo_block %} #### 4.2) Add local filesystem fallback for development In the development environment, override the three filesystem services with a local adapter when the S3 bucket is not configured. This stores uploaded files under `public/Yves/assets/static/images` and serves them via the Yves assets path. **config/Shared/config_default-docker.dev.php** Add the import statement: ```php use Spryker\Shared\Flysystem\FlysystemConstants; ``` Add the following block in the filesystem section: ```php if (!getenv('SPRYKER_S3_PUBLIC_ASSETS_BUCKET')) { $publicUrl = sprintf( '%s%s', $config[ApplicationConstants::BASE_URL_YVES], '/assets/static/images', ); $localMediaFilesystemConfig = [ 'sprykerAdapterClass' => LocalFilesystemBuilderPlugin::class, 'root' => APPLICATION_ROOT_DIR . '/public/Yves/assets/static/images', 'path' => '', ]; $config[FileSystemConstants::FILESYSTEM_SERVICE]['backoffice-media'] = $localMediaFilesystemConfig; $config[FileSystemConstants::FILESYSTEM_SERVICE]['storefront-media'] = $localMediaFilesystemConfig; $config[FileSystemConstants::FILESYSTEM_SERVICE]['merchant-portal-media'] = $localMediaFilesystemConfig; $config[FlysystemConstants::FLYSYSTEM_OPTIONS] = [ 'public_url' => $publicUrl, ]; } ``` #### 4.3) Add local filesystem fallback for CI **config/Shared/config_default-docker.ci.php** Add the import statements: ```php use Spryker\Shared\Application\ApplicationConstants; use Spryker\Shared\Flysystem\FlysystemConstants; ``` Add the `$localMediaFilesystemConfig` variable before the `$config[FileSystemConstants::FILESYSTEM_SERVICE]` array, and add the three services as entries inside that array. After the array, add the public URL config: ```php $localMediaFilesystemConfig = [ 'sprykerAdapterClass' => LocalFilesystemBuilderPlugin::class, 'root' => APPLICATION_ROOT_DIR . '/public/Yves/assets/static/images', 'path' => '', ]; $config[FileSystemConstants::FILESYSTEM_SERVICE] = [ // ... existing entries ... 'backoffice-media' => $localMediaFilesystemConfig, 'storefront-media' => $localMediaFilesystemConfig, 'merchant-portal-media' => $localMediaFilesystemConfig, ]; $publicUrl = sprintf( '%s%s', $config[ApplicationConstants::BASE_URL_YVES], '/assets/static/images', ); $config[FlysystemConstants::FLYSYSTEM_OPTIONS] = [ 'public_url' => $publicUrl, ]; ``` {% info_block warningBox "Verification" %} 1. Log in to the Back Office. 2. Navigate to **Configuration > Theme > Logos**. 3. Upload a logo image using the file upload widget. 4. Verify the uploaded file is accessible at the public URL shown after upload. {% endinfo_block %} ### 5) Clear caches Clear the Twig cache and application cache to apply the new Twig functions: ```bash console twig:cache:warmer console cache:clear ``` ## Configure the feature After installing the feature, configure branding settings in the Back Office: 1. Log in to the Back Office. 2. Go to **Configuration > Theme**. 3. Select the tab for the context you want to configure: **Storefront**, **Back Office**, **Merchant Portal**, or **Logos**. 4. Enter the desired values and click **Save**. Changes to Storefront settings are published to key-value storage automatically. Back Office and Merchant Portal settings take effect on the next page load. ### Logo upload fields Logo settings support direct file upload from the Back Office. Uploaded files are stored via the corresponding Flysystem media filesystem service (`storefront-media`, `backoffice-media`, `merchant-portal-media`) and served from the configured `public_url`. | Context | Setting | Recommended size | Supported formats | Filesystem service | |---------|---------|-----------------|-------------------|--------------------| | Storefront | Storefront Logo | 186×50 px | GIF, PNG, JPEG, BMP, WebP, SVG | `storefront-media` | | Back Office | Back Office Logo | 186×50 px | GIF, PNG, JPEG, BMP, WebP, SVG | `backoffice-media` | | Merchant Portal | Merchant Portal Logo | 186×50 px | GIF, PNG, JPEG, BMP, WebP, SVG | `merchant-portal-media` | In production, configure the `SPRYKER_S3_PUBLIC_ASSETS_BUCKET`, `SPRYKER_S3_PUBLIC_ASSETS_KEY`, `SPRYKER_S3_PUBLIC_ASSETS_SECRET`, and `AWS_REGION` environment variables to point to an S3 bucket (or compatible object storage). In development and CI, files are stored locally at `public/Yves/assets/static/images`. ### Store-level overrides To configure a per-store override: 1. In the scope selector at the top of the Configuration page, switch from **Default** to the target store (for example, **DE**). 2. Adjust the setting value. 3. Click **Save**. Stores without a store-level value inherit the global (Default) value. ## Theme configuration key reference The following theme settings are registered by the feature's YAML schema. Use their compound keys in `configurationValue()` Twig calls or via `getModuleConfig()` in a module Config class. | Compound Key | Context | Type | Default | |-------------|---------|------|---------| | `theme:storefront:colors:background_brand_primary` | Storefront | color | `#00bebe` | | `theme:storefront:colors:background_brand_subtle` | Storefront | color | `#eb553c` | | `theme:storefront:custom_css:yves_custom_css` | Storefront | text | (empty) | | `theme:logos:logos:yves_logo_url` | Storefront | file | (empty) | | `theme:backoffice:colors:bo_main_color` | Back Office | color | `#1ebea0` | | `theme:backoffice:colors:bo_sidenav_color` | Back Office | color | `#23303c` | | `theme:backoffice:colors:bo_sidenav_text_color` | Back Office | color | `#e4e4e4` | | `theme:logos:logos:backoffice_logo_url` | Back Office | file | (empty) | | `theme:merchant_portal:colors:spy_primary_color` | Merchant Portal | color | `#1ebea0` | | `theme:logos:logos:merchant_portal_logo` | Merchant Portal | file | (empty) | ### Twig usage examples Inject a theme color as a CSS custom property in a Back Office layout: {% raw %} ```twig ``` {% endraw %} Read multiple values at once: {% raw %} ```twig {% set themeValues = configurationValues([ 'theme:backoffice:colors:bo_main_color', 'theme:logos:logos:backoffice_logo_url', ]) %} ``` {% endraw %}

Install the Product Experience Management feature

Wed, 29 Jul 2026 07:53:15 +0000

## Prerequisites Install the required features: | NAME | VERSION | REQUIRED | | --- | --- | --- | | Spryker Core | {{page.release_tag}} | Required | | Product | {{page.release_tag}} | Required | | Product Image | {{page.release_tag}} | Required | | Price Product | {{page.release_tag}} | Required | | Stock | {{page.release_tag}} | Required | | Tax | {{page.release_tag}} | Required | | Store | {{page.release_tag}} | Required | | Locale | {{page.release_tag}} | Required | | Category | {{page.release_tag}} | Required | | Merchant | {{page.release_tag}} | Required | | Shipment Type | {{page.release_tag}} | Required | | File System | {{page.release_tag}} | Required | ## Install feature core ### 1) Install the required modules Install the required modules using Composer: ```bash composer require spryker-feature/product-experience-management:"{{page.release_tag}}" --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following modules have been installed: | MODULE | EXPECTED DIRECTORY | | --- | --- | | ProductExperienceManagement | vendor/spryker-feature/product-experience-management | {% endinfo_block %} ### 2) Set up configuration Configure the filesystem storage for import and export files. The feature requires two named filesystem entries: `product-experience-management-imports` and `product-experience-management-exports`. #### Production (S3) **config/Shared/config_default.php** To enable an IAM role configuration, use `IamAws3v3FilesystemBuilderPlugin`: ```php use Spryker\Service\FlysystemAws3v3FileSystem\Plugin\Flysystem\IamAws3v3FilesystemBuilderPlugin; use Spryker\Shared\FileSystem\FileSystemConstants; $config[FileSystemConstants::FILESYSTEM_SERVICE] = [ // ... existing entries ... 'product-experience-management-imports' => [ 'sprykerAdapterClass' => IamAws3v3FilesystemBuilderPlugin::class, 'bucket' => getenv('SPRYKER_S3_PEM_IMPORT_BUCKET') ?: '', 'region' => getenv('AWS_REGION') ?: '', 'path' => 'pem-imports/', ], 'product-experience-management-exports' => [ 'sprykerAdapterClass' => IamAws3v3FilesystemBuilderPlugin::class, 'bucket' => getenv('SPRYKER_S3_PEM_EXPORT_BUCKET') ?: '', 'region' => getenv('AWS_REGION') ?: '', 'path' => 'pem-exports/', ], ]; ``` {% info_block warningBox "IAM authentication required" %} These filesystems authenticate through the IAM role attached to the workload, which resolves AWS credentials automatically. Access keys (`key` and `secret`) are not supported. If your project was set up from older documentation using access keys, migrate to this configuration. For more details, see [AWS S3 filesystem builder plugins](/docs/dg/dev/backend-development/data-manipulation/data-ingestion/structural-preparations/flysystem.html#aws-s3-filesystem-builder-plugins). {% endinfo_block %} #### Development (local filesystem) **config/Shared/config_default-docker.dev.php** ```php use Spryker\Service\FlysystemLocalFileSystem\Plugin\Flysystem\LocalFilesystemBuilderPlugin; use Spryker\Shared\FileSystem\FileSystemConstants; $config[FileSystemConstants::FILESYSTEM_SERVICE]['product-experience-management-imports'] = [ 'sprykerAdapterClass' => LocalFilesystemBuilderPlugin::class, 'root' => '/data', 'path' => '/data/pem-imports', ]; $config[FileSystemConstants::FILESYSTEM_SERVICE]['product-experience-management-exports'] = [ 'sprykerAdapterClass' => LocalFilesystemBuilderPlugin::class, 'root' => '/data', 'path' => '/data/pem-exports', ]; ``` {% info_block warningBox "Verification" %} Make sure the filesystem directories exist and are writable by the application. For local development, verify that `/data/pem-imports` and `/data/pem-exports` directories are created inside the Docker container. {% endinfo_block %} ### 3) Set up the database schema and transfer objects Apply database changes and generate entity and transfer changes: ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure that the following changes have been applied by checking your database: | DATABASE ENTITY | TYPE | EVENT | | --- | --- | --- | | spy_import_job | table | created | | spy_import_job_run | table | created | | spy_import_job_run_error | table | created | {% endinfo_block %} {% info_block warningBox "Verification" %} Make sure the following changes in transfer objects have been applied: | TRANSFER | TYPE | EVENT | PATH | | --- | --- | --- | --- | | ImportJob | class | created | src/Generated/Shared/Transfer/ImportJobTransfer | | ImportJobRun | class | created | src/Generated/Shared/Transfer/ImportJobRunTransfer | | ImportJobRunFileInfo | class | created | src/Generated/Shared/Transfer/ImportJobRunFileInfoTransfer | | ImportJobRunError | class | created | src/Generated/Shared/Transfer/ImportJobRunErrorTransfer | | ImportJobCollection | class | created | src/Generated/Shared/Transfer/ImportJobCollectionTransfer | | ImportJobRunCollection | class | created | src/Generated/Shared/Transfer/ImportJobRunCollectionTransfer | | ImportJobRunErrorCollection | class | created | src/Generated/Shared/Transfer/ImportJobRunErrorCollectionTransfer | | ImportJobRunCollectionRequest | class | created | src/Generated/Shared/Transfer/ImportJobRunCollectionRequestTransfer | | ImportJobRunCollectionResponse | class | created | src/Generated/Shared/Transfer/ImportJobRunCollectionResponseTransfer | | ImportJobCollectionRequest | class | created | src/Generated/Shared/Transfer/ImportJobCollectionRequestTransfer | | ImportJobCollectionResponse | class | created | src/Generated/Shared/Transfer/ImportJobCollectionResponseTransfer | | ImportJobCriteria | class | created | src/Generated/Shared/Transfer/ImportJobCriteriaTransfer | | ImportJobConditions | class | created | src/Generated/Shared/Transfer/ImportJobConditionsTransfer | | ImportJobRunCriteria | class | created | src/Generated/Shared/Transfer/ImportJobRunCriteriaTransfer | | ImportJobRunConditions | class | created | src/Generated/Shared/Transfer/ImportJobRunConditionsTransfer | | ImportJobRunErrorCriteria | class | created | src/Generated/Shared/Transfer/ImportJobRunErrorCriteriaTransfer | | ImportJobRunErrorConditions | class | created | src/Generated/Shared/Transfer/ImportJobRunErrorConditionsTransfer | | ImportJobExportResult | class | created | src/Generated/Shared/Transfer/ImportJobExportResultTransfer | | ImportStepResponse | class | created | src/Generated/Shared/Transfer/ImportStepResponseTransfer | | ImportStepError | class | created | src/Generated/Shared/Transfer/ImportStepErrorTransfer | | ImportRowValidationCollection | class | created | src/Generated/Shared/Transfer/ImportRowValidationCollectionTransfer | | ImportPublishEvent | class | created | src/Generated/Shared/Transfer/ImportPublishEventTransfer | {% endinfo_block %} ### 4) Configure navigation Add the following entry to the Back Office navigation: **config/Zed/navigation.xml** ```xml Import & Export Import & Export swap_vert Import Import product-experience-management job index 1 Export Export product-experience-management export index 1 ``` Build the navigation cache: ```bash console navigation:cache:remove ``` {% info_block warningBox "Verification" %} Log in to the Back Office and verify that the **Import & Export** section appears in the main navigation with **Import** and **Export** sub-items. {% endinfo_block %} ### 5) Set up console #### Register the console command Register the `import:job:run` console command that processes pending import job runs: **src/Pyz/Zed/Console/ConsoleDependencyProvider.php** ```php use SprykerFeature\Zed\ProductExperienceManagement\Communication\Console\ImportJobRunConsole; // In getConsoleCommands(): new ImportJobRunConsole(), ``` {% info_block warningBox "Verification" %} Execute the following and verify it completes without errors: ```bash console import:job:run ``` The output should indicate that it processed the next pending import job run, or that no pending runs are available. {% endinfo_block %} #### Configure the scheduler Register the import job run processor to run on a schedule so pending imports are picked up automatically: **src/Pyz/Zed/SymfonyScheduler/SymfonySchedulerConfig.php** ```php 'import-job-run' => [ 'command' => $logger . '$PHP_BIN vendor/bin/console import:job:run', 'schedule' => '* * * * *', ], ``` {% info_block warningBox "Verification" %} Verify that the scheduler configuration is loaded: ```bash console scheduler:setup ``` Check that `import-job-run` appears in the list of scheduled jobs. {% endinfo_block %}

Spryker Documentation

Create discounts based on shipment

Activate a discount rule based on a shipment carrier

Add the checkout shipment precheck plugin to checkout

Install the Configuration Management feature

Configuration Management feature

What It Does

Quick Start

1. Declare settings in a YAML schema

2. Sync schemas

3. Consume in your module Config

Reading Configuration Values

The getModuleConfig() Method

Real-World Examples

Scope-Specific Reads

Integration Checklist

YAML Schema Declaration Reference

Schema Validation

Hierarchy

Feature Level

Tab Level

Group Level

Setting Level

Setting Types

File upload fields

file_upload properties

Options

Secret vs Storefront Behavior

Available Scopes

Constraints

Built-in Constraint Types

Dependencies

Dependency Rule

When Clause

Condition

Dependency Operators

XSS Sanitization

Status Badges

Schema File Locations

Backoffice Management

Search

Override Detection

Twig Integration

configurationValue

configurationValues

Data Import

CSV format

Running the import

Behavior

Console Commands

Common Issues

Upcoming major module releases

Install the SSP File Management feature

Configure services

Prerequisites

Service versions

Database services

MariaDB

Configure MariaDB

MySQL

Configure MySQL

PostgreSQL

Configure PostgreSQL

Elasticsearch

Configure Elasticsearch

Kibana UI

Configure Kibana UI

RabbitMQ

Configure RabbitMQ

Swagger UI

Rest API Reference in Spryker

Configure Swagger UI

Redis

Configure Redis

Redis GUI

Configure Redis GUI

MailHog

Configure MailHog

Blackfire

Configure Blackfire

The `getModuleConfig()` Method

`file_upload` properties

`configurationValue`

`configurationValues`