domino-cli 2.6.0

Domino Platform CLI tool, providing utilities to install, configure and control your Domino Platform insfrastructure

Domino CLI

Domino CLI is a command line interface tool written in Python for Domino Platform deployment orchestration system. Its purpose is to provide a convenient way of controlling the Domino Platform Coordinator via its REST interface. It can also generate configuration files for each Domino Platform components, as well as install those.

Requirements

• Domino CLI requires Python 3.x for execution (tested on Python 3.7, 3.8, 3.10 and 3.12).
• Pip (Python package installer) is required for installation.
• It is executable both on Windows and Linux systems.

Configuration

The tool can be configured via the following environment variables:

Environment variable	Mandatory?	Description
DOMINO_BASE_URL	Yes	URL of Domino instance to be controlled, e.g. http://localhost:8080/domino
DOMINO_CLI_USERNAME	No	Optional predefined username for accessing Domino
DOMINO_CLI_PASSWORD	No	Optional predefined password for accessing Domino
DOMINO_CLI_PREAUTHORIZED_TOKEN	No	(For CI/CD mode) Passes an already generated access token - see further information in CI/CD mode)
DOMINO_CLI_DEBUG_MODE	No	Optional debug switch. Currently its only effect is echoing the parsed command
DOMINO_CLI_DISABLE_COLORS	No	Optional switch to disable terminal colors.
DOMINO_DEFAULT_AUTH_MODE	No	Changes how Domino CLI acquires the access token for Domino. Defaults to direct mode (legacy)
DOMINO_OAUTH_TOKEN_URL	In OAuth mode	OAuth 2.0 compliant authorization server address, including the token request endpoint path
DOMINO_OAUTH_CLIENT_ID	In OAuth mode	OAuth 2.0 Client ID of Domino CLI
DOMINO_OAUTH_CLIENT_SECRET	In OAuth mode	OAuth 2.0 Client Secret of Domino CLI
DOMINO_OAUTH_SCOPE	In OAuth mode	OAuth 2.0 access token scope
DOMINO_OAUTH_AUDIENCE	No	OAuth 2.0 audience of Domino

Installation

Domino CLI can be installed via pip and then it can be executed as a standalone CLI tool. In order to install, execute the following command in the terminal:

• On Windows:

  py -m pip install domino-cli
  # or
  pip install domino-cli
  

• On Linux:

  python3 -m pip install domino-cli
  

Execution

Domino CLI can be executed from any terminal with Python. First the DOMINO_BASE_URL parameter must be defined. To do this, execute the following command in the terminal:

• On Windows:

  set DOMINO_BASE_URL=<your_domino_instance_url>
  

• On Linux:

  export DOMINO_BASE_URL=<your_domino_instance_url>
  

Notes:

• With the same approach you can set the other supported environment variables as well.
• You may consider setting the environment variables permanently in the supported way of your platform.

After this step, you can start Domino CLI:

domino-cli

CI/CD mode

Domino CLI now supports execution in so-called CI/CD mode, which is a simplified execution mode, primarily to be used on CI/CD environments, usually within a deployment script. There are a few things to note here:

• To execute Domino CLI in CI/CD mode, pass the --cicd switch as the first command line parameter, then the command you wish to execute, e.g. like this:

  domino-cli --cicd deploy your_app latest
  

• Interactive terminal is not available in CI/CD mode, you may only execute a single command at a time, then Domino CLI immediately quits with exit 0 status code, or exit 1 in case of any error.
• This also means, you can't open an authorized session. Instead, you may call the auth --generate-token command and set the result (the generated access token) as the DOMINO_CLI_PREAUTHORIZED_TOKEN environment variable, e.g. as follows:

  export DOMINO_CLI_PREAUTHORIZED_TOKEN="$(domino-cli --cicd auth --generate-token)"
  # the token in DOMINO_CLI_PREAUTHORIZED_TOKEN will be used by Domino CLI to authorize any further operations
  domino-cli --cicd deploy your_app latest
  domino-cli --cicd start your_app
  

• Please note, that without the interactive terminal, any operation that depends on user input, is not available, including the configuration wizards, and manual authentication (you need to define the necessary parameters as environment variables, as described above in the Configuration section)

Usage

After successfully starting up Domino CLI you should see its prompt (Domino CLI >) along with some start-up messages. Now it's time to start playing around with the commands - the supported ones are the following:

Generic commands

help

Anytime you feel unsure how to use the tool, just type this command to have the in-application help text printed. This will also be printed in case you type an unsupported command or hit enter without typing any commands.

exit

This command doesn't really need any explanation, it makes the tool quit.

auth <--encrypt-password|--generate-token|--open-session|--set-mode <direct|oauth>>

Authentication command serves three different purposes based on the provided flag.

• --encrypt-password: Provides a utility to hash the provided password with BCrypt. The generated hash can be used in Domino's configuration as its management access account password.
• --generate-token: Authenticates with Domino in order to generate a management access token. The generated token can be used by external systems needing access to Domino.
• --open-session: Authenticates with Domino in order to generate a management access token AND stores it in the tool's security context. Opening a session is always needed to access lifecycle commands. Opening a session is only needed once every time you start the tool, but the token is stored only in memory, so you always need to open a session after starting the tool.
• --set-mode <direct|oauth>: Changes the active authentication mode. Since CLI v1.3.0, it's possible to use an external OAuth 2.0 Authorization Server to acquire access token for Domino. Please note, that both Domino and Domino CLI must be registered clients on the specified authorization server; as well as Domino must be configured to accept the token issued by the configured authorization server. The default auth mode is the legacy one, called "direct". Please make sure to specify the required OAuth parameters before changing the auth mode to "oauth". Also, this feature is only supported in Domino v1.5.0 and above.

Opening a session and generating a token require full authentication, therefore the tool asks for your configured (on Domino side) management account username and password (only in direct auth mode). You can speed up the process by predefining the credentials as environment variables (see Configuration section). Please be warned that by setting the password as an environment variable you cause a potential security vulnerability to your system. Keeping this in mind please handle this option with caution!

Lifecycle-management commands

The commands below work only in case the proper application registrations have already been made in Domino. The app parameter of the commands always refer to an application's registered identifier.

deploy <app> <latest|version> [--roll|--instance <instance-suffix>]

Instructs Domino to deploy the specified version of the given application. The application and its selected version must be already uploaded to the target server via Domino. Specify the keyword latest to let Domino decide which version to be deployed, or provide an existing version number of the application. Passing the --roll switch instructs Domino to automatically deploy and auto-start all instances of a multi-instance deployment, while --instance <instance-suffix> can be used to deploy only the selected single instance of a multi-instance deployment (auto-start is not applicable in this case). Neither of these switches are available for single-instance deployments.

start <app> [--roll|--instance <instance-suffix>]

Instructs Domino to start the currently deployed version of the application. The --roll switch can be used to start/stop/restart all available instances of a multi-instance deployment, while --instance <instance-suffix> can be used to start/stop/restart only the specified instance of a multi-instance deployment.

stop <app> [--roll|--instance <instance-suffix>]

Instructs Domino to stop the currently running instance of the application.

restart <app> [--roll|--instance <instance-suffix>]

Instructs Domino to restart the currently running instance of the application.

info <app> [--instance <instance-suffix>]

Instructs Domino to query the application's info endpoint and returns the results.

Deployment definition management commands

import <optional/path/to/deployment-definition.yml>

Imports a YAML formatted deployment definition. Without providing an absolute or relative path to your deployment definition file, defaults to .domino/deployment.yml.

OAuth descriptor management commands

oauth-import <app> [--dry-run] <optional/path/to/deployment-definition.yml>

Imports a YAML formatted OAuth descriptor. Without providing an absolute or relative path to your OAuth descriptor file, defaults to .domino/oauth.yml. The --dry-run switch causes Domino not to save, but to verify only the descriptor's contents, including the permission and application relations defined by it.

Secret management commands

Domino Coordinator, starting with v2.3.0, can act as a simple secret manager. Domino CLI provides an integration for these operations. Please note, that most of the commands do not support CI/CD mode, except for the --retrieve commands.

secret --create <key> <context>

Creates a new secret. You'll need to provide the secret key and a context (basically a group) name for the secret as arguments, then you'll be prompted to enter the secret value, without echoing the value to the terminal.
Notes:

• Context is an arbitrary value, that lets you return multiple, corresponding secrets with a single request.
• Created secrets are by default "locked", meaning they can't be returned via the API (only accessible by Domino Coordinator directly, for deployment definitions).

secret --metadata --all

Returns the metadata of all existing secrets, grouped by their context.

secret --metadata <key>

Returns the metadata of the given secret.

secret --retrieve --key <key>

Returns the value of the given secret, if retrievable. In CI/CD mode, the result is returned in <key>=<value> format, that can be put in a .env file directly.

secret --retrieve --context <context>

Returns the value of all secrets under the given context, if each of them is retrievable. In CI/CD mode, the result is returned in <key>=<value> format, that can be used in a .env file directly. E.g.:

$ domino-cli --cicd secret --retrieve --context config > .env
$ cat .env
datasource.host=jdbc:mysql://localhost:3306/test
datasource.username=root
...

secret --lock <key>

Locks (disables retrieval of) the given secret.

secret --unlock <key>

Unlocks (enables retrieval of) the given secret.

secret --delete <key>

Deletes the given secret.

Configuration wizards

Domino CLI also provides configuration wizards which help to properly create Domino configuration files. Currently one configuration wizard is supported by the tool, but the list of wizards will be extended soon.

wizard deployment

Starts wizard that helps to create a Domino application deployment configuration. Usage notes:

• Fixed choice steps are indicated by displaying the choices with a number in square brackets at the beginning of the line. Type the desired number and hit enter to select your choice.
• Some steps may expect multiple responses. Hit enter after each of your answers. To finalize the step hit enter on an empty line.
• Resulted configuration can be either displayed on console or written to file. If you chose to show the result on console, simply copy the displayed config into your existing Domino deployment config file. If you want to write the results to file, you need to define the file path when prompted. Having an already existing deployment configuration file will cause the tool to merge the newly created config with the existing file.

wizard coordinator

Starts wizard that helps to create a Domino Platform Coordinator configuration.

wizard docker-agent

Starts wizard that helps to create a Domino Platform Docker Agent configuration.

wizard bin-exec-agent

Starts wizard that helps to create a Domino Platform Binary Executable Agent configuration.

wizard installer

Starts wizard that helps to install the currently available Domino Platform components (Domino Coordinator, Domino Docker Agent, and Domino Binary Executable Agent). The first two are installed as Docker containers, while the last one is installed as a Systemd service. Please note, that because of this, Domino Binary Executable Agent installer supports Linux OS only (tested on Ubuntu).