Deploy file reference - 1.0

Last updated: June 4, 2021

Edit on GitHub

You are browsing a previous version of the document. The latest version is 202204.0.

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), Yves or Glue.
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 signle 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'

image:

Defines the Docker image configuraion 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: php:

Defines PHP settings for Spryker applications.

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 setting of Assets.

assets: image: - defines a docker image for a front-end container. If not specified, the default value applies: assets: image: nginx:alpine.
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 an engine for static compressions. Possible values are gzip and brotli.
assets: compression: engine: static: - defines a comression mode. Allowed values are only, true, and false.
assets: compression: engine: level: - defines a compression level. Allowed range is from 1 to 9.
assets: compression: engine: types: - defines additional MIME types to be compressed.

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 for more details.
- 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(zed), yves, and glue.
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
- glue - 2m
- yves - 1m

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

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
        ...

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

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: 9.6
        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: 1. Remove all Spryker volumes: ```shell 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), [regions: stores: services:](#regions) and [groups: applications: endpoints: services:](#groups-applications-endpoints) 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 string or * to allow all domains.

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:
        license: eu01xxaa7460e1ea3abdfbbbd34e85c10cd0NRAL

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: 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 is 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
```
```
redis-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.

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 profilling 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.

Was this article helpful?

Tell us what could be better

Name (Optional)

Email (Optional) Invalid email format.

Type your thoughts here

We appreciate the time you took to share the feedback
and will consider it as soon as possible.