Automation Examples

Simple examples of using automation to install the platform.

Automation Reference Installing the Akana API Platform 2018.0.x

Supported Platforms: 2018.0.x

Table of Contents

Overview
  1. Automation recipe examples: overview
Creating a basic container:
  1. Creating a basic container: overview
  2. Download and extract the installation files
  3. Put the logging file in place to enable logging
  4. Set up the properties file
  5. Run the recipe using the automation script
  6. Run the Akana Administration Console in the browser
Creating a PM/CM container:
  1. PM/CM container: overview
  2. Steps for setting up a PM/CM container
  3. Properties file for PM/CM container
  4. PM/CM container: automation script
  5. PM/CM container: results
Creating an ND container:
  1. ND container: overview
  2. Steps for setting up an ND container
  3. Properties file for ND container
  4. ND container: automation script
  5. ND container: results
Registering the ND container:
  1. Registering the ND container: overview
  2. Steps for registering the ND container
  3. Properties file for registering the ND container
  4. Registering the ND container: automation script
  5. Registering the ND container: results
Additional resource information:
  1. Providing property values at the command line
  2. Downloading and extracting the installation files
  3. Running automation recipes: troubleshooting

Overview:

Automation recipe examples: overview

General notes about the examples included in this document:

  • In these examples, the user home directory is /home/user. Substitute your own directory.
  • In this example, the value for the install directory (INSTALL_DIR property) is /home/user/akana. Substitute your own install directory.
  • You can encrypt passwords. This example does not use encryption.

back to top

Creating a basic container:

Creating a basic container: overview

In this example we will create a basic container using automation, at the Linux command line. This example uses a core automation recipe, bootstrap.json. This recipe is also part of many other recipes that perform more complex actions, so it's a good exercise to run it on its own.

The scenario includes:

  1. Downloading and unzipping the installation files
  2. Setting up specific files and properties so that the script will work correctly. This includes:
    • Putting the logging file in place to enable logging.
    • Writing the properties file.
  3. Using the automation script to run a basic recipe to create the container.
  4. Opening the Akana Administration Console user interface for the container in the browser.

back to top

Download and extract the installation files

As with any installation, you'll need to download the correct files and unzip them in the correct sequence in your installation directory.

For detailed instructions on downloading and extracting the files, refer to the sections in the installation documentation:

For abbreviated instructions for the specific files used in these examples, see Downloading and extracting the installation files.

The illustration below shows copying the files from another location so that the four files are in the akana directory.

Setting up the files

back to top

Put the logging file in place to enable logging

When running a recipe, logging is very helpful to track down problems or monitor the progress of a recipe. The recipe scripts use SLF4J logging, and since no default implementation is shipped with the scripts, it is sometimes necessary to provide one. To deploy a logger implementation, you'd need to copy the file to a location accessible to the automation script.

So, the next step is to copy the slf4j-simple-1.7.19.jar logger file, which is part of the installation, to the $INSTALL_DIR/lib/script folder.

For this example, from the/home/user/akana folder, run the following:

cp lib/ext/slf4j-simple-1.7.19.jar lib/script/

back to top

Set up the properties file

For this example, we're going to define a few key properties via a properties file, which the automation script will reference.

The filename and location don't matter as long as you reference the file correctly in the automation script. In this example, we're creating a file named bootstrap.properties in the /bin directory.

First, in the /home/user/akana/bin folder, create the properties file. For example:

vi bootstrap.properties

Add the below contents to the file:

INSTALL_DIR=/home/user/akana
CONTAINER_NAME=pm01
DEFAULT_PORT=9900

Save the file.

Note: For information about how you could provide these properties at the command line, see Providing property values at the command line below.

Determining values for properties used in the recipe

The recipes needs certain values, such as the name of your installation directory and the name of the container you're creating.

In a manual installation, you provide these values in the installation wizard user interface. When using a recipe you can provide them:

  1. In a properties file. See the example above.
  2. System properties. Usually passed in at the command line using -D. See Providing property values at the command line.
  3. As environment variables.

In this example of creating a basic container, the values are defined in a properties file.

There are two scenarios for property values:

  • Variables that have no default: if the value is not provided the recipe will fail.

    Examples: INSTALL_DIR, CONTAINER_NAME.

  • Variables that have default values defined in the recipe. If you want to use a different value you'll have to provide it. If not, the default value is used.

    Example: In the bootstrap.json recipe, the default port is defined as 9900 (line 16). In this example of creating a basic container, we explicitly specify port 9900 in the properties file; however, since port 9900 is the default, it isn't really necessary to specify a port.

back to top

Run the recipe using the automation script

In this example, the properties file is bootstrap.properties.

Therefore, the script command to run from the /akana/bin folder is:

./jython.sh -Dorg.slf4j.simpleLogger.logFile=System.out -m akana.container --recipe ../recipes/bootstrap.json --props bootstrap.properties

The result of running the automation script is shown below.

Running the script

You can see that the container was successfully created and started, as indicated above.

back to top

Run the Akana Administration Console in the browser

You can now access the Akana Administration Console via the browser: {hostname}:{port}/admin/login.html.

Log in, using the default username and password (administrator/password) unless you specified a different username and password.

To verify the container name, after login, go to the System tab. The container name is displayed in the panel header, as shown below. In this example the container name is pm01 (see Set up the properties file above).

Running the Akana Administration Console for the container

You've now created a basic container using automation. This is the equivalent of completing Step 3 in the manual installation instructions (see Step 3: Run Configurator to create the first container).

back to top

Creating a PM/CM container:

PM/CM container: overview

By following the steps in Creating a basic container above, you'll get some practical experience of running an automation recipe. However, there are no features installed in the basic container.

Now it's time to take it a step further, creating a container with multiple features installed and multiple properties set.

There are these differences in the procedure:

  • You're running a different automation recipe, pm-cm-all.json.
  • Because it's a more complex recipe, you'll need to provide a lot more properties.

You'll also need to have your database set up. Depending on the database type and version you're using, you might also need to put a driver in place and/or modify some database settings first. Refer to these sections of the Installing the Akana API Platform 2018.0.x doc:

back to top

Steps for setting up a PM/CM container

The sequence of steps is the same for running any recipe, as described in detail in Creating a basic container above:

  1. Download and extract the installation files (once per installation).
  2. Put the logging file in place to enable logging (once per installation).
  3. Set up the properties file (per recipe). For this example, define the properties listed in Properties file for PM/CM container below.
  4. Run the recipe using the automation script (per recipe). For this example, use the script shown in PM/CM container: automation script below.

back to top

Properties file for PM/CM container

In your installation folder, look in the /recipes subfolder at the pm-cm-all.json recipe.

For this example, because the recipe is doing a lot more, you must provide additional properties. To see which properties you need to define for a recipe, just look through the recipe, and any other recipes that it might be referencing.

Because we're going to run several recipes, these examples use the recipe name for the properties file. For the PM container, the recipe is pm-cm-all.json, so the properties file is pm-cm-all.properties. The filename doesn't matter as long as it's correct in the script.

In the /home/user/akana/bin folder, create the properties file. For example:

vi pm-cm-all.properties

In the file, provide values for all the properties referenced by the recipe. An example is shown below.

INSTALL_DIR=/home/user/akana
PRODUCT_HOME=/home/user/akana
CONTAINER_NAME=pmcm01
TENANT_ID=atmosphere
TENANT_NAME=atmosphere
TENANT_HOST=ubu1664qa-17.akana.roguewave.com
TENANT_CONSOLE_HOST=ubu1664qa-17.akana.roguewave.com
TENANT_VHOSTS=ubu1664qa-17.akana.roguewave.com
TENANT_EMAIL=administrator@atmosphere
TENANT_PASSWORD=password
TENANT_THEME=hermosa
TENANT_THEME_IMPL=default
DB_NAME=UBU1664QA17
DB_TYPE=oracle
DB_INSTANCE=db1
DB_PORT=1521
DB_ADMIN_USERNAME=SYSTEM
DB_ADMIN_PASSWORD=rd57chv
DB_USERNAME=UBU1664QA17
DB_PASSWORD=password
DB_SERVER=akanaeng-oracle12cr2-1.aws.akana.roguewave.com
DB_DRIVER_LOCATION=file:///home/user/ojdbc8.jar
DB_SCHEMA_TIMEOUT=4000000000

Note: The example above references the location for the ojdbc8.jar file, needed for an Oracle database. If you're using Oracle, you'd have to have the driver in place and update the path appropriately. If you're using another type of database, you may or may not need to provide a driver. Refer to the Database drivers section of the installation documentation. There might be other steps you need to have in place for your database. Check the information in the links provided in PM/CM container: overview above.

back to top

PM/CM container: automation script

In this example, the recipe is pm-cm-all.json and the properties file is pm-cm-all.properties.

Therefore, the script command to run from the /akana/bin folder is:

./jython.sh -Dorg.slf4j.simpleLogger.logFile=System.out -m akana.container --recipe ../recipes/pm-cm-all.json --props pm-cm-all.properties

When the recipe has successfully completed, you'll see a message such as the below:

pm-cm-all.json, successful completion

back to top

PM/CM container: results

You can now access the Akana Administration Console for the container: {hostname}:{port}/admin/login.html, as shown below.

You can see from the Installed Features page that Community Manager is installed and all pending tasks are complete.

Running the Akana Administration Console for the pm-cm-all container

In this example, you can also access the Policy Manager and Community Manager via the browser, as shown below.

Policy Manager: {hostname}:{port} (default credentials, used in this example, are administrator/password).

Running Community Manager for the pm-cm-all container

Community Manager: {hostname}:{port}/atmosphere/#/home/login (default credentials, used in this example, are administrator@atmosphere/password).

Running the developer portal

back to top

Creating an ND container:

ND container: overview

Next, we're going to create the Network Director container. We can then register the ND container so that it can communicate with the PM/CM container.

  • Recipe: nd-cm-all.json
  • Properties file in this example: nd-cm-all.properties

back to top

Steps for setting up an ND container

The sequence of steps is the same for running any recipe, as described in detail in Creating a basic container above:

  1. Download and extract the installation files (once per installation).
  2. Put the logging file in place to enable logging (once per installation).
  3. Set up the properties file (per recipe). For this example, define the properties listed in Properties file for ND container below.
  4. Run the recipe using the automation script (per recipe). For this example, use the script shown in ND container: automation script below.

back to top

Properties file for ND container

Properties file (nd-cm-all.properties):

INSTALL_DIR=/home/user/akana
DEFAULT_PORT=9905
CONTAINER_NAME=nd01
PM_PORT=9900
PM_HOST=ubu1664qa-17.akana.roguewave.com

back to top

ND container: automation script

In this example, the recipe is nd-cm-all.json and the properties file is nd-cm-all.properties.

Therefore, the script command to run from the /akana/bin folder is:

./jython.sh -Dorg.slf4j.simpleLogger.logFile=System.out -m akana.container --recipe ../recipes/nd-cm-all.json --props nd-cm-all.properties

When the recipe has successfully completed, you'll see a message such as the below:

pm-cm-all.json, successful completion

back to top

ND container: results

You can now access the Akana Administration Console for the ND container. In this example: {hostname}:9905/admin/login.html.

You can see from the Installed Features page that Network Director is installed and all pending tasks are complete.

Running the Akana Administration Console for the ND container

The next step is to register the ND container with PM.

back to top

Registering the ND container:

Registering the ND container: overview

Next, we're going to run another automation recipe to register the ND container with the PM/CM container.

  • Recipe: register-container.json
  • Properties file in this example: register-container.properties

back to top

Steps for registering the ND container

The sequence of steps is the same for running any recipe, as described in detail in Creating a basic container above:

  1. Download and extract the installation files (once per installation).
  2. Put the logging file in place to enable logging (once per installation).
  3. Set up the properties file (per recipe). For this example, define the properties listed in Properties file for registering the ND container below.
  4. Run the recipe using the automation script (per recipe). For this example, use the script shown in Registering the ND container: automation script below.

back to top

Properties file for registering the ND container

Properties file (register-container.properties):

TENANT_ID=atmosphere
ORG_KEY=uddi:soa.com:registryorganization
PM_PORT=9900
CONTAINER_NAME=nd01
INSTALL_DIR=/home/user/akana

In the above, TENANT_ID and ORG_KEY are both provided. You must provide one of these two, but to provide both is optional. The ORG_KEY value can be specific to the tenant.

back to top

Registering the ND container: automation script

./jython.sh -Dorg.slf4j.simpleLogger.logFile=System.out -m akana.container --recipe ../recipes/register-container.json --props register-container.properties

back to top

Registering the ND container: results

When the recipe has successfully completed, you'll see a message such as the below.

Register Container recipe successful

Now, log in to Policy Manager on the PM/CM container (in this example, {hostname}:9900).

You'll see that the ND container is now registered, as shown below.

ND container is registered

back to top

Additional resource information:

Providing property values at the command line

For consistency, it's a good idea to provide properties in a properties file (see Set up the properties file).

However, you could also provide properties at the command line when running the script.

Let's say you want to provide two basic properties, INSTALL_DIR and CONTAINER_NAME, which we used to create the basic container in the first example above. Your recipe.properties file would look like this:

INSTALL_DIR=/home/user/akana
CONTAINER_NAME=pm01

Your command line instruction for running the script would look something like this:

./jython.sh -Dorg.slf4j.simpleLogger.logFile=System.out -m akana.container 
--recipe ../recipes/bootstrap.json --props bootstrap.properties

However, you could instead provide the above two properties at the command line. In this example, from the /home/user/akana/bin folder, you'd provide the following at the command line:

./jython.sh -Dorg.slf4j.simpleLogger.logFile=System.out -DINSTALL_DIR=.. -m akana.container --name pm01 --home .. --recipe ../recipes/bootstrap.json

In the above:

  • ./jython.sh

    Calls the jython script

  • -Dorg.slf4j.simpleLogger.logFile=System.out

    Sets the logging

  • -DINSTALL_DIR=..

    Sets the INSTALL_DIR property value to one folder up (the /home/user/akana folder in this example)

  • -m akana.container

    Specifies the module being run

  • --name pm01

    Specifies that the script should create a container named pm01

  • --home ..

    Sets the home directory

  • --recipe ../recipes/bootstrap.json

    Specifies the recipe to run

back to top

Downloading and extracting the installation files

Instructions for downloading and extracting the files are in the installation documentation: for example, for 2018.0.x, see Installing the Akana API Platform 2018.0.x (Step 1 and Step 2). Abbreviated instructions are below.

The download files

The examples in this document create containers for version 2018.0.7. The files for this example are listed below.

This file... Installs...
akana-platform-linux-jre-2018.0.0.19.zip The base files for the major version of the Akana Platform, the underlying infrastructure to all Akana products.
akana-platform-update-cumulative-2018.0.6.zip The latest update to the Akana Platform, including all previous updates since the release of the major version above.
akana-api-platform-2018.0.0.396.zip The base files for the major version of the Akana API Platform, the API management product, which runs on the underlying Akana Platform.
akana-api-platform-update-cumulative-2018.0.7.zip The latest update to the Akana API Platform, including all previous updates since the release of the major version above.

The illustration below shows copying the files from another location so that the four files are in the akana directory.

Extracting the files

In the /home/user/akana folder, unzip the files in this sequence, always choosing to overwrite existing files if they already exist:

  • unzip -o akana-platform-linux-jre-2018.0.0.19.zip
  • unzip -o akana-platform-update-cumulative-2018.0.6.zip
  • unzip -o akana-api-platform-2018.0.0.396.zip
  • unzip -o akana-api-platform-update-cumulative-2018.0.7.zip

back to top

Running automation recipes: troubleshooting

This section provides information about errors you might run into when running automation, and possible reasons/resolution.

Problem: TypeError

You might encounter a TypeError such as the example shown below if you create the properties file on Windows. When running automation on Linux, it's best to create the properties file on Linux.

TypeError: cannot concatenate 'unicode' and 'NoneType' objects

back to top