CaaS Connect: Documentation for Administrators

1. Introduction

Content as a Service provides the editorial data of FirstSpirit via a uniform JSON-based data format that can be consumed by any endpoint. Using the CaaS Connect module reduces the configuration and administration effort in the FirstSpirit project for the delivery layer considerably.

In the remainder of this document the abbreviation CaaS will be used instead of Content as a Service.

1.1. Technical requirements

Besides the FirstSpirit version 5.2.240208, the module requires access to the CaaS platform.

An API key with appropriate permissions must be configured, and the accessibility of the platform endpoint over the network must be ensured. For more information on installing and using the CaaS platform, refer to the appropriate documentation.

2. Installation of the module

The module has no dependencies on other modules and can therefore be installed very easily on the FirstSpirit server. Since projects must be explicitly marked as CaaS projects, the project data is not automatically synchronized after the module is installed. In order for the module to work as expected, the service component must be configured.

After installation or update of the module, restarting the FirstSpirit server is required.

3. Components

In the following chapters all components of the module and their administration are described.

3.1. Service

The service component CaaS Connect Service is the link between the projects on the FirstSpirit server and the CaaS platform. In order for project content to be transferred to the platform, the service must be started. If the service is stopped, no synchronization takes place.
A valid configuration is required to operate the service. The configuration dialog of the service component CaaS Connect Service shows which fields are optional or mandatory. If a field is empty or the entry is invalid, the field is highlighted with a red border. The different configuration points are explained in more detail in the chapter Configuration via the file system. The minimal configuration includes a reachable CaaS platform and an API key that has read and write access to all CaaS projects.
More information about API keys and permissions can be found in the CaaS platform documentation.

Figure 1. Configuration dialog of the CaaS Connect Service component

Please note that when the CaaS module service is started, it checks if a connection to the CaaS platform can be established. If this connection check fails an error message will be appended to the FirstSpirit server log.

The tenant ID may consist of a maximum of 63 characters and is not case-sensitive.

If password encryption is set active in the FirstSpirit server, the values for API Key and Secret access key (S3) get automatically encrypted whenever the configuration is saved via the dialog and upon service start. The values in the dialog are then presented in ciphertext.

A detailed explanation of the resulting URL scheme can be found in the CaaS Connect documentation.

3.1.1. Media hosting

Media binary data can be stored either in the CaaS platform or in an S3-compatible service. Uploading binary data to the CaaS platform is the default configuration. If binary data is to be delivered via a S3 service, the configuration of the service component CaaS Connect Service must be adjusted accordingly.

If the media hosting option is changed, previous binary data URLs become invalid. As soon as a medium is changed or released again, both binary data and URLs are updated. If needed, a full synchronization can be performed to avoid having to make project changes. The schedules that were automatically created can be used to trigger a full synchronization for this purpose.

Hosting via S3: Both Amazon S3 and S3-compatible services can be used for delivery. The specification of an S3 endpoint is optional. If no end point is specified, it is assumed that Amazon S3 is being accessed. In this case, a client region must be specified so that the Amazon end point can be determined. It is composed as follows: s3.$clientRegion.amazonaws.com. The access credentials for the S3 service are also optional. If there is no specification in the configuration, environment variables and system properties are evaluated. Further information about such a configuration can be found in the official Amazon S3 documentation.

If an S3-compatible service is used without using a CloudFront domain, the links of the binary data of media files will use the virtual hosted-style format. For more information about the format and its limitations see Virtual hosting of buckets and Amazon S3 Path Deprecation Plan.

3.2. Project component

When adding the project component CaaS Connect project app to a project, it activates the CaaS Connect module for that project. The configuration dialog of the project component displays useful information like the CaaS base URLs and offers project specific configurations options.

Figure 2. Configuration dialog of the project component of CaaS Connect

The configuration of the URL Factory, which is used to generate media binary URLs, as well as dataset and pageRef routes, can be overridden on a project-specific basis. We recommend using a URL Factory that uses the FirstSpirit Registry as persistence. Of the standard FirstSpirit URL factories, the following use the FirstSpirit Registry: Advanced URLs, Default URLs (SEO), Multiview URLs (SEO) and Infix URLs (SEO).

After changing the URL factory configuration it is necessary to overwrite all CaaS content to apply these changes. For more information on how to overwrite the CaaS content using the schedules see Overwrite the complete data set.

The configured URL Factory is used to generate media binary URLs when the hosting of media binary data is disabled through the NoBinaryUpload option in the module configuration or when the S3 option is used in combination with CloudFront.

The displayed project-specific API keys are automatically generated by the CaaS Connect module. For preview and release of the project, one API key with read only permission and one API key with read and write permission are provided.

It is necessary to restart the service after making changes to the configuration. Only then will they be active.

3.3. Schedules

Additionally, multiple schedules are created after adding the project component to a project. The schedules synchronize the preview or release content between FirstSpirit and the CaaS platform.

More information is available in the chapter Manual data reconciliation of the module documentation.

In case of pre-existing project content these schedules can be used to populate the CaaS as well.

4. Configuration via the file system

Besides the manual configuration via the FirstSpirit user interface, CaaS Connect version 3 or later on can also be configured via the file system. To achieve this, all that is necessary is to create a JSON configuration file. The service CaaS Connect Service automatically loads the file caasConnect.json at startup, which must be located in the FirstSpirit server in ./conf/modules/CaasConnect.CaasConnectService/caasConnect.json. The following examples show the format of the configuration file that is required and supported.

Never use the values of the sample configurations on your test or production systems as is, but replace them with values specific to your project.

Minimal configuration, content of the caasConnect.json file

{
  // The CaaS platform endpoint
  "baseUrl":"http://localhost:8080",
  // The API key that is used for data transfer between module and platform
  "apiKey": "ef27ef88-11c1-4ba0-946c-5c82d2880a18",
  // The name or abbreviation of the tenant
  "tenantId": "defaultTenant"
}

Content of the caasConnect.json file

{
  // URL to the API of the CaaS platform
  "baseUrl": "http://localhost:8080",
  // API key for data transfer between module and platform
  "apiKey": "ef27ef88-11c1-4ba0-946c-5c82d2880a18",
  // The name or identifier of the tenant
  "tenantId": "defaultTenant",
  // (Optional) Configuration for uploading and serving media files via an S3 bucket
  // Default configuration: CaaS is used to serve media files
  "mediaConnectorConfig" : {
    "S3": {
      // (Optional) URL to an S3-compatible API endpoint
      // Default configuration: AWS API endpoint (https://s3.{region}.amazonaws.com)
      "endpointUri": "https://s3.eu-central-1.amazonaws.com",
      // (Optional) S3 credentials for uploading media files
      // Default configuration: uses the "Default provider chain" of the AWS Java SDK (see https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html#credentials-chain)
      "credentials": {
        "accessKeyId": "mySecretS3KeyId",
        "secretAccessKey": "mySecretS3AccessKey"
      },
      // Name of the S3 bucket
      "bucketName": "examplebucketname",
      "timeoutInSeconds": 10,
      // (Optional) region of the bucket
      // Default configuration: uses the "Default region provider chain" of the AWS SDK (see https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/region-selection.html#automatically-determine-the-aws-region-from-the-environment)
      "clientRegion": "eu-central-1",
      // (Optional) "Cache-Control" metadata attribute added to the S3 object when uploading to the bucket
      // Default configuration: maxAge 300 seconds (5 minutes), maxAgeShared 900 seconds (15 minutes)
      "cacheControl": {
        "maxAge": {
          "seconds": 100
        },
        "maxAgeShared": {
          "seconds": 150
        }
      },
      // (Optional) Configuration to service media files via CloudFront distribution.
      // Default configuration: URL of the S3 bucket in virtual-hosted-style is used to serve media files (e.g. https://examplebucketname.s3.{region}.amazonaws.com/)
      "cloudFront": {
        // (Optional) URL to a CloudFront-compatible API endpoint
        // Default configuration: AWS CloudFront API endpoint (https://cloudfront.amazonaws.com)
        "endpointUri": "https://cloudfront.amazonaws.com",
        // Id of the CloudFront distribution
        "distributionId": "A4L1CDF3GND316",
        // Base url of the CloudFront domain
        "baseUrl": "https://my-cloudfront-domain.com",
        // (Optional) Enables/disables manual invalidation of files in the CloudFront CDN
        // Default configuration: files are not manually invalidated (invalidateFiles = false)
        "invalidateFiles": false
      },
      // (Optional) URL Factory that is used to generate SEO routes in media documents
      "seoRouteFactory": "Advanced URLs"
    }
  },
  // (Optional) Endpoint of an HTTP proxy to use for communication with the CaaS platform or other services (S3, CloudFront)
  "proxyAddress": "foo:123"
}

If an error occurs while the service is reading the configuration file, a corresponding error message is displayed in the FirstSpirit log. Since the service cannot start without a valid configuration file, the functionality of the module is severely limited in this case.

Please note that when the CaaS module service is started, it checks if a connection to the CaaS platform can be established. An unsuccessful connection attempt on the part of the module will then result in an error message in the FirstSpirit server log.

Some configuration values are subject to further restrictions besides optionality, for example, a bucket name cannot contain uppercase letters. Invalid values are displayed directly in the user interface and cannot be saved. If such an invalid configuration is stored as a file, a corresponding error message will appear in the FirstSpirit log and the service will not start.

It is necessary to restart the service after making changes to the configuration. Only then will they be active.

If password encryption is set active in the FirstSpirit server, apiKey and mediaConnectorConfig.S3.credentials.secretAccessKey are automatically encrypted. See FirstSpirit documentation for Administrators for more details. Please note that the module uses an internally defined key for encryption and does not use any of the values given in password.encryption.key.\*.

Adding a project component to a project is also possible via the FirstSpirit API.

ModuleAdminAgent.installProjectApp("CaasConnect", caasConnectProjectAppName, project)

5. Error handling

Invalid configuration or network problems may cause errors on the CaaS Connect module side. All errors are logged in the FirstSpirit log.

5.1. Network error or overload

The module depends on the full availability of the CaaS platform. If the platform is not available or cannot process incoming requests fast enough, the module tries to repeat the requests. If this does not succeed either, an error is displayed in the FirstSpirit log and possible changes to the data are not synchronized with the CaaS platform. The editor is not notified of the error, so monitoring the server log by the administration is essential. If an error occurs it can be corrected either by executing the schedules or by repeating the action that lead to the data change.

5.2. Configuration of the API key

The API key configured in the service component is used to synchronize all projects on the server with the CaaS platform. The API key therefore requires write and read permissions for all CaaS projects, on the FirstSpirit server. For more information on configuring API keys, refer to the CaaS platform documentation.

5.3. Push notifications (change streams).

The change stream definitions can be found in the metadata of the collections. They are created at the same time as the collection. If the definitions are missing, they can be restored by triggering a new deployment by executing a schedule.

6. Legal information

The CaaS is a product of Crownpeak Technology GmbH, Dortmund, Germany.

Only a license agreed upon with Crownpeak Technology GmbH is valid with respect to the user for using the module.

Details of any third-party software products not produced by Crownpeak Technology GmbH that are used, their own licenses and any update information can be found in the META-INF/licenses.csv file supplied with the module.

7. Help

The Technical Support of the Crownpeak Technology GmbH provides expert technical support covering any topic related to the FirstSpirit™ product. You can get and find more help concerning relevant topics in our community.

8. Disclaimer

This document is provided for information purposes only. Crownpeak Technology GmbH may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. Crownpeak Technology GmbH specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.