Beatbox Deployments

Beatbox is an on-premise 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. Hence, deployment directories must adhere to the following pattern:

${AGENT_INSTALL_DIR}/data/beatbox/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

The 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. The target directory will contain a deployment .zip file. See the Advanced Deployer documentation for details.

The Beatbox deployment defines an environment variable DEPLOYMENT_ENVIRONMENT for the Beatbox installation. Deployable bundles must adhere to a directory structure of <ownerId>/<environment>.

Given CONNECT_OWNER_ID=myCompany and DEPLOYMENT_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 bundle file in your Beatbox installation, specifically in the ${AGENT_INSTALL_DIR}/data/beatbox/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 of all flows and restarts the remaining flows, whether or not the flow is modified.

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, the archive is moved to a failed folder.

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 a Beatbox must be in JSON format and saved as .json files in the flows directory. .zip bundle files end up as JSON files after being extracted. 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 one of the following changes to the flows directory is 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.

These flow management tasks are only attempted once, logging errors 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, like when some flow was 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 for 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?