Configure services

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:

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.

Configure MariaDB

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

Configure Blackfire

To enable Blackfire, follow these steps:

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

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

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

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

services:
    ...
    blackfire:
        engine: blackfire

3. Pass Blackfire client details:

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

4. Pass Blackfire server details:

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

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

• Access to New Relic with an APM account.
• Local: New Relic license key.
• The New Relic module.

Spryker provides its own New Relic licenses for use with its PaaS environments. A New Relic license key is only required if you wish to set up your own local monitoring.

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

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

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

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

• Deploying in a staging environment
• Deploying in a production environment

3. Submit an infrastructure change request via the Support Portal. We will confirm that a New Relic APM account is available for you and ensure that the correct application naming convention is set up to cascade to the appropriate APM.

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.

Local: Configure New Relic

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

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

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

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

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, please 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, please 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, null, false);
    }
}

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 Migration guide - Monitoring

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:

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

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

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