Overview
This guide will walk you through the following steps:
Configuring Github as your storage provider
Creating a Maverics environment to publish config to Github
Deploying an orchestrator to read the config in Github
Prerequisites
Gitlab account, permissions to create a repo and generate access tokens
Permissions in your host environment install the orchestrator service
Configure storage provider
You will utilize Github to publish configurations from the Maverics Console, which your orchestrators will access. The Maverics Console must have permissions to both read and write to this bucket, while the orchestrators will need read-only access.
Create a Gitlab token for a repo
We recommend creating two tokens:
One with read and write permissions for the Maverics Console
One with read-only permission for the Orchestrator host
See the Gitlab topic, Personal access tokens for more information on how to retrieve the token to your repo.
After you’ve verified your email address in Gitlab and created a new repository for Maverics, follow the steps below to generate a token:
On the left sidebar, click your avatar. Click Preferences.
On the left sidebar, click Access tokens.
Click Add new token.
In Token name, enter a name for the token.
In Expiration date, enter an expiration date for the token. The token expires on that date at midnight UTC. A token with the expiration date of 2024-01-01 expires at 00:00:00 UTC on 2024-01-01.
If you do not enter an expiry date, the expiry date is automatically set to 365 days later than the current date.
By default, this date can be a maximum of 365 days later than the current date. In GitLab 17.6 or later, you can extend this limit to 400 days.
In Select Scopes, click the checkbox for read_repository and write_repository. Select Create personal access token.
Copy the contents of the field under Your new personal access token. Copy this to a safe place as you will need it for the next section.
Repeat these steps to create a token for.the orchestrator service
In Select Scopes, click the checkbox for read_repository Maverics Console Configuration Storage
Maverics Console Configuration Storage
Go to Deployments.
Next to Configuration Storage, click Edit.
From the dropdown menu, select Gitlab repository
.png?sv=2022-11-02&spr=https&st=2025-05-05T18%3A52%3A58Z&se=2025-05-05T19%3A11%3A58Z&sr=c&sp=r&sig=lOW7a%2Fa21us%2BmEmxRQYrWIs7NqAZjD%2BzWXbqgzL%2BpTI%3D)
Click to enlarge
Field | Description |
---|---|
Namespace | Your Gitlab organization name. |
Repo | The name of your Gitlab repo. |
Branch | The name of your branch in the Gitlab repo |
Token | The access token to your Gitlab repo. Repository read and Repository write access is required. |
Optional Configuration File Path | The path to the configuration file in your Github repo. |
Orchestrator Remote Config
If you are using the silent install process and the Windows machine will connect directly to a Maverics cloud environment, use the following PowerShell script as a template and update the configuration values as required:
# Set the configuration values
$RegistryPath = 'HKLM:\SYSTEM\CurrentControlSet\Services\mavericsSvc'
$Name = 'Environment'
$Value = @('MAVERICS_HTTP_ADDRESS=127.0.0.1:8888',
'MAVERICS_POLLING_INTERVAL_SECONDS=30',
'MAVERICS_RELOAD_CONFIG=true',
'MAVERICS_GITLAB_CONFIG={ "token":"GITHUB_TOKEN", "namespace":"ORGANIZATION_NAME", "repo":"REPO_NAME", "branch":"BRANCH_NAME","configurationFilePath": "GITLAB_CONFIGURATION_FILE_PATH" }',
'MAVERICS_BUNDLE_PUBLIC_KEY_FILE=C:\config\public_key.pem',
'MAVERICS_CONFIGURATION_TYPE=1',
'MAVERICS_REMOTE_CONFIG_TYPE=GITLAB')
# Create the relevant registry path if the Orchestrator MSI has not yet been installed
If (-NOT (Test-Path $RegistryPath)) {
New-Item -Path $RegistryPath -Force | Out-Null
}
# Update the Environment
New-ItemProperty -Path $RegistryPath -Name $Name -Value $Value -Type MultiString -Force
The Orchestrator is compatible with Red Hat Linux and Ubuntu. Refer to the Linux install article for details on system requirements, installation procedures, updates, and uninstallation.
Create a maverics.env file using a text editor in the directory where you downloaded and unzipped the orchestrator binary.
Replace the bracketed placeholders with files and values needed for your environment.
# MAVERICS_DEBUG_MODE: Enables or disables debug mode for Maverics.
# When set to true, additional debug information will be logged.
MAVERICS_DEBUG_MODE=true
# MAVERICS_HTTP_ADDRESS: Specifies the HTTP address and port for the Maverics server to listen on.
# Example: :443 or :8443
MAVERICS_HTTP_ADDRESS=:443
# MAVERICS_TLS_SERVER_CERT_FILE: Path or secret key name to the TLS server certificate file.
# This is used to enable HTTPS for the Maverics server.
MAVERICS_TLS_SERVER_CERT_FILE=<your_cert.pem>
# MAVERICS_TLS_SERVER_KEY_FILE: Path to the TLS server private key file.
# This is used in conjunction with the server certificate to enable HTTPS.
MAVERICS_TLS_SERVER_KEY_FILE=<your_private_key.pem>
# MAVERICS_RELOAD_CONFIG: This is required when deploying config from Maverics to your storage provider.
# When set to true, the configuration file will be reloaded automatically when changes are detected.
MAVERICS_RELOAD_CONFIG=true
# MAVERICS_POLLING_INTERVAL_SECONDS: Specifies the interval, in seconds, at which the configuration file is polled for changes.
MAVERICS_POLLING_INTERVAL_SECONDS=30
# MAVERICS_BUNDLE_PUBLIC_KEY_FILE: Path to the public key file used for verifying signed bundles.
# Download this public key file from your Maverics environment.
MAVERICS_BUNDLE_PUBLIC_KEY_FILE=./public_key.pem
# MAVERICS_GITLAB_CONFIG: JSON string containing Github configuration details.
# Includes region, bucket name, access key ID, secret access key, and (optional) configuration file path.
MAVERICS_GITLAB_CONFIG='{"token":"GITHUB_TOKEN", "namespace":"ORGANIZATION_NAME", "repo":"REPO_NAME", "branch":"BRANCH_NAME","configurationFilePath": "GITLAB_CONFIGURATION_FILE_PATH"}'
Refer to the Docker install article for details on system requirements, installation procedures, updates, and uninstallation.
Create a maverics.env file using a text editor in the directory where you downloaded and unzipped the orchestrator binary.
Replace the bracketed placeholders with files and values needed for your environment.
# MAVERICS_DEBUG_MODE: Enables or disables debug mode for Maverics.
# When set to true, additional debug information will be logged.
export MAVERICS_DEBUG_MODE=true
# MAVERICS_HTTP_ADDRESS: Specifies the HTTP address and port for the Maverics server to listen on.
# Example: :443 or :8443
export MAVERICS_HTTP_ADDRESS=:443
# MAVERICS_TLS_SERVER_CERT_FILE: Path or secret key name to the TLS server certificate file.
# This is used to enable HTTPS for the Maverics server.
# Example: <key_name_in_secret_provider> or ./etc/maverics/your_cert.pem
export MAVERICS_TLS_SERVER_CERT_FILE=<your_cert.pem>
# MAVERICS_TLS_SERVER_KEY_FILE: Path to the TLS server private key file.
# This is used in conjunction with the server certificate to enable HTTPS.
export MAVERICS_TLS_SERVER_KEY_FILE=<your_private_key.pem>
# MAVERICS_RELOAD_CONFIG: This is required when deploying config from Maverics to your storage provider.
# When set to true, the configuration file will be reloaded automatically when changes are detected.
export MAVERICS_RELOAD_CONFIG=true
# MAVERICS_POLLING_INTERVAL_SECONDS: Specifies the interval, in seconds, at which the configuration file is polled for changes.
export MAVERICS_POLLING_INTERVAL_SECONDS=30
# MAVERICS_BUNDLE_PUBLIC_KEY_FILE: Path to the public key file used for verifying signed bundles.
# Download this public key file from your Maverics environment.
export MAVERICS_BUNDLE_PUBLIC_KEY_FILE=./public_key.pem
# MAVERICS_GITLAB_CONFIG: JSON string containing Github configuration details.
# Includes region, bucket name, access key ID, secret access key, and (optional) configuration file path.
export MAVERICS_GITLAB_CONFIG='{"token":"GITHUB_TOKEN", "namespace":"ORGANIZATION_NAME", "repo":"REPO_NAME", "branch":"BRANCH_NAME","configurationFilePath": "GITLAB_CONFIGURATION_FILE_PATH"}'
Create a maverics.env using a text editor and save it to a working directory.
Replace the bracketed placeholders with files and values needed for your environment.
# MAVERICS_DEBUG_MODE: Enables or disables debug mode for Maverics.
# When set to true, additional debug information will be logged.
export MAVERICS_DEBUG_MODE=true
# MAVERICS_HTTP_ADDRESS: Specifies the HTTP address and port for the Maverics server to listen on.
# Example: :443 or :8443
export MAVERICS_HTTP_ADDRESS=:443
# MAVERICS_TLS_SERVER_CERT_FILE: Path or secret key name to the TLS server certificate file.
# This is used to enable HTTPS for the Maverics server.
export MAVERICS_TLS_SERVER_CERT_FILE=<your_cert.pem>
# MAVERICS_TLS_SERVER_KEY_FILE: Path to the TLS server private key file.
# This is used in conjunction with the server certificate to enable HTTPS.
export MAVERICS_TLS_SERVER_KEY_FILE=<your_private_key.pem>
# MAVERICS_RELOAD_CONFIG: This is required when deploying config from Maverics to your storage provider.
# When set to true, the configuration file will be reloaded automatically when changes are detected.
export MAVERICS_RELOAD_CONFIG=true
# MAVERICS_POLLING_INTERVAL_SECONDS: Specifies the interval, in seconds, at which the configuration file is polled for changes.
export MAVERICS_POLLING_INTERVAL_SECONDS=30
# MAVERICS_BUNDLE_PUBLIC_KEY_FILE: Path to the public key file used for verifying signed bundles.
# Download this public key file from your Maverics environment.
export MAVERICS_BUNDLE_PUBLIC_KEY_FILE=./public_key.pem
# MAVERICS_GITLAB_CONFIG: JSON string containing Github configuration details.
# Includes region, bucket name, access key ID, secret access key, and (optional) configuration file path.
MAVERICS_GITLAB_CONFIG='{"token":"GITHUB_TOKEN", "namespace":"ORGANIZATION_NAME", "repo":"REPO_NAME", "branch":"BRANCH_NAME","configurationFilePath": "GITLAB_CONFIGURATION_FILE_PATH"}'
The Windows MSI installer prompts you for the environment details as part of the installation process:
After starting the MSI installer, click next until you get to the Select a configuration source step.
Accept the default Maverics Cloud, and then click Next.
Select Gitlab.
Edit the JSON replacing the placeholder values with the actual values from previous steps. Note:
configurationFilePath
is optional.
{
"namespace": "user123456789",
"repo": "reponame",
"branch": "main",
"token": "glpat_xxxxxxxxxxxx",
"configurationFilePath": "folder1/folder2"
}
When you are done click Next to proceed to the Bundle public key file selection.
Configuration Bundle Signing
Configuration bundles published by the Maverics platform are signed to ensure data integrity. The orchestrator cannot load a published bundle without validating the configuration file signatures against the public key for the specific configuration deployment.
In Maverics Console go to Deployments and open the deployment you created before, scroll to the Host Environment section and download the public key.
In the MSI installer, click Change… navigate to the downloaded public key and click open. Click Next
In the next screen choose the IP address, port and TLS settings for the orchestrator. Click Next and Install. If there are no install errors the orchestrator is receiving configuration from AWS.
To verify you can view Maverics logs in the Event Viewer
Start→Search for Event Viewer
Go to Windows logs → Application
Maverics Event
...level=info msg="loaded config 'maverics.tar.gz' from Gitlab"
Start orchestrator on the host
The Windows installation configures the orchestrator service to auto-start after all other services have started.
In Terminal navigate to the directory where you downloaded and unzipped the orchestrator binary.
Run the following command replacing with paths to the orchestrator binary.
sudo systemctl start maverics
To start the Orchestrator container, use the docker run command. For example:
docker run --publish 443:8443 \
--volume /opt/maverics:/etc/maverics \
--env-file /opt/maverics/maverics.env \
--name orchestrator maverics_base:0.18.10
The example command above illustrates the following options:
--publish
(or-p
) maps port 8443 on the container to port 443 on the host--volume
(or-v
) bind mounts the hosts /opt/maverics/ directory to /etc/maverics in the container--env-file
sources environment variables from a maverics.env file for the orchestrator process--name
(optional) provides an explicit name for the container instancemaverics_base:0.18.10
specifies the image name and release number of the container
Paths, port addresses, names, versions, and other settings will vary depending on your use case. Information on all options can be found in the docker run reference documentation.
In Terminal navigate to the directory where you downloaded and unzipped the orchestrator binary.
Run the following command replacing with paths to the orchestrator binary.
source ./maverics.env && ./maverics_darwin_ARM64
Troubleshooting
What do I do if orchestrator fails to start with an error message
“…level=error msg="failed to instantiate config provider: unable to read file 'public_key.pem' specified in 'MAVERICS_BUNDLE_PUBLIC_KEY_FILE': open public_key.pem: no such file or directory"
?Configuration bundles published by the Maverics platform are signed to ensure data integrity. The orchestrator cannot load the public key associated with your deployment. In the host environment configuration check that the file path is correct.
What do I do if the orchestrator fails to start with the error message
"level=error msg="failed to load configuration: unable to unbundle 'maverics.tar.gz' config from <storage provider>: bundle signature verification failed: signature verification failed: go-jose/go-jose: error in cryptographic primitive"
?In this case, the signature verification failed. The configuration bundle signature did not match with the public key used to start the orchestrator. Get the Deployment, scroll down to the Host Environment section, download the Public Key, and update the path in your host environment to the new file.