Skip to main content

Getting Started

The Witboost infrastructure command-line (also known as the Witboost Infra CLI) provides an easy-to-use interface to automate manual tasks, such as witboost upgrade, image mirroring, prerequisites checks, etc.

System Requirements​

  • Operating System: Linux(x64), Windows (x64).

Prerequisites​

  • The CLI requires several tools to be installed locally, namely helm, kubectl, curl
  • Internet access, this is required to reach the Witboost registry and repositories
  • Git credentials with access to Witboost's Helm chart, Installation Project and Witboost CLI project repository. Reach out to Witboost Team in case these are missing

Installation​

To download the Witboost CLI binary, run the following command in your shell, making sure to replace the variables with the values provided by the Witboost Team.

Installation for Linux / Windows​

curl --user <deploy_token> \
--output "witboost-infra" "<download_url>/<version>/witboost-linux-x64"

Run your first CLI command with

chmod +x witboost-infra
./witboost-infra --help

Installation for MacOS​

Installation via brew.

export HOMEBREW_GITLAB_API_TOKEN=<deploy_token>
brew tap witboost/witboost-infra https://gitlab.com/AgileFactory/Witboost.Mesh/iac/witboost.mesh.infrastructure.witboostcli.homebrew-tap.git
brew install witboost-infra
warning

If the brew tap command requires further authentication, you use whatever username and the same token as password.

Run your first CLI command with

./witboost-infra --help

Upgrading the MacOs CLI

If you already have the CLI installed, you can easily upgrade to the latest version by running:

brew upgrade witboost-infra

Next steps​

Now you are ready to initialize the CLI.

The initialization process gathers witboost registry credentials, determines the current and latest Witboost versions, and several performs several internal steps that are mandatory for other commands.

./witboost-infra init
info: Starting CLI initialization...
info: helm found ✓
info: kubectl found ✓
Registry username: git-username
Registry password: [hidden]
Current Witboost version (optional, press Enter to fetch from deployment): 2.5.0
info: Latest Helm chart version: 2.7.0
info: Fetched and Cached Product values.yaml for Current:2.5.0 and Latest:2.7.0 versions from https://gitlab.com/api/v4/projects/project-id/packages/helm/stable
info: Rules extracted successfully, configuration files updated successfully
info: Initialization complete. Current:2.5.0, Latest:2.7.0 and all versions between them updated in initial setup configuration
note

Private Helm registry username and password refer to gitlab credentials with access to the Witboost Helm and package registries. Reach out to the Witboost Team to get it.

Checkout the specific documentation of the init command.

Features​

The CLI offers the following features:

  • Witboost migration: it migrates your Witboost configuration file to make it ready for a Witboost upgrade
  • Image mirroring: it copies Witboost docker images into your private registry
  • Database checker: it checks that databases are correctly setup for Witboost
  • Convert HOCON: it converts the hocon blocks from the Witboost Helm chart values.yaml, making this file a full-yaml file

Witboost migration​

When you want to update Witboost, it might be required for you to make some changes in the configuration file (values.yaml).

To ease this process, Witboost Migration feature automates the configuration transformation functionality i.e. it automatically transforms the user’s configuration file (values.yaml) through the required migration steps from the current version to the target Witboost version.

After you have successfully initialized the CLI, you are just ready to start the migration process.

./witboost-infra transform --user-values "values.yaml" --set-target "x.y.z"

Checkout the specific documentation of the Migration.

Image mirroring​

The image mirroring feature allows you to copy all Witboost Docker images required for your deployment from the official Witboost registry to your own private container registry. This is especially useful for environments with restricted internet access or for organizations that need to maintain a local mirror of all required images for security or compliance reasons.

You can use the CLI to automatically extract the list of images for a specific Witboost version and mirror them to your target registry.

Checkout the specific documentation of the mirror-images command.

Database checker​

The database-checker feature allows you to check if your database setup fits Witboost requirements.

This command can be particularly handy to be sure your environment is ready before you start the actual installation.

Checkout the specific documentation of the database-checker command.

Convert HOCON​

Some pieces of configuration in the Witboost Helm chart are HOCON files serialized as strings. This mixed configuration format prevents the Witboost team from defining migration rules for fields within the HOCON blocks. During migrations, structural changes to the configuration may occur, and when those changes affect HOCON fields, the CLI cannot be used to apply them automatically. As a result, some changes will always need to be performed manually.

To fully enjoy automatic migrations, you just need to ensure you have your configuration file as a full YAML format file.

Checkout the specific documentation of the convert-hocon command.