Spryker Documentation

Process documentation guidelines

Tue, 21 Apr 2026 09:51:53 +0000

This document provides guideline templates for development teams striving for high-quality software. These templates are flexible and serve as a starting point, so make sure to adjust them to your project's requirements. Defining and following these guidelines may be necessary to fulfill project Service Level Agreements (SLAs), with each guideline explicitly outlining the responsible team. Alignment with all involved teams is essential for ensuring a functioning concept. The process documentation guidelines enhance the communication between teams over all processes and ensure that they can operate and deploy their applications the best possible way. ## Deployment guidelines The following guidelines apply to the deployment of each release candidate. ### Environment variable assertion In large teams, effective communication and issue management can be challenging. As a result, some environment variables or their expected values may not be properly set in the production environment. To minimize the risk of critical errors, we recommend running a final validation on the production environment to verify that the expected setup changes match the actual state. To run a proper validation with the understanding of the scope of these changes, make sure to provide a list of the requested changes as part of the deployment standard service request for the operations team. This final validation step ensures that the production environment is correctly configured and minimizes the risk of errors. ### Special manual steps If there are manual one-time steps that aren't automated on the application side via the deployment pipeline processes, the uniformed instructions to these exclusive requests need to be handed over to the operations team in the deployment standard service request. This also includes any dependencies that may appear between the deployment elements. For example, one component needs to be released before another; or a special timing is needed. ### Infrastructure changes Changes to the platform infrastructure and application infrastructure are carefully evaluated because mistakes in this area can cause critical problems. To reduce risks, when submitting a deployment standard service request, make sure to carefully document the intention behind each impact on infrastructure. ### Expected behavior In special cases, like technical debts, functional debts, or accepted risks, a release can lead to release specific, temporary, expected critical or warning states that doesn't have to be handled or mitigated by the operations team. To decrease unnecessary fire-fighting on both sides, list and explain these scenarios when submitting a deployment standard service request. ### Example for deployment standard service request **Title**: Deployment of version 1.2.3 to production **Description**:
This request is for the deployment of version 1.2.3 of the MyProject application to the production environment. **Requested Changes**: - Deployment of version 1.2.3 of the MyProject application - Update of the following environment variables: - Expected environment variable name: `DATABASE_URL`
Expected value: `postgresql://user:password@localhost:5432/mydatabase` - Expected environment variable name: `API_KEY`
Expected value: `abcd1234` - Expected environment variable name: `DEBUG`
Expected value: `false` - Special manual steps: - **Step 1**: Run the database migration script before starting the application. - **Step 2**: Update the DNS records for the new application version. - Infrastructure changes: - Add an additional application server to the load balancer pool. - Increase the size of the database server's disk. *Expected behavior: - There may be a temporary increase in error log entries because of a known issue with the new version that will be fixed in the next release. **Impact**:
This deployment will include updates to the application's database connection and API key, as well as changes to the infrastructure. There is a low risk of downtime during the deployment. **Rollback Plan**:
In the event of an issue during the deployment, we will roll back to the previous version of the application and revert any infrastructure changes. **Testing**:
This release has been thoroughly tested in the staging environment. A final validation on the production environment to verify that the expected setup changes match the actual state will be performed before the deployment. **Approvals**: - Lead developer: approved - QA team: approved - Operations team: approved ## Operational guidelines The following guidelines apply to operating applications or for special failure scenarios that may as well occur during deployment or rollback. Given the size and complexity of a large applications, which delivers many features with each release, unexpected errors can have multiple potential resolutions. To ensure that the most effective resolution is chosen with minimal disruption to the functionality of a successfully deployed release, implement the following operation guidelines. ### Main workflows To understand the main and critical workflows in the application, operational guidelines should outline the normal behavior of important features and workflows at the logical, component, and infrastructure levels. This forms a general overview of the logic, components, and infrastructure. This overview is necessary for making informed operational decisions and building project-specific operational dashboards, for example—to to identify and highlight project-specific bottlenecks. Also, it's needed for analyzing, answering, and resolving requests. ### Risks, early warnings, and counter actions Building a large application is usually coupled with massive application-level logging. In some cases, a critical system issue can be prevented or minimized with timely warning signals. By using regular signals, like logs and metrics, from identified business or technical bottlenecks or risks, the operations team can improve the application's stability. We recommend maintaining a list of such signals and risks in the operational guidelines. This includes recommended actions to take in order to deliver the best mitigation strategy. For more information on these guidelines, see [Operatable feature guidelines](/docs/dg/dev/architecture/non-functional-requirement-templates/operatable-feature-guidelines.html). ### Silent undesired scenario Although monitoring systems are used to detect unwanted states, some business functionality may be within acceptable metrics but not desirable under certain conditions. For example, the minimum daily browsing customer count is 10, but 11 customers during Black Friday is not considered normal. To monitor such cases, these scenarios need to be documented for the operations team. ### User guide To minimize the impact of resolution efforts and optimize the process, make sure to provide the operations team with the necessary business context. For example, resolving a small number of errors through the Back Office may be more optimal than rolling back an entire release. ### Entity size expectations The number of entities plays an important role in determining how an application will function in a production environment. To mitigate risks in this area, performance, scaling, manual tests, and reviews can be applied. However, the identified and estimated number of entities for the project can serve as a warning to pay extra attention to these entities in order to further reduce risks. For example, a marketing campaign bringing 10,000 active users to the homepage at 17:08 on Friday. ### Remote service catalog To properly handle and monitor the cooperation between local and remote or third-party services, provide the operations team with a detailed communication protocol. Make sure to additionally include the expected outages and major impacts. This way, the operations team can ignore expected outages and actively focus on known risks. For example, a payment provider connected to the project needs to be monitored to ensure its availability. The following communication protocol is used: - The local service sends an HTTP GET request to the remote service's API endpoint, along with any necessary headers and query parameters. - The remote service responds with an HTTP status code and a JSON payload containing the requested data. - The local service processes the data and displays it to the user or performs any necessary actions.

Process documentation guidelines

Tue, 21 Apr 2026 09:51:53 +0000

This document provides guideline templates for development teams striving for high-quality software. These templates are flexible and serve as a starting point, so make sure to adjust them to your project's requirements. Defining and following these guidelines may be necessary to fulfill project Service Level Agreements (SLAs), with each guideline explicitly outlining the responsible team. Alignment with all involved teams is essential for ensuring a functioning concept. The process documentation guidelines enhance the communication between teams over all processes and ensure that they can operate and deploy their applications the best possible way. ## Deployment guidelines The following guidelines apply to the deployment of each release candidate. ### Environment variable assertion In large teams, effective communication and issue management can be challenging. As a result, some environment variables or their expected values may not be properly set in the production environment. To minimize the risk of critical errors, we recommend running a final validation on the production environment to verify that the expected setup changes match the actual state. To run a proper validation with the understanding of the scope of these changes, make sure to provide a list of the requested changes as part of the deployment standard service request for the operations team. This final validation step ensures that the production environment is correctly configured and minimizes the risk of errors. ### Special manual steps If there are manual one-time steps that aren't automated on the application side via the deployment pipeline processes, the uniformed instructions to these exclusive requests need to be handed over to the operations team in the deployment standard service request. This also includes any dependencies that may appear between the deployment elements. For example, one component needs to be released before another; or a special timing is needed. ### Infrastructure changes Changes to the platform infrastructure and application infrastructure are carefully evaluated because mistakes in this area can cause critical problems. To reduce risks, when submitting a deployment standard service request, make sure to carefully document the intention behind each impact on infrastructure. ### Expected behavior In special cases, like technical debts, functional debts, or accepted risks, a release can lead to release specific, temporary, expected critical or warning states that doesn't have to be handled or mitigated by the operations team. To decrease unnecessary fire-fighting on both sides, list and explain these scenarios when submitting a deployment standard service request. ### Example for deployment standard service request **Title**: Deployment of version 1.2.3 to production **Description**:
This request is for the deployment of version 1.2.3 of the MyProject application to the production environment. **Requested Changes**: - Deployment of version 1.2.3 of the MyProject application - Update of the following environment variables: - Expected environment variable name: `DATABASE_URL`
Expected value: `postgresql://user:password@localhost:5432/mydatabase` - Expected environment variable name: `API_KEY`
Expected value: `abcd1234` - Expected environment variable name: `DEBUG`
Expected value: `false` - Special manual steps: - **Step 1**: Run the database migration script before starting the application. - **Step 2**: Update the DNS records for the new application version. - Infrastructure changes: - Add an additional application server to the load balancer pool. - Increase the size of the database server's disk. *Expected behavior: - There may be a temporary increase in error log entries because of a known issue with the new version that will be fixed in the next release. **Impact**:
This deployment will include updates to the application's database connection and API key, as well as changes to the infrastructure. There is a low risk of downtime during the deployment. **Rollback Plan**:
In the event of an issue during the deployment, we will roll back to the previous version of the application and revert any infrastructure changes. **Testing**:
This release has been thoroughly tested in the staging environment. A final validation on the production environment to verify that the expected setup changes match the actual state will be performed before the deployment. **Approvals**: - Lead developer: approved - QA team: approved - Operations team: approved ## Operational guidelines The following guidelines apply to operating applications or for special failure scenarios that may as well occur during deployment or rollback. Given the size and complexity of a large applications, which delivers many features with each release, unexpected errors can have multiple potential resolutions. To ensure that the most effective resolution is chosen with minimal disruption to the functionality of a successfully deployed release, implement the following operation guidelines. ### Main workflows To understand the main and critical workflows in the application, operational guidelines should outline the normal behavior of important features and workflows at the logical, component, and infrastructure levels. This forms a general overview of the logic, components, and infrastructure. This overview is necessary for making informed operational decisions and building project-specific operational dashboards, for example—to to identify and highlight project-specific bottlenecks. Also, it's needed for analyzing, answering, and resolving requests. ### Risks, early warnings, and counter actions Building a large application is usually coupled with massive application-level logging. In some cases, a critical system issue can be prevented or minimized with timely warning signals. By using regular signals, like logs and metrics, from identified business or technical bottlenecks or risks, the operations team can improve the application's stability. We recommend maintaining a list of such signals and risks in the operational guidelines. This includes recommended actions to take in order to deliver the best mitigation strategy. For more information on these guidelines, see [Operatable feature guidelines](/docs/dg/dev/best-practices/non-functional-requirement-templates/operatable-feature-guidelines.html). ### Silent undesired scenario Although monitoring systems are used to detect unwanted states, some business functionality may be within acceptable metrics but not desirable under certain conditions. For example, the minimum daily browsing customer count is 10, but 11 customers during Black Friday is not considered normal. To monitor such cases, these scenarios need to be documented for the operations team. ### User guide To minimize the impact of resolution efforts and optimize the process, make sure to provide the operations team with the necessary business context. For example, resolving a small number of errors through the Back Office may be more optimal than rolling back an entire release. ### Entity size expectations The number of entities plays an important role in determining how an application will function in a production environment. To mitigate risks in this area, performance, scaling, manual tests, and reviews can be applied. However, the identified and estimated number of entities for the project can serve as a warning to pay extra attention to these entities in order to further reduce risks. For example, a marketing campaign bringing 10,000 active users to the homepage at 17:08 on Friday. ### Remote service catalog To properly handle and monitor the cooperation between local and remote or third-party services, provide the operations team with a detailed communication protocol. Make sure to additionally include the expected outages and major impacts. This way, the operations team can ignore expected outages and actively focus on known risks. For example, a payment provider connected to the project needs to be monitored to ensure its availability. The following communication protocol is used: - The local service sends an HTTP GET request to the remote service's API endpoint, along with any necessary headers and query parameters. - The remote service responds with an HTTP status code and a JSON payload containing the requested data. - The local service processes the data and displays it to the user or performs any necessary actions.

Operational and deployment guidelines

Tue, 21 Apr 2026 09:51:53 +0000

Operational and deployment guidelines

Tue, 21 Apr 2026 09:51:53 +0000

Operatable feature guidelines

Tue, 21 Apr 2026 09:51:53 +0000

Operatable feature guidelines

Tue, 21 Apr 2026 09:51:53 +0000

Monitorable process guidelines

Tue, 21 Apr 2026 09:51:53 +0000

Log structure example

```JSON { "actor": { "actorId": "end-user-1", "sessionId": "end-user-1-session-27", "transactionId": "end-to-end-transaction-555", "parentTransactionId": "end-to-end-transaction-554", }, "service": { "host": "ip-11-111-1-111.eu-central-1.compute.internal", "componentType": "GLUE", "component": "StorefrontApi", "activityId": "address-search-suggestions", }, "@timestamp": "2022-08-01T18:20:22.602934+00:00", "message":"StorefrontAPI : GET : v2/stores/delivery : start", "messageId":"unique-message-id", "level": 0, "levelCode": 0, "extra" : { "exception": {...} "environment": { "application": "", "environment": "", "store": "", "codeBucket": "", "locale": "" }, "server": { "url": "", "isHttps": true, "hostname": "", "requestMethod": "", "referer": null }, "request": { "requestId": "", "type": "", "requestParams": {} }, "externalRequest" : { "externalDuration":"0", "externalResponseCode": "remote-service-unique-answer-code" }, } ```

Log structure with example values

```JSON { "@timestamp": "2022-08-01T18:20:22.602934+00:00", "@version": 1, "host": "ip-10-105-6-175.eu-central-1.compute.internal", "message": "StorefrontAPI : Request : v2/stores/delivery", "type": "GLUE", "channel": "Glue", "level": "INFO", "monolog_level": 200, "extra": { "environment": { "application": "GLUE", "environment": "docker.dev", "store": null, "codeBucket": "US", "locale": "en_US" }, "server": { "url": "https://api.com/v1/action-name?param1=abc", "is_https": true, "hostname": "api.com", "user_agent": "cypress/test-automation", "user_ip": "35.205.30.220", "request_method": "GET", "referer": null }, "request": { "requestId": "3c1f60f1", "type": "WEB", "request_params": { "currency": "USD", "service_type": "delivery", "zip_code": "32773-5600", "address": "3707 S Orlando Dr" } } }, "context": { "payload": { "find_by": [] } } } ```

Log structure with example error values

```JSON { "@timestamp": "2021-08-19T14:54:23.447685+00:00", "@version": 1, "host": "localhost", "message": "Exception - Sniffer run was not successful: Unknown error in \"/.../vendor/spryker/development/src/Spryker/Zed/Development/Business/ArchitectureSniffer/ArchitectureSniffer.php::165\"", "type": "ZED", "channel": "Zed", "level": "CRITICAL", "monolog_level": 500, "extra": { "environment": { "application": "ZED", "environment": "development", "store": "US", "codeBucket": "US", "locale": "en_US" }, "server": { "url": "http://:/", "is_https": false, "hostname": "", "user_agent": null, "user_ip": null, "request_method": "cli", "referer": null }, "request": { "requestId": "ad26d9e1", "type": "CLI", "request_params": [] } }, "context": { "exception": { "class": "Exception", "message": "Sniffer run was not successful: Unknown error", "code": 0, "file": "/.../vendor/spryker/development/src/Spryker/Zed/Development/Business/ArchitectureSniffer/ArchitectureSniffer.php:165", "trace": [ "/.../vendor/spryker/development/src/Spryker/Zed/Development/Business/ArchitectureSniffer/ArchitectureSniffer.php:117", "/.../vendor/spryker/development/src/Spryker/Zed/Development/Business/DevelopmentFacade.php:484", "/.../vendor/spryker/development/src/Spryker/Zed/Development/Communication/Console/CodeArchitectureSnifferConsole.php:286", "/.../vendor/spryker/development/src/Spryker/Zed/Development/Communication/Console/CodeArchitectureSnifferConsole.php:93", "/.../vendor/symfony/console/Command/Command.php:258", "/.../vendor/symfony/console/Application.php:938", "/.../vendor/symfony/console/Application.php:266", "/.../vendor/spryker/console/src/Spryker/Zed/Console/Communication/Bootstrap/ConsoleBootstrap.php:111", "/.../vendor/symfony/console/Application.php:142", "/.../vendor/spryker/console/bin/console:27" ] } } } ```

## Metric generation Each metric represents a condition of system attributes. There can be many of them, and they can be correlated with each other. - Every service or component can define and generate project-appropriate metrics for key processes to enable tracking of such events and reacting when they reach undesired scores. These metrics are generated with a basic dimension of the duration and outcome of the operation, such as success or failure. - The start and end of a process must be recorded to enable tracking and tuning of the infrastructure. - Instances of communication duration with remote services must be recorded to understand if a local process is delayed for a good reason. - Critical metrics, along with their threshold values, must be highlighted in the [Operational guidelines](/docs/dg/dev/architecture/non-functional-requirement-templates/process-documentation-guidelines.html#operational-guidelines) to enable the setting up of a monitoring system. - Deployment and rollback flows can generate metrics to enable tracking and interaction with these processes.

Monitorable process guidelines

Tue, 21 Apr 2026 09:51:53 +0000

Log structure example

Log structure with example values

Log structure with example error values

## Metric generation Each metric represents a condition of system attributes. There can be many of them, and they can be correlated with each other. - Every service or component can define and generate project-appropriate metrics for key processes to enable tracking of such events and reacting when they reach undesired scores. These metrics are generated with a basic dimension of the duration and outcome of the operation, such as success or failure. - The start and end of a process must be recorded to enable tracking and tuning of the infrastructure. - Instances of communication duration with remote services must be recorded to understand if a local process is delayed for a good reason. - Critical metrics, along with their threshold values, must be highlighted in the [Operational guidelines](/docs/dg/dev/best-practices/non-functional-requirement-templates/process-documentation-guidelines.html#operational-guidelines) to enable the setting up of a monitoring system. - Deployment and rollback flows can generate metrics to enable tracking and interaction with these processes.

Basic SEO techniques to use in your project

Tue, 21 Apr 2026 09:51:53 +0000

Search Engine Optimization or SEO is the process of improving a site to increase its visibility for relevant searches. The better visibility a page has in search results, the more likely you are to garner attention and attract prospective and existing customers to your business.

Search engines use bots to crawl pages on the web, going from site to site, collecting information about those pages, and putting them in an index. Next, algorithms analyze pages in the index, taking into account a lot of ranking factors, to determine the order pages should appear in the search results for a given query.

To increase search result ranking in the Spryker system, we use some basic SEO approaches. To utilize them in your project, first of all, you need to define the landing pages, which will collect the basic traffic and should be indexed first. By default, in the Spryker system, these landing pages are Product details, Catalog, Shared Shopping List, and Product bundle pages.

The simplest and basic way to optimize SEO of page content is the proper usage of headings on the pages and microdata usage.

Using headings

Headings allow for easy navigation through page content and help users and search engines read and understand the text. However, for the headings to be helpful for users and search engines, the headings must be structured well, and contain the key phrases.

H1 headings

It is important to use the h1 heading. However, the number of h1 elements on each page must be limited to one. The h1 heading must be the name or title of the page.

For example, on a catalog page, h1 is the name of the chosen category. Or, on a product details page, it’s the product name. Then h2 and h3 subheadings are used to introduce different sections. Those individual sections might also use more specific headers (h3 tags, then h4 tags) to introduce sub-sections. It’s rare for most content to get deep enough to need to use h4 tags.

Check out the headings structure on a catalog page in the Spryker Demo Shop:

To keep the initial Spryker design, we use the service CSS classes title with modifiers h1-h6. At the same time, headings in CMS blocks are div elements, as these blocks can be injected anywhere and potentially could break the common heading structure.

Using microdata

After introducing the headings structure, the next step towards increasing the search result ranking is using the microdata. There are different approaches to using microdata on a page, and one of them is the usage of the Schema.org vocabulary, which we also implemented for the Spryker system. Schema.org (often called Schema) is a semantic vocabulary of tags or microdata that you can add to your HTML to improve the way search engines read and represent your page on search engine results pages (SERPs). Microdata is one of three code languages designed to provide search-engine spider programs with information about the website content. The failure to use microdata leads to the reduction of search ranks of the shop pages. Because the content is not typed for search engines in this case, and they can not build structured pages to index them well.

Integrating microdata into code offers a number of potential advantages. First, microdata can give search engine crawlers more context for the type of information on a website and the way the site should be indexed and ranked. Another benefit of microdata is the creation of rich snippets, which display more information on the SERPs than traditional listings.

Considering that Spryker is an e-commerce platform, the most important types of information are:

Product: any offered product or service
Offer: an offer to transfer some rights to an item or to provide a service
Review: a review of an item
AggregateRating: the average rating based on multiple ratings or reviews
PropertyValue: a property-value pair represents a feature of a product or place

Here is an example of the Schema.org microdata implementation for a page:

<div itemscope itemtype="https://schema.org/Product">
  <span itemprop="name">Product name</span>  
</div>

The itemscope element in an HTML tag encloses information about the item. The itemscope specifies that the HTML contained in the tag is about a particular item. To specify the type of the item, we use the itemtype attribute right after the itemscope. For example, on the following Spryker Product details page, the itemtype attribute specifies that the item contained in the tag has the Product type, as defined in the schema.org type hierarchy. Item types are provided as URLs, in our case http://schema.org/Product. To label properties of items, we use the itemprop attribute:

Name, image, and product wrapper

Brand, SKU, offer, and price

Description, product details, ratings

Review

Applying the basic SEO techniques in your project

For details about applying the basic SEO techniques in your project, see Basic SEO techniques integration guide.

Guidelines

Tue, 21 Apr 2026 09:11:56 +0000

This section contains a collection of useful guidelines for developing on the Spryker Commerce OS: - [Coding guidelines](/docs/dg/dev/guidelines/coding-guidelines/coding-guidelines.html) - [Keeping a project upgradable](/docs/dg/dev/guidelines/keeping-a-project-upgradable/keeping-a-project-upgradable.html) - [Performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html) - [Testing guidelines](/docs/dg/dev/guidelines/testing-guidelines/testing-best-practices/testing-concepts.html) - [Project development guidelines](/docs/dg/dev/guidelines/project-development-guidelines.html) - [Data processing guidelines](/docs/dg/dev/guidelines/data-processing-guidelines.html) - [Module configuration convention](/docs/dg/dev/guidelines/module-configuration-convention.html) - [Security guidelines](/docs/dg/dev/guidelines/security-guidelines.html)