Digital Distributed Containers (DDC)

A Digital Distributed Container subscription (Single and/or Multi Service Container) is required.

The Digital Distributed Container functionality allows to create stand alone container containing either a single or multiple services. Those containers can then be deployed on a container-based infrastructure and scaled according to the organization needs.

Single Service Container

Micro-service pattern: An individual service is exported as a container that can be deployed on your organization’s infrastructure. Licensed using a Single Service Container Tokens (SSCT)

Multi Service Container

Bundled-service pattern: Multiple services are selected and exported as a container that can be deployed on your organization’s infrastructure. Licensed using a Multi Service Container Tokens (MSCT)

Each container requires its own license token to execute. A token of the proper type (SSCT or MSCT) is required for each deployment. A deployment is defined as a container image being deployed in a single location. This means that locally scaling of a given container in the same location can be done with a single token, but geographical scaling requires a token per location.

Creating a Digital Distributed Container

In order to be able to build containers, the administrator must configure the base image for the containers.

The containers expose an HTTP port to its API on port 8181.

Single Service Container

Single service containers are automatically created when a service is published to the Service Library from the modelers.

Each execution environment can be configured to build the containers either locally or push them to a remote registry.

Multi Service Container

Multi service containers are built on demand from the Service Library by selecting the services to include in the container and pushing the container image to a remote registry.

Security in a Digital Distributed Container

The generated containers do not include a security layer. It is the responsibility of the organization to implement the security around the container.

Service storage

For services that require state persistence (long-running workflow and cases), it is possible to either use the file system through a persisted volume mounted under /data/des/pinstances or through a MongoDB connection.

By default, unless the proper environment variables are set, the file system persistence is used. If no persistent volume is mounted under /data/des/pinstances, the state will be deleted between container restart.

When using the file system persistence with multiple container instance running in parallel, the same persistent volume is required to be mounted on each container instance.

When MongoDB is configured (through environment variables), the storage is delegated to a MongoDB service (single or cluster) that can be scaled. Each service writes to its own database. Each data store (if subscribed) is stored in a separated database. Therefore, multiple services can share the same MongoDB service concurrently (either multiple single service containers or multiple multi service containers).

Override service descriptors

For services that communicate with external services e.g. REST apis, triggers etc, there is a need to provide different values so called service descriptors when deploying to various environments. A common case is given container is promoted via different environments (dev → test → prod) and then point it to different environments of the external systems.

Required service descriptors can be extracted from the container by running it with an environment DES_INFO=json set. An example docker run command would look like following:

docker run --rm --env DES_INFO=json container.registry.com:5001/services/bpmn/my-service:latest

This command will print following output:

{
  "prod/bpmn/my-service/1.0": [
    {
      "interfaceId": "_c9e1e003-ec00-47bc-abfe-10df53c1ed46", // 1
      "interfaceName": "Calculate Body Mass Index",
      "id": "6332b6e2-db81-4885-9a28-d20beb42e92e",
      "serviceUrl": "http://localhost:8080/execution", // 2
      "updated": "Mar 15, 2021, 12:17:11 PM",
      "name": "bpmn-test",
      "type": "oauth2", // 3
      "options": {  // 4
        "clientSecret": "to be set",
        "clientId": "to be set",
        "accessToken": "to be set",
        "tokenType": "Bearer",
        "refreshUrl": "http://localhost:8080/oauth2/token"
      }
    }
  ]
}
1 Service interface that defines communication with external system
2 URL of the external system
3 Authentication type
4 Authentication options, note that when taken out from the container all sensitive information are replaced with to be set

Users can use Service Descriptor Editor (available in Settings product) to modify service descriptors and then export it for deployment.

Service descriptors should be mounted under /data/des/system-identities folder as individual files. These files must follow env_group_artifact_version naming convention. Example could be prod_finance_my-service_1.0.

In case of multi service containers, each service’s service descriptors must be placed in separate file.

To avoid creating files for each service, file names can be reduced to be applied on higher level. Use file name prod_finance to apply to all services that are deployed to prod environment and are with finance group. Similar can be applied for all services in prod environment or all versions of prod_finance_my-service

Environment variables

Environment Variable Required Description

LICENSE

Required

The license token for this container.

PERSISTENCE_TYPE

Required for MongoDB Storage

Set to mongo to use the MongoDB service storage or to fs to use default file system persistence. Defaults to fs.

PERSISTENCE_MONGO_CONNECTION

Required for MongoDB Storage

The connection string of MongoDB.

PERSISTENCE_MONGO_USER

Optional for MongoDB Storage

The username to connect to MongoDB. This can also be defined in the connection string.

PERSISTENCE_MONGO_PASSWORD

Optional for MongoDB Storage

The password to connect to MongoDB. This can also be defined in the connection string.

PERSISTENCE_MONGO_DATABASE

Optional for MongoDB Storage

When using a username/password, authorization could be done on a different database than admin.

PERSISTENCE_MONGO_LOCK

Optional for MongoDB Storage

Number of milliseconds to consider a lock still valid on an instance. Defaults to 60 seconds.

PERSISTENCE_MONGO_LOCK_LIMIT

Optional for MongoDB Storage

Maximum time (in milliseconds) to try to acquire a lock. Defaults to 5000.

PERSISTENCE_MONGO_LOCK_WAIT

Optional for MongoDB Storage

Interval (in milliseconds) between trying to acquire locks. Defaults to 100 ms.

PERSISTENCE_FS_LOCK

Optional for File System Storage

Number of milliseconds to consider a lock still valid on an instance. Defaults to 60 seconds.

PERSISTENCE_FS_LOCK_LIMIT

Optional for File System Storage

Maximum time (in milliseconds) to try to acquire a lock. Defaults to 5000.

PERSISTENCE_FS_LOCK_WAIT

Optional for File System Storage

Interval (in milliseconds) between trying to acquire locks. Defaults to 100 ms.

TRIGGER_THREAD_COUNT

Optional configuration for trigger service

Number of threads that will process triggers such as timers, incoming messages (rabbitmq, apache kafka), etc. Defaults to 1.

SMTP_HOST

Required for services sending emails

SMTP hostname.

SMTP_PORT

Required for services sending emails

SMTP port number.

SMTP_TLS

Required for services sending emails

Set to "true" if the SMTP port requires TLS, omit otherwise (or set to "false").

SMTP_USERNAME

Optional for services sending emails

Optional username for the SMTP server if it is required.

SMTP_PASSWORD

Optional for services sending emails

Optional password for the SMTP server if it is required.

EMAIL_FROM

Optional for services sending emails

An email address to use in the FROM field if none was provided when sending an email.

EMAIL_TO

Optional for services sending emails

An email address to use in the TO field if none was provided when sending an email.

TZ

Optional

A timezone for the container. The values can be found in this wikipedia page in the TZ database name column (eg. Canada/Eastern). Defaults to host timezone.

DES_INFO

Optional

When set, container will only display information about itself instead of starting (allowed values: json, kubernetes, text). Used to get service descriptors (connectivity with external systems) utilized by the container’s services

VALIDATION_INTERFACES_STRICT

Optional

Controls validation mode of interfaces at startup, accepted values: true (to fail startup in case of validation errors) or false (to only log validation errors), defaults to false

SESSION_TIMEOUT

Optional

Controls the web session timeouts. This value is numeric and in number of minutes, defaults to no timeout