Installing with the Cloud Pak for Applications command-line interface (CLI)

You can use the Cloud Pak installer CLI install command to install the Accelerators for Teams, Transformation Advisor, and Application Navigator software.

Before you begin

Ensure that you have a connection to a Red Hat® OpenShift® Container Platform (OCP) cluster, and have cluster-admin permissions. You also need Docker installed to run the Cloud Pak installer. See Preparing for installation.

Upgrading from Cloud Pak 3.x to Cloud Pak 4.x:

Upgrading from a previous Cloud Pak 4.x version:

Installation steps

Step 1: Get a key to the entitled registry.

After you order IBM Cloud Pak for Applications, an entitlement key for the Cloud Pak software is associated with your MyIBM account. Use the key to access the Entitled Container Fulfillment Registry.

Get the entitlement key that is assigned to your ID.

  1. Log in to MyIBM Container Software Library External link icon with the IBMid and password that are associated with the entitled software.
  2. In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard.

Step 2: Extract the installation configuration from the installer image on the entitled registry.

At a command line, run the following commands. The command examples apply for Linux® and macOS operating systems. For Windows® operating systems, see Running the Cloud Pak CLI on Windows.

  1. Set the entitled registry information. Run export commands that set ENTITLED_REGISTRY to cp.icr.io, set ENTITLED_REGISTRY_USER to cp, and set ENTITLED_REGISTRY_KEY to the entitlement key that you got from the previous step.

    export ENTITLED_REGISTRY=cp.icr.io
    export ENTITLED_REGISTRY_USER=cp
    export ENTITLED_REGISTRY_KEY=<apikey>
    
  2. Log in to the entitled registry with the following docker login command:

    docker login "$ENTITLED_REGISTRY" -u "$ENTITLED_REGISTRY_USER" -p "$ENTITLED_REGISTRY_KEY"
    
  3. Run the following command to pull down the installer container image and view the license.

    docker run -e LICENSE=view \
               "$ENTITLED_REGISTRY/cp/icpa/icpa-installer:4.1.1"
    

    You must accept the license before running any installer command. To accept the license pass -e LICENSE=accept option with each command.

  4. Extract the installation configuration. Run the following commands to create the data directory and extract the configuration files to it.

    mkdir data
    docker run -v $PWD/data:/data:z -u 0 \
               -e LICENSE=accept \
               "$ENTITLED_REGISTRY/cp/icpa/icpa-installer:4.1.1" cp -r "data/*" /data
    

Step 3: Review the installation configuration files.

Review settings in the config.yaml, kabanero.yaml, and transadv.yaml configuration files, which are in the data directory. The Cloud Pak installer calculates default values when you run a command. The default values likely are suitable for your environment. But, if you encounter problems after you run a command in Step 4, you might need to change the configuration values for your environment and then run the command again.

For example, you might need to specify your OpenShift cluster router subdomain in the subdomain setting of the config.yaml configuration file if the installer cannot find your subdomain when a check or install command is run. To see what values the installer used for a command, you might need to run the command first and then view the log for the command in the logs directory.

Note: Default installation does not install Mobile Foundation or Common Services. To install Mobile Foundation, review settings in mobilefoundation.yaml and run mf-install. To install Common Services, review settings in commonservices.yaml and run cs-install.

For information about configuration file settings, see Installer configuration files.

Step 4: Run the installer.

  1. The Cloud Pak for Applications installer requires a connection to your OCP cluster. There are two ways to provide the login information to the installer:

    • If you have the oc client installed, use the client to log in to your cluster as usual.

      oc login https://<your_api_cluster_url> -u <username> -p <password>
      

      Note: To generate a login command with the correct URL and port number, log in to the OpenShift console, click your username, then click Copy Login Command. Paste the copied oc login command into your terminal.

    • If you do not have the oc client installed, you can use environment variables to pass in login information.

      • If you have a username and password, pass
        • -e OPENSHIFT_URL=https://<your_api_cluster_url> -e OPENSHIFT_USERNAME=<username> -e OPENSHIFT_PASSWORD=<password>
      • If you have a token, pass
        • -e OPENSHIFT_URL=https://<your_api_cluster_url> -e OPENSHIFT_TOKEN=<token>
  2. (Optional) Run the Cloud Pak for Applications installer check command to check prerequisites.

     docker run -v ~/.kube:/root/.kube:z -u 0 -t \
               -v $PWD/data:/installer/data:z \
               -e LICENSE=accept \
               -e ENTITLED_REGISTRY -e ENTITLED_REGISTRY_USER -e ENTITLED_REGISTRY_KEY \
               "$ENTITLED_REGISTRY/cp/icpa/icpa-installer:4.1.1" check
    

    To see details on the check results, view the check.log.<timestamp> file in the logs directory.

  3. Run the installer install command to install Accelerators for Teams, Transformation Advisor, and Application Navigator.

    docker run -v ~/.kube:/root/.kube:z -u 0 -t \
               -v $PWD/data:/installer/data:z \
               -e LICENSE=accept \
               -e ENTITLED_REGISTRY -e ENTITLED_REGISTRY_USER -e ENTITLED_REGISTRY_KEY \
               "$ENTITLED_REGISTRY/cp/icpa/icpa-installer:4.1.1" install
    

    The installer displays progress messages and adds the messages to the install.log.<timestamp> file in the logs directory. If you encounter problems during installation, see Troubleshooting.

    If the installation is successful, the last progress messages have URLs to the Cloud Pak console, the pipelines dashboard, Transformation Advisor, and Application Navigator.

After installation

Verify that you can access the Cloud Pak Console:

  1. Click the displayed Cloud Pak Console URL.

  2. On the Cloud Pak Console, click IBM Cloud Pak for Applications Instance in the Cloud Pak Console Instance. The Accelerators for Teams instance page provides information about your application stacks and, under Tools, has links to the pipelines dashboard and other tools such as Transformation Advisor and Application Navigator.

    Tip: You can also access the Cloud Pak Console from an OpenShift Web Console. Go to the OpenShift Container Platform application console and click OpenShift Web Console link to the Cloud Pak Console Cloud Pak Console from the navigation menu.

Before you start developing applications, set up your environment:

  1. To customize the Accelerators for Teams application stacks and share them with your team, see Setting up application stacks. Code changes are shared only with members of your GitHub Enterprise organization, and are not public. By default, your Kabanero instance is configured with a public set of Kabanero stacks. If needed, you can configure Appsody to get the Accelerators for Teams stack images from the internal Docker registry of your cluster.

  2. From the Cloud Pak Console, click Set up dev tools and configure development tools.

Note: There is a compatibility issue with some versions of Appsody CLI. For more information, see Troubleshooting.

For information about how to use Accelerators for Teams, click IBM Cloud Pak for Applications Docs in the Cloud Pak Console Docs and IBM Cloud Pak for Applications Guides in the Cloud Pak Console Guides on the Cloud Pak Console or see the Kabanero resources External link icon.

For information about how to use Transformation Advisor, see the Transformation Advisor documentation, videos, and web page.

For information about how to use Application Navigator, see Managing the environment or the IBM Application Navigator web page.

The following figure displays the IBM Cloud Pak for Applications Cloud Pak Console.
IBM Cloud Pak for Applications Cloud Pak Console