Beatbox Setup

Integration-level management tasks are only available to users with the correct permissions. See the Users documentation for more details.

Beatbox is a software version of the flow-server that is installed on-premises behind your own firewall. Flows can be deployed to Beatbox, but there are no Heartbeat features (like monitoring) available directly on Beatbox. However, Beatbox connects securely to the centralized flow-server, so any Beatbox-deployed flows can still be viewed and monitored in the same Heartbeat interface that you’ve always used.

System Requirements

Beatbox can only be installed on a 64-bit version of Linux. This can be on a dedicated server or virtual machine but must meet the following criteria:

Hardware Minimum requirements

Processor

Dual 64-bit processors. More processors allow for increased, simultaneous flow executions.

Memory

4 GB of RAM. More RAM allows for increased, simultaneous flow executions and might be required to process large data payloads.

Hard disk

500 MB for run-time and configuration, 10 GB for logs and data storage. SSD based storage is recommended for the best performance.

You will also need to install Docker (with Docker Compose), version 20.10.0 or higher.

Creating an ID

To get started with Beatbox, first create an ID in Heartbeat. Select Beatbox from the left-hand navigation menu, which will display the following page:

The list of beatbox instances includes a name, auto-generated ID, and status.

Select the Create button in the top-right corner and enter a name. An ID is automatically created afterwards. This is the ID that you will add to your Beatbox environment variables in the next step.

Beatbox IDs cannot be deleted. Contact Utilihive Support if you need to delete an ID.

Installing Beatbox

Utilihive Support will provide two things you need to install Beatbox: an archive of the Beatbox setup files and credentials to log into the private Docker registry. On your Linux machine, extract the setup files in the directory where you want the data to be stored. In a terminal window, navigate to the setup directory and execute the following command:

./init-beatbox.sh

This script creates the needed directories for local data (e.g., data/beatbox/logs) and confirms that you can log into Docker. Note that you might need to run the script with sudo if permissions are an issue.

The only other file you should touch at this time is the beatbox.env file. Open this file and fill in the following properties:

Property Description

BEATBOX_ID

The ID that was generated in Heartbeat.

UTILIHIVE_OWNER_ID

The ownerId of your organization.

UTILIHIVE_API_ENDPOINT

The remote API endpoint that logs and metrics are sent to. Provided by Utilihive Support.

UTILIHIVE_ENVIRONMENT

The kubernetes namespace environment that logs and metrics are sent to. Normally set to development, test, stage, or production.

Not to be confused with the mc.flow-server.admin.environment configuration property which is the environment name of the Beatbox installation. More on this can be found under Directory Layout

UTILIHIVE_LOG_INDEX

The index that logs are sent to. Provided by Utilihive Support.

UTILIHIVE_LOG_USERNAME

The username for sending logs. Provided by Utilihive Support.

UTILIHIVE_LOG_PASSWORD

The password for sending logs. Provided by Utilihive Support.

UTILIHIVE_METRICS_USERNAME

The username for sending metrics. Provided by Utilihive Support.

UTILIHIVE_METRICS_PASSWORD

The password for sending metrics. Provided by Utilihive Support.

DECRYPTION_KEY

The decryption key for any credentials stored in the config/utilihive-flow-server-override.properties file.

POSTGRES_PASSWORD

The password to use when initializing the local database. This is a password of your choosing but should not be changed after the first installation.

DEPLOYMENT_PUBLISHER_USER

The username of the Agent user for sending flow details. Only relevant if you are using OAuth2 Password Grant. See information about the two grant types supported below.

DEPLOYMENT_PUBLISHER_PASSWORD

The password of the Agent user for sending flow details. Only relevant if you are using OAuth2 Password Grant. See information about the two grant types supported below.

DEPLOYMENT_PUBLISHER_CLIENT_ID

The client ID of the service user used for publishing to the upstream server API. The user must have Agent role. Provided by Utilihive Support. Only relevant if you are using OAuth2 Client Credentials Grant. See information about the two grant types supported below.

DEPLOYMENT_PUBLISHER_CLIENT_SECRET

The client secret of the service user used for publishing to the upstream server API. The user must have Agent role. Provided by Utilihive Support. Only relevant if you are using OAuth2 Client Credentials Grant. See information about the two grant types supported below.

DEPLOYMENT_PUBLISHER_SCOPE

The scope of the token used for publishing to the upstream server API. Provided by Utilihive Support. Only relevant if you are using OAuth2 Client Credentials Grant. See information about the two grant types supported below.

DEPLOYMENT_TLS_CERTIFICATE_AUTHORITY_PEM

(Optional) The TLS certificate authority used for to verify upstream server in case it uses custom certificate authority. The certificate is in PEM format. Since this string contains newlines, you have to perform proper escaping in the configuration file.

DEPLOYMENT_PUBLISHER_HTTP_PROXY_URI

(Optional) URI for HTTP proxy.

DEPLOYMENT_PUBLISHER_HTTP_PROXY_USERNAME

(Optional) The username which will be used for HTTP proxy authentication.

DEPLOYMENT_PUBLISHER_HTTP_PROXY_PASSWORD

(Optional) The password which will be used for HTTP proxy authentication.
Two types of authentication grants towards the upstream server API are supported that differ in how do they obtain authentication token from the identity provider. `OAuth2 Password Grant (that requires DEPLOYMENT_PUBLISHER_USER and DEPLOYMENT_PUBLISHER_PASSWORD to be set) and OAuth2 Client Credential Grant (that requires DEPLOYMENT_PUBLISHER_CLIENT_ID, DEPLOYMENT_PUBLISHER_CLIENT_SECRET and DEPLOYMENT_PUBLISHER_SCOPE to be set). Those properties are mutually exclusive and only one of them should be set.

Afterwards, run the following command to download and start the necessary containers:

docker compose up -d

You can verify that Beatbox is running by making an HTTP request on the Beatbox machine to http://localhost:8090/actuator/health. In Heartbeat, the Beatbox status will display a green checkmark if the metrics endpoints are successfully connected.

If you plan to expose any HTTP-based services in your flows, the firewall on the Beatbox machine needs to have port 8080 open. You can accomplish this with a command such as ufw allow 8080.

Managing Beatbox

Beatbox flows and resources are deployed differently than using the SDK. See the Beatbox Deployments documentation for specifics.

After you deploy a flow to Beatbox, its flow traces will appear in Heartbeat alongside your other flows. See the Flow Traces documentation for information on filtering Beatbox data. If Agent user credentials were provided, deployed flows will also appear in the Flows page in Heartbeat.