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
exportcommand. The examples on this page useintelligencehub-deployment.jsonon themainbranch. - 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.
backups directory in appData, according to the Backup Copies setting.Environment Variables
| Environment Variable | Description |
|---|---|
HIGHBYTE_DEPLOYMENT_FILE | Path 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. |
runtime directory, because the start scripts change into that directory before launching the hub.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": []
} ]
}
| Field | Value |
|---|---|
uri | The HTTPS URI of the repository. |
username, password | A 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. |
ref | The branch to load from. |
patterns | The 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.
Install the hub.
Commit the deployment file to the Git repository, for example by configuring Git Backup on an existing hub and selecting Backup Now.
If the deployment file contains secrets or encrypted connection credentials, copy the
intelligencehub-certificatestore.pkcs12file 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 withset-passwordorrotate-password, also set theHIGHBYTE_STORE_PASSWORDenvironment variable to that password for the new hub, in the same place asHIGHBYTE_DEPLOYMENT_FILEin step 5. Without it, the hub cannot open the copied store and does not start.Create the deployment settings file on the hub host.
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.
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.batfrom 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:
- 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.
- Under User variables or System variables, select New.
- Enter
HIGHBYTE_DEPLOYMENT_FILEas the Variable name, and the full path to the deployment settings file as the Variable value, for exampleC:\highbyte\deployment\deployment-settings.json. - 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"
start-windows.bat, because windows that are already open keep the previous values. For the service, see the warning in Windows Service.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.
runtime directory, so changes made to service-installer-windows.xml need to be applied again after an upgrade. Keep the deployment settings file outside the runtime directory for the same reason. See Run as a Service for details on the service and its configuration file.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
sudo chmod 600 /opt/highbyte/deployment/deployment-settings.json, so that the repository credentials are not readable by other users.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.