App Composition Platform installation

Last updated:
Edit on GitHub

This document describes how you can make your project ACP-ready and how you install ACP.

Installing ACP in SCOS

Prerequisite

To be eligible for ACP, your project must be hosted in the Spryker Cloud.

The ACP catalog is integrated into the Back Office and contains the list of applications you can connect to your shop.

You can access the ACP catalog only if you are a SCOS customer and have been enabled for ACP. This means that your SCOS environment needs to be properly set up and registered with ACP.

The installation process of ACP on SCOS is also called ACP enablement. It involves multiple steps that require actions from both you and Spryker. The first step implies making your SCOS project ACP-ready, meaning that the required ACP modules are up-to-date and the SCOS Cloud environment is configured correctly. The second step is making your project ACP-enabled by registering your SCOS project with the Spryker’s ACP. This enables the ACP Catalog in the Back Office to interact with ACP, allowing you to browse, connect, and configure ACP applications for use with SCOS.

The following diagram illustrates the different steps of the ACP enablement process and outlines the responsibilities for executing them.

Info

The actions and level of effort required to make your project ACP-ready may vary depending on the update status of your SCOS module versions. However, the process of making your project ACP-enabled is always handled by Spryker.

Getting SCOS ACP-ready

To make your project ACP-ready, different update steps are necessary depending on the template version on which your project was started:

  • SCOS product release 202211.0: All the changes required for ACP readiness are already included, but you should still verify them at the project level.
  • Older versions: To get the project ACP-ready, you should complete all steps described in this document.
Product version ealier than 202211.0

If you were onboarded with a version older than product release 202211.0, please contact us.

1. Module updates for ACP

To get your project ACP-ready, it is important to ensure that your project modules are updated to the necessary versions.

1. ACP modules

Starting with the Spryker product release 202211.0, the ACP catalog is included by default in the Spryker Cloud product. However, you should still make sure that your Spryker project uses the latest versions of the following modules:

  • spryker/app-catalog-gui: ^1.2.0 or higher
  • spryker/message-broker:^1.4.0 or higher
  • spryker/message-broker-aws:^1.3.2 or higher
  • spryker/session:^4.15.1 or higher

2. App modules

Apps- and PBC-specific modules

Depending on the specific ACP apps or PBCs you intend to use via ACP, you will need to add or update the modules for each respective app or PBC as explained in the corresponding app guide.

The Spryker ACP Apps are continuously enhanced and improved with new versions. Though you don’t have to update the apps themselves, it might be at times necessary to perform minor updates of the app-related SCOS modules to take full advantage of the latest app feature updates.

For each app you wish to use, ensure that you have the latest app-related SCOS modules installed. The following apps are supported:

2. Configure SCOS

Once you have ensured that your project modules are up-to-date, proceed to configure your SCOS project to activate the ACP catalog in the Back Office using the following steps:

  1. Define the configuration and add plugins to the following files:
config/Shared/config_default.php 
use Spryker\Shared\AppCatalogGui\AppCatalogGuiConstants;
use Spryker\Shared\Kernel\KernelConstants;
use Spryker\Shared\MessageBroker\MessageBrokerConstants;
use Spryker\Shared\MessageBrokerAws\MessageBrokerAwsConstants;
use Spryker\Shared\OauthAuth0\OauthAuth0Constants;
use Spryker\Shared\OauthClient\OauthClientConstants;
use Spryker\Shared\Store\StoreConstants;
use Spryker\Zed\OauthAuth0\OauthAuth0Config;

...

// ----------------------------------------------------------------------------
// ------------------------------ ACP -----------------------------------------
// ----------------------------------------------------------------------------
$aopApplicationConfiguration = json_decode(html_entity_decode((string)getenv('SPRYKER_AOP_APPLICATION')), true);
$config[KernelConstants::DOMAIN_WHITELIST] = array_merge(
    $config[KernelConstants::DOMAIN_WHITELIST],
    $aopApplicationConfiguration['APP_DOMAINS'] ?? [],
);
$config[StoreConstants::STORE_NAME_REFERENCE_MAP] = $aopApplicationConfiguration['STORE_NAME_REFERENCE_MAP'] ?? [];
$config[AppCatalogGuiConstants::APP_CATALOG_SCRIPT_URL] = $aopApplicationConfiguration['APP_CATALOG_SCRIPT_URL'] ?? '';

$aopAuthenticationConfiguration = json_decode(html_entity_decode((string)getenv('SPRYKER_AOP_AUTHENTICATION')), true);
$config[OauthAuth0Constants::AUTH0_CUSTOM_DOMAIN] = $aopAuthenticationConfiguration['AUTH0_CUSTOM_DOMAIN'] ?? '';
$config[OauthAuth0Constants::AUTH0_CLIENT_ID] = $aopAuthenticationConfiguration['AUTH0_CLIENT_ID'] ?? '';
$config[OauthAuth0Constants::AUTH0_CLIENT_SECRET] = $aopAuthenticationConfiguration['AUTH0_CLIENT_SECRET'] ?? '';

$config[MessageBrokerConstants::CHANNEL_TO_TRANSPORT_MAP] =
$config[MessageBrokerAwsConstants::CHANNEL_TO_RECEIVER_TRANSPORT_MAP] = [
    // Here we will define the receiver transport map accordinally to APP (PBC)
];

$config[MessageBrokerAwsConstants::CHANNEL_TO_SENDER_TRANSPORT_MAP] = [
    // Here we will define the sender transport map accordinally to APP (PBC)
];

$aopInfrastructureConfiguration = json_decode(html_entity_decode((string)getenv('SPRYKER_AOP_INFRASTRUCTURE')), true);

$config[MessageBrokerAwsConstants::SQS_RECEIVER_CONFIG] = json_encode($aopInfrastructureConfiguration['SPRYKER_MESSAGE_BROKER_SQS_RECEIVER_CONFIG'] ?? []);
$config[MessageBrokerAwsConstants::HTTP_SENDER_CONFIG] = $aopInfrastructureConfiguration['SPRYKER_MESSAGE_BROKER_HTTP_SENDER_CONFIG'] ?? [];

// ----------------------------------------------------------------------------
// ------------------------------ OAUTH ---------------------------------------
// ----------------------------------------------------------------------------
$config[OauthClientConstants::OAUTH_PROVIDER_NAME_FOR_MESSAGE_BROKER] = OauthAuth0Config::PROVIDER_NAME;
$config[OauthClientConstants::OAUTH_GRANT_TYPE_FOR_MESSAGE_BROKER] = OauthAuth0Config::GRANT_TYPE_CLIENT_CREDENTIALS;
$config[OauthClientConstants::OAUTH_OPTION_AUDIENCE_FOR_MESSAGE_BROKER] = 'aop-event-platform';

$config[AppCatalogGuiConstants::OAUTH_PROVIDER_NAME] = OauthAuth0Config::PROVIDER_NAME;
$config[AppCatalogGuiConstants::OAUTH_GRANT_TYPE] = OauthAuth0Config::GRANT_TYPE_CLIENT_CREDENTIALS;
$config[AppCatalogGuiConstants::OAUTH_OPTION_AUDIENCE] = 'aop-atrs';

$config[OauthClientConstants::OAUTH_PROVIDER_NAME_FOR_PAYMENT_AUTHORIZE] = OauthAuth0Config::PROVIDER_NAME;
$config[OauthClientConstants::OAUTH_GRANT_TYPE_FOR_PAYMENT_AUTHORIZE] = OauthAuth0Config::GRANT_TYPE_CLIENT_CREDENTIALS;
$config[OauthClientConstants::OAUTH_OPTION_AUDIENCE_FOR_PAYMENT_AUTHORIZE] = 'aop-app';
  1. In the navigation.xml file, add one more navigation item:
config/Zed/navigation.xml 
...
  <app-catalog-gui>
      <label>Apps</label>
      <title>Apps</title>
      <icon>fa-cubes</icon>
      <bundle>app-catalog-gui</bundle>
      <controller>index</controller>
      <action>index</action>
  </app-catalog-gui>
...
  1. In the MessageBrokerDependencyProvider.php file, enable the following module plugins:
src/Pyz/Zed/MessageBroker/MessageBrokerDependencyProvider.php 
<?php

/**
 * This file is part of the Spryker Suite.
 * For full license information, please view the LICENSE file that was distributed with this source code.
 */

namespace Pyz\Zed\MessageBroker;

use Spryker\Zed\MessageBroker\Communication\Plugin\MessageBroker\CorrelationIdMessageAttributeProviderPlugin;
use Spryker\Zed\MessageBroker\Communication\Plugin\MessageBroker\TimestampMessageAttributeProviderPlugin;
use Spryker\Zed\MessageBroker\Communication\Plugin\MessageBroker\TransactionIdMessageAttributeProviderPlugin;
use Spryker\Zed\MessageBroker\Communication\Plugin\MessageBroker\ValidationMiddlewarePlugin;
use Spryker\Zed\MessageBroker\MessageBrokerDependencyProvider as SprykerMessageBrokerDependencyProvider;
use Spryker\Zed\MessageBrokerAws\Communication\Plugin\MessageBroker\Receiver\AwsSqsMessageReceiverPlugin;
use Spryker\Zed\MessageBrokerAws\Communication\Plugin\MessageBroker\Sender\HttpMessageSenderPlugin;
use Spryker\Zed\OauthClient\Communication\Plugin\MessageBroker\AccessTokenMessageAttributeProviderPlugin;
use Spryker\Zed\Session\Communication\Plugin\MessageBroker\SessionTrackingIdMessageAttributeProviderPlugin;
use Spryker\Zed\Store\Communication\Plugin\MessageBroker\CurrentStoreReferenceMessageAttributeProviderPlugin;
use Spryker\Zed\Store\Communication\Plugin\MessageBroker\StoreReferenceMessageValidatorPlugin;

class MessageBrokerDependencyProvider extends SprykerMessageBrokerDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\MessageBrokerExtension\Dependency\Plugin\MessageSenderPluginInterface>
     */
    public function getMessageSenderPlugins(): array
    {
        return [
            new HttpMessageSenderPlugin(),
        ];
    }

    /**
     * @return array<\Spryker\Zed\MessageBrokerExtension\Dependency\Plugin\MessageReceiverPluginInterface>
     */
    public function getMessageReceiverPlugins(): array
    {
        return [
            new AwsSqsMessageReceiverPlugin(),
        ];
    }

    /**
     * @return array<\Spryker\Zed\MessageBrokerExtension\Dependency\Plugin\MessageAttributeProviderPluginInterface>
     */
    public function getMessageAttributeProviderPlugins(): array
    {
        return [
            new CorrelationIdMessageAttributeProviderPlugin(),
            new TimestampMessageAttributeProviderPlugin(),
            new CurrentStoreReferenceMessageAttributeProviderPlugin(),
            new AccessTokenMessageAttributeProviderPlugin(),
            new TransactionIdMessageAttributeProviderPlugin(),
            new SessionTrackingIdMessageAttributeProviderPlugin(),
        ];
    }

    /**
     * @return array<\Spryker\Zed\MessageBrokerExtension\Dependency\Plugin\MiddlewarePluginInterface>
     */
    public function getMiddlewarePlugins(): array
    {
        return [
            new ValidationMiddlewarePlugin(),
        ];
    }

    /**
     * @return array<\Spryker\Zed\MessageBrokerExtension\Dependency\Plugin\MessageValidatorPluginInterface>
     */
    public function getExternalValidatorPlugins(): array
    {
        return [
            new StoreReferenceMessageValidatorPlugin(),
        ];
    }
}
  1. In the MessageBrokerConfig.php file, adjust the following module config:
src/Pyz/Zed/MessageBroker/MessageBrokerConfig.php 
<?php

/**
 * This file is part of the Spryker Suite.
 * For full license information, please view the LICENSE file that was distributed with this source code.
 */

namespace Pyz\Zed\MessageBroker;

use Generated\Shared\Transfer\MessageAttributesTransfer;
use Spryker\Zed\MessageBroker\MessageBrokerConfig as SprykerMessageBrokerConfig;

class MessageBrokerConfig extends SprykerMessageBrokerConfig
{
    /**
     * Defines attributes which should not be logged.
     *
     * @api
     *
     * @return array<string>
     */
    public function getProtectedMessageAttributes(): array
    {
        return [
            MessageAttributesTransfer::AUTHORIZATION,
        ];
    }
}
  1. In the OauthClientDependencyProvider.php file, enable the following module plugins:

In the MessageBrokerConfig.php, adjust the following module config:

src/Pyz/Zed/OauthClient/OauthClientDependencyProvider.php 
<?php

/**
 * This file is part of the Spryker Suite.
 * For full license information, please view the LICENSE file that was distributed with this source code.
 */

namespace Pyz\Zed\OauthClient;

use Spryker\Zed\OauthAuth0\Communication\Plugin\OauthClient\Auth0OauthAccessTokenProviderPlugin;
use Spryker\Zed\OauthClient\OauthClientDependencyProvider as SprykerOauthClientDependencyProvider;
use Spryker\Zed\Store\Communication\Plugin\OauthClient\CurrentStoreReferenceAccessTokenRequestExpanderPlugin;

class OauthClientDependencyProvider extends SprykerOauthClientDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\OauthClientExtension\Dependency\Plugin\OauthAccessTokenProviderPluginInterface>
     */
    protected function getOauthAccessTokenProviderPlugins(): array
    {
        return [
            new Auth0OauthAccessTokenProviderPlugin(),
        ];
    }

    /**
     * @return array<\Spryker\Zed\OauthClientExtension\Dependency\Plugin\AccessTokenRequestExpanderPluginInterface>
     */
    protected function getAccessTokenRequestExpanderPlugins(): array
    {
        return [
            new CurrentStoreReferenceAccessTokenRequestExpanderPlugin(),
        ];
    }
}

3. Update the SCOS deploy.yml file

This section describes the variables that you must configure for use within your SCOS AWS environment.

You need to define the environment variables in the deploy.yml file of each SCOS environment like testing, staging, and production. There will be multiple general environment variables that in turn will contain several configurations.

Warning

It is crucial to specify the keys for the environment variables. The infrastructure values, such as SPRYKER_AOP_INFRASTRUCTURE and STORE_NAME_REFERENCE_MAP are provided by Spryker OPS upon request.

General structure 
ENVIRONMENT_VARIABLE_NAME_A: '{
  "CONFIGURATION_KEY_A":"SOME_VALUE_A",
  "CONFIGURATION_KEY_B":"SOME_VALUE_B"
}'
Data structure example for a demo environment connected to the Spryker ACP production 
#AOP
SPRYKER_AOP_APPLICATION: '{
  "APP_CATALOG_SCRIPT_URL": "https://app-catalog.atrs.spryker.com/loader",
  "STORE_NAME_REFERENCE_MAP": {"DE": "tenant_messages_for_store_reference_AOP_Demo_Production-DE.fifo", "AT": "tenant_messages_for_store_reference_AOP_Demo_Production-AT.fifo"},
  "APP_DOMAINS": [
      "os.apps.aop.spryker.com",
      "*.bazaarvoice.com"
  ]
}'

SPRYKER_AOP_INFRASTRUCTURE: '{
  "SPRYKER_MESSAGE_BROKER_HTTP_SENDER_CONFIG": {
        "endpoint":"https:\/\/events.atrs.spryker.com\/events\/tenant"
  },
  "SPRYKER_MESSAGE_BROKER_SQS_RECEIVER_CONFIG": {
    "default": {
        "endpoint":"https:\/\/sqs.eu-central-1.amazonaws.com",
        "region":"eu-central-1",
        "auto_setup":false,
        "buffer_size":1
    },
      "DE": {
        "queue_name":"tenant_messages_for_store_reference_AOP_Demo_Production-DE.fifo"
    },
    "AT": {
        "queue_name":"tenant_messages_for_store_reference_AOP_Demo_Production-AT.fifo"
    }
  }
}'

General configurations: SPRYKER_AOP_APPLICATION variable

The configuration key APP_CATALOG_SCRIPT_URLis the URL for the App-Tenant-Registry-Service (ATRS) and path to the JS script to load the ACP catalog.

Example of the production ATRS_HOST and path:

https://app-catalog.atrs.spryker.com/loader

The configuration key: STORE_NAME_REFERENCE_MAP is the StoreReference mapping to the appropriate Spryker store.

Spryker OPS

The StoreReference mapping is created by Spryker OPS, and they provide you with the corresponding values to be added to your deploy.yml file.

Example of demo stores for DE and AT:

{"DE": "tenant_messages_for_store_reference_AOP_Demo_Production-DE", "AT": "tenant_messages_for_store_reference_AOP_Demo_Production-AT"}

The configuration key APP_DOMAINS designates the app domains used in redirects.

Spryker OPS

The app domains are provided by Spryker OPS.

Example of the app domain values:

[
  "os.apps.aop.spryker.com",
  "*.bazaarvoice.com"
]

Message Broker configuration: SPRYKER_AOP_INFRASTRUCTURE variable

The configuration key SPRYKER_MESSAGE_BROKER_SQS_RECEIVER_CONFIG is for the receiver configuration. The queues must be defined for each store, or a default queue for all stores is to be defined.

Spryker OPS

The queues are created by Spryker OPS, and they provide you with the corresponding values to be added to your deploy.yml file.

Example of the receiver configuration for the Spryker production environment:

{
  "default": {
    "endpoint":"https://sqs.eu-central-1.amazonaws.com",
    "auto_setup":false, "buffer_size":1
  },
  "DE": {
    "queue_name":"tenant_messages_for_store_reference_AOP_Demo_Production-DE.fifo"
  },
  "<Store Reference>": {
    "queue_name":"queue_name_for_store_reference_<Store>"
  }
}

Example of the SPRYKER_MESSAGE_BROKER_HTTP_SENDER_CONFIG configuration key value:

{
    "endpoint":"https://events.atrs.spryker.com/events/tenant"
}

Next steps after the ACP-readiness

After configuring the files, updating all modules, and adding the requested keys with their corresponding values provided by Spryker OPS to the deploy.yml file, the SCOS codebase is now up-to-date. Once redeployed, your environment is ACP-ready.

The next step is to get your newly updated and deployed ACP-ready SCOS environment ACP-enabled. The ACP enablement step is fully handled by Spryker and implies registration of your ACP-ready SCOS environment with ACP by connecting it with the ACP App-Tenant-Registry-Service (ATRS) as well as the Event Platform (EP), so that the ACP catalog is able to work with SCOS.

To get your project ACP-enabled, contact the Spryker support.

Once all the steps of the ACP-enablement process are completed, the ACP catalog appears in the Back Office:

acp-catalog