Deploying and upgrading using the command line tools

You can deploy, upgrade, or clean the i2 Explore for iBase application using the command line tools provided in the analyze-deployment-tooling directory.

Configuring the deployment

If this is a first-time deployment and the variables.conf file does not yet exist, you can generate the configuration from templates by running one of the following commands from the analyze-deployment-tooling directory:

  • setup -h — Generates the configuration files and displays the help message.

  • AdminConsole.exe — Opens the Administration Console, which also generates the configuration files on first run.

Before deploying for the first time, review the configuration properties in the variables.conf file and update them to match your environment:

<installation_location>/analyze-deployment-tooling/configs/explore-for-ibase/utils/variables.conf

At a minimum, you must configure the iBase database connection properties, including the database name, security database name, database server host, and port. You should also verify that the SQL Server install location and database file location are correct.

For a full reference of all available properties, see Configuration Properties.

Note: If you are upgrading an existing deployment, your variables.conf file is already populated with your existing settings.

Configuring server certificates

You can provide your own TLS certificates for the i2 Explore service, or allow the deployment to generate them automatically.

To generate certificates from the command line, run:

setup -t generateSecrets

To supply your own certificates, place the certificate files in the required locations before deploying. For detailed information about the required files and their locations, see Configuring TLS Connection to iBase.

If you do not generate or supply certificates before deploying, the deploy task generates them automatically. Generated certificates are not recommended for production environments.

Deploying

The application is deployed for the first time using the setup script in the analyze-deployment-tooling directory. Open a Command Prompt, navigate to the analyze-deployment-tooling directory, and run:

setup -t deploy -u <username> -p <password>

Replace <username> and <password> with database administrator credentials that have sysadmin permissions. These credentials are used to create the Information Store database, logins, and users.

The deploy task performs the following actions:

  • Downloads the required prerequisites if they are not already present in the pre-reqs directory.

  • Generates the i2 Explore configuration from your iBase database.

  • Creates the Information Store database in the iBase SQL Server instance.

  • Generates certificates and secrets required by the deployment.

  • Deploys configuration files to the Liberty application server, Solr, and ZooKeeper.

  • Starts the Liberty application server, Solr, and ZooKeeper services.

After the first deployment, a dedicated database user is created and subsequent deployments do not require database administrator credentials. For more information, see Database Permissions Summary. You can run subsequent deployments without the -u and -p arguments:

setup -t deploy

Note: The default task is deploy, which runs if no task is specified.

Upgrading

To upgrade an existing deployment to a newer version of i2 Explore for iBase, run:

setup -t upgrade -u <username> -p <password>

Replace <username> and <password> with database administrator credentials that have sysadmin permissions. These credentials are always required for an upgrade.

Note: Use this action once after you unpack a new release over the top of an existing installation.

The upgrade task stops all running services, removes the current deployment, re-downloads third-party prerequisites, updates the i2 Explore services to the latest versions, and redeploys the application.

The upgrade task preserves your existing configuration, secrets, and flagged records. These are backed up before the clean step and restored automatically after the redeployment.

Cleaning

To remove an existing deployment, run:

setup -t clean -u <username> -p <password>

Replace <username> and <password> with database administrator credentials that have sysadmin permissions. These credentials are always required for a clean.

The clean task stops all running services, removes installed binaries, Solr and ZooKeeper data, and drops the Information Store database and associated logins. iBase data is not modified by this operation. Flagged records are backed up and restored on the next deployment.

During a standard clean, the operation stops if it cannot connect to the database, back up flagged records, or drop the Information Store database. This preserves the database scripts and flagged record data so that you can resolve the issue and retry.

To force the clean operation to continue with file cleanup even if the database steps fail, use the -f flag:

setup -t clean -f -u <username> -p <password>

When the -f flag is specified, the database scripts and any flagged record backups are deleted regardless of whether the database was successfully dropped. If the database drop failed, you might not be able to drop the database and users afterwards because the required scripts are no longer available. If the flagged records backup failed, those record flags are permanently lost.

Important: Use force clean only if you understand the consequences, or if you are advised to do so by i2 Group support.

Results

When the deployment or upgrade is complete, the console output contains an entry in the following form, indicating the URL at which i2 Explore for iBase is accessible:

Explore for iBase available at URL: <your_url>

Credential Manager

By default, i2 Explore for iBase stores passwords and generated secrets in Windows Credential Manager rather than as files on disk.

The secret store type is controlled by the SECRET_STORE_TYPE property in the variables.conf file. The following values are supported:

  • cm (default) — Stores secrets in Windows Credential Manager.

  • file — Stores secrets as files on disk, in the secrets directory within the configuration folder.

Note: Certificates are always stored as files, regardless of the SECRET_STORE_TYPE setting.

When you change the SECRET_STORE_TYPE value, run the following command to migrate existing secrets to the new store:

setup -t migrateSecrets

The migration reads secrets from the previous store and writes them to the new one. After a successful migration, the secrets are removed from the previous store.

You can set individual credentials from the command line by using the setCredential task. The following credential keys are supported: ADMIN_CONSOLE_PASSWORD, ENTRA_SECRET, and LDAP_PASSWORD. For example, to set the i2 Explore Administration Console password:

setup -t setCredential -p <password> ADMIN_CONSOLE_PASSWORD

Deployment tasks

The following options and tasks are available to use with the setup script.

usage: setup [-t TASK] [-h] [-v] [-f] [-u USERNАME] [-p PASSWORD] [value]

Argument name

Argument description

-t, --task TASK

Specifies the task to perform. Defaults to deploy.

-h, --help

Displays the help message and exits.

-v, --verbose

Enables verbose logging.

-f, --force

Forces the operation, ignoring warnings.

-u, --username

Specifies the database administrator username.

-p, --password

Specifies a password for the task.

value

Optional value for the specific tasks.

Task name

Description

deploy

Deploys the i2 Explore for iBase environment (default).

upgrade

Upgrades an existing i2 Explore for iBase deployment.

clean

Stops all services, removes installed binaries, Solr and ZooKeeper data, and drops the ISTORE database.

start

Starts all i2 Explore services.

stop

Stops all i2 Explore services.

startLiberty

Starts Liberty.

stopLiberty

Stops Liberty.

startZkHosts

Starts ZooKeeper hosts.

stopZkHosts

Stops ZooKeeper hosts.

startSolrNodes

Starts the Solr nodes.

stopSolrNodes

Stops the Solr nodes.

startSolrAndZk

Starts the Solr nodes and ZooKeeper hosts.

stopSolrAndZk

Stops the Solr nodes and ZooKeeper hosts.

checkLdap

Checks the connection to LDAP using the configured properties.

checkDb

Checks the connection to the iBase database using the configured properties.

createDatabaseScripts

Generates the database scripts required for manual creation of the ISTORE database.

generateSecrets

Generates certificates and required passwords.

migrateSecrets

Migrates secrets from one secret store to another based on the SECRET_STORE_TYPE configuration.

setCredential

Sets a specific credential. Requires -p for the value, and a positional value argument for the credential key. For more information, see Credential Manager.

setAdminConsolePassword

Sets the i2 Explore Administration Console password. Requires -p for the value.

installPreReqs

Installs all deployment prerequisites.

cleanPreReqs

Removes all prerequisite binaries except the i2 Analyze toolkit.

Exploring the deployment

For more information about the directory structure created after deployment, see Exploring the i2 Explore for iBase Deployment.

Making changes to the deployment

You can make changes to the configuration of an existing deployment. For detailed information about all available configuration properties, see Configuration Properties.

iBase database changes

iBase Designer requires exclusive access to the iBase database. Because of this, it might be necessary to stop the i2 Explore services before launching iBase Designer. You can do this by running:

setup -t stop

When changes are made to the schema of the iBase database, these need to be reflected in the i2 Explore application. Certain changes, like removing item types from the iBase database, can cause errors for users of i2 Explore, but these are rectified after the i2 Explore application is updated.

To update i2 Explore, run the deploy task:

setup -t deploy

Changing ports on an existing deployment

If you need to change any of the Liberty, Solr, or ZooKeeper ports on an existing deployment, follow these steps:

  1. Run the clean task:

    setup -t clean

  2. Update the variables.conf file with the new port values:

    <installation_location>/analyze-deployment-tooling/configs/explore-for-ibase/utils/variables.conf

  3. Run the deploy task:

    setup -t deploy