Start from a Git Deployment

Overview

The Intelligence Hub can load its configuration from a deployment file stored in a Git repository each time it starts. This page shows the simplest setup, where a single deployment file in Git holds the full hub configuration, and covers how to start the hub with it on Windows, Linux/macOS, and Docker.

The setup uses two files:

  • Deployment file: The hub configuration, stored in the Git repository. This is the file produced by Git Backup, by a project Export to Git, or by the export command. The examples on this page use intelligencehub-deployment.json on the main branch.
  • Deployment settings file: A small JSON file stored on the hub host that tells the hub which repository, branch, and file to load. See Git Integration for the full schema.

To assemble the configuration from several files or repositories, first complete the setup on this page, and then see Layered Deployment Example.

The hub reads the location of the deployment settings file from the HIGHBYTE_DEPLOYMENT_FILE environment variable. The variable is read by the Intelligence Hub itself rather than by the start scripts, so no changes to the scripts in the runtime directory are required.

Environment Variables

Environment VariableDescription
HIGHBYTE_DEPLOYMENT_FILEPath to the deployment settings file. When set, the hub fetches the configuration described by the file during start-up. When not set, the hub starts with the configuration already in appData.

Deployment Settings File

The following deployment settings file loads intelligencehub-deployment.json from the root of the main branch. The fragment has no keyPaths, so the entire deployment file is applied.

{
  "version": 1,
  "repos": [ {
    "type": "git",
    "name": "hub-config",
    "uri": "https://github.com/<org>/<repo>.git",
    "author": "",
    "email": "",
    "auth": {
      "type": "pass",
      "username": "<user>",
      "password": "<token>"
    }
  } ],
  "fragments": [ {
    "type": "hub",
    "details": {
      "type": "git",
      "repoName": "hub-config",
      "ref": "main",
      "patterns": [ "intelligencehub-deployment.json" ]
    },
    "keyPaths": []
  } ]
}
FieldValue
uriThe HTTPS URI of the repository.
username, passwordA user with read access to the repository, and a password or personal access token. For a public repository, set auth to { "type": "none" }. To use a GitHub App, see Git Integration.
refThe branch to load from.
patternsThe path of the deployment file, relative to the root of the repository. This matches the Deploy File setting in Git Backup.

The hub does not modify the deployment settings file, so a token entered in plain text stays in plain text. Store the file where it can be permission restricted. To encrypt the token, see the encrypt command.

Setup

To start a hub from a deployment file in Git, follow the steps below.

  1. Install the hub.

  2. Commit the deployment file to the Git repository, for example by configuring Git Backup on an existing hub and selecting Backup Now.

  3. If the deployment file contains secrets or encrypted connection credentials, copy the intelligencehub-certificatestore.pkcs12 file from the appData of the hub that produced the deployment file to the appData of the new hub so it can decrypt them. If the store password on the source hub was changed with set-password or rotate-password, also set the HIGHBYTE_STORE_PASSWORD environment variable to that password for the new hub, in the same place as HIGHBYTE_DEPLOYMENT_FILE in step 5. Without it, the hub cannot open the copied store and does not start.

  4. Create the deployment settings file on the hub host.

  5. Set the environment variable. Where it is set depends on how the hub runs. See Command Line, Windows Environment Variables, Windows Service, Linux systemd Service, or Docker for specifics.

  6. Start the hub, then sign in and confirm that the configuration from the repository is loaded.

Command Line

To try a deployment from a terminal, set the variable for the current session and run the start script from the runtime directory.

Windows (Command Prompt):

set HIGHBYTE_DEPLOYMENT_FILE=C:\highbyte\deployment\deployment-settings.json
start-windows.bat

Windows (PowerShell):

$env:HIGHBYTE_DEPLOYMENT_FILE = "C:\highbyte\deployment\deployment-settings.json"
.\start-windows.bat

Linux:

HIGHBYTE_DEPLOYMENT_FILE=/opt/highbyte/deployment/deployment-settings.json ./start-linux.sh

macOS:

HIGHBYTE_DEPLOYMENT_FILE=/opt/highbyte/deployment/deployment-settings.json ./start-macos.sh

The variable only applies to that session. To keep it across sessions on Windows, see Windows Environment Variables. For a hub that starts automatically, set it on the service as described below.

Windows Environment Variables

On Windows, the variable can be stored as a User variable or a System variable so that it does not need to be set in each session:

  • User variables apply to processes started by that user, such as running start-windows.bat from a terminal. They do not require administrator rights.
  • System variables apply to every user and to services. The HighByte Intelligence Hub Runtime service runs as the Local System account and does not see User variables, so use a System variable when running as a service. They require administrator rights.

To set the variable using the Environment Variables dialog:

  1. Open the Start menu and search for environment variables.
    • For a User variable, select Edit environment variables for your account.
    • For a System variable, select Edit the system environment variables, and then select Environment Variables on the Advanced tab.
  2. Under User variables or System variables, select New.
  3. Enter HIGHBYTE_DEPLOYMENT_FILE as the Variable name, and the full path to the deployment settings file as the Variable value, for example C:\highbyte\deployment\deployment-settings.json.
  4. Select OK to close each dialog.

To set the variable from the command line instead, use setx. The first command sets a User variable. The second sets a System variable and must be run from a Command Prompt opened with Run as administrator:

setx HIGHBYTE_DEPLOYMENT_FILE "C:\highbyte\deployment\deployment-settings.json"
setx /M HIGHBYTE_DEPLOYMENT_FILE "C:\highbyte\deployment\deployment-settings.json"

To stop loading the deployment from Git, delete the variable in the same dialog. When running from a terminal, open a new window before starting the hub again. When running as a service with a System variable, restart the computer, because the service keeps the previous value until then, as described in Windows Service. The hub then starts with the configuration that was last applied.

Windows Service

The HighByte Intelligence Hub Runtime service starts the hub by calling start-windows.bat, so the environment variable must be available to the service process.

Define the variable as a System variable, as described in Windows Environment Variables, or add an env element inside the <service> element of runtime\service\service-installer-windows.xml, which limits the variable to the service:

<env name="HIGHBYTE_DEPLOYMENT_FILE" value="C:\highbyte\deployment\deployment-settings.json"/>

Restart the HighByte Intelligence Hub Runtime service to apply changes to the env element.

Linux systemd Service

Add the environment variable to the [Service] section of the unit file:

Environment=HIGHBYTE_DEPLOYMENT_FILE=/opt/highbyte/deployment/deployment-settings.json

Alternatively, point to a separate file that holds it:

EnvironmentFile=/etc/highbyte/deployment.env

The /etc/highbyte/deployment.env file contains one variable per line:

HIGHBYTE_DEPLOYMENT_FILE=/opt/highbyte/deployment/deployment-settings.json

Reload the unit and restart the service to apply the change:

sudo systemctl daemon-reload
sudo systemctl restart highbyte.service

Docker

When running the Intelligence Hub in Docker, mount the deployment settings file into the container and set the environment variable to its path inside the container.

docker run -p 45245:45245 -p 1885:1885 -p 8885:8885 -e ACCEPT_EULA=Y --name highbyte \
  --mount source=hb_vol,target=/usr/local/highbyte/appData \
  --mount type=bind,source=<folder>,target=/usr/local/highbyte/deployment,readonly \
  --restart=unless-stopped \
  -e HIGHBYTE_DEPLOYMENT_FILE=/usr/local/highbyte/deployment/deployment-settings.json \
  highbyte:X.X.X

<folder> is the directory on the host that holds deployment-settings.json. The deployment is applied each time the container starts, so restarting the container with docker restart highbyte loads the latest commit on the branch.

If the deployment file contains secrets, copy intelligencehub-certificatestore.pkcs12 into the volume before starting the container. If the store uses a non-default password, also pass it with -e HIGHBYTE_STORE_PASSWORD=<password>. See High Availability - Docker for an example of copying the file into a volume.