Beatbox Deployments

Beatbox is an on-premises version of the flow-server. Make sure you have installed Beatbox according to the setup guide before attempting deployments.

Directory Layout

Beatbox uses a file-based deployer. It periodically checks a configured directory and performs flow management tasks based on the detected changes. The directory layout is similar to the SDK Deployer’s File System Mode, with added support for flows. Thus, the directories must adhere to the following pattern:

{rootManagementFolder}/deployment/{ownerId}/{environment}/{resource-type}

The values for rootManagementFolder and environment are set to their default values in utilihive-flow-server-defaults.properties, but can be overwritten in the config/utilihive-flow-server-override.properties Beatbox file. The defaults are rootManagementFolder=/data/beatbox and environment=beatbox. Example override:

mc.flow-server.admin.fileBasedDeployment.rootManagementFolder=/data/beatbox
mc.flow-server.admin.environment=test

If the rootManagementFolder is set to /data/beatbox, and the environment set to test, then a valid directory layout would look like the following:

data/
  beatbox/
    deployment/
      myCompany/
        test/
          flows/
            simple-rest-flow.json
          resources/
            simple-rest-api.json
            simple-rest-api.properties
          secrets/
            backendAuth.properties

Note that rootManagementFolder starts at the root of your Beatbox installation directory, not the root of your system.

Bundles

If you have been using the Lowcode DSL to develop flows, you can generate a bundled archive with the SDK Deployer that will resolve the necessary files and directories for you. See the Advanced Deployer documentation for details.

The Beatbox deployment contain a configuration property mc.flow-server.admin.environment which defines an environment for the Beatbox installation. Deployable bundles have to adhere to a directory structure of ownerId/environment.

Given ownerId=myCompany and mc.flow-server.admin.environment=myEnv, the following structure is required in the bundle:

zippedBundle/
  myCompany/
    myEnv/
      flows/
        ...
      resources/
        ...
      secrets/
        ...

After you have generated a bundle, place the .zip file in your Beatbox installation in the {rootManagementFolder}/deployment-bundle folder. Beatbox’s file-based deployer will automatically pick up and extract the archive, replacing all existing deployment files with the bundle files. This triggers a full redeployment, so existing flows that have not been deleted are restarted, even if they have not actually changed.

On success, the original files from the deployment folder are moved to a _previous_deployment folder, and the archive is moved to a deployed folder. If the deployment was unsuccessful, however, the archive is moved to a failed folder instead.

Given a rootManagementFolder of /data/beatbox, the bundle approach would result in the following directory layout:

data/
  beatbox/
    _previous_deployment/
    deployment/
    deployment-bundle/
      deployed/
      failed/

Flows

Flow specs intended for Beatbox must be in JSON format and saved (as .json files) in the flows directory. It is recommended to use the SDK Deployer’s bundle command to generate these JSON specs from Lowcode configurations.

The file-based deployer performs the following flow management tasks when changes to the flows directory are detected:

Adding a file triggers a flow deployment.
Changing a file triggers an update to the flow.
Removing a file triggers the deletion of the flow.

Such flow management tasks are only attempted once, with any errors being logged to the data/beatbox/logs/application.log file. A deployment or update can be retried, however, by changing the last modified timestamp of the respective file (e.g., by using the touch <flow-spec-file> command).

If the deployer fails to deserialize the contents of a flow spec file, the file is moved to a flows-invalid directory on the same level as the flows directory. If there is a mismatch between the ownerId in the flow spec and the name of the deployment subdirectory, the flow file is moved to a flows-owner-id-misconfiguration directory.

You cannot create an empty file in the flows directory and then populate it later. The deployer will most likely pick up the change event on the empty file creation and consider it an invalid flow.

Command Files

One-shot commands can be provided to the deployer via specially named files. This is useful in cases where the flow-server and local directories aren’t in sync (i.e., some flows were deployed via the Customers Management API). The following files can be created in the flows directory to trigger the action defined by their extension:

<flow-spec-id>.delete
<flow-spec-id>.redeploy

The file is immediately deleted after the task is initiated, whether or not it is ultimately successful.

Resources and Secrets

The file-based deployer can also deploy resources and secrets that are present in the resources and secrets directories, respectively. However, these directories are not actively monitored for changes. Resources and secrets are only deployed when they are referenced by a flow being deployed. Thus, a flow must be redeployed to pull in any updates to a related resource or secret. If nothing about the flow spec itself has changed, then you can trigger a resource pickup by restarting the flow with a .redeploy file.

Resources and secrets are managed in the same way as they are in the SDK Deployer. This means resources are represented as two files: a .json file for the actual content and a .properties file for the metadata. Secrets are a single .properties file.

The file-based deployer only supports resource references with a revision of latest (e.g., OpenAPIv3:my-api-spec:latest).

Was this page helpful?