Installing the Akana API Platform 8.4x

Learn how to download, install, and configure the Akana API Platform 8.4x, including the Akana Platform and all features previously included in Policy Manager and Community Manager.

Note: This document covers instructions for the combined features available in version 8.4x. For versions prior to 8.4x, refer to the applicable version of the documentation: Installing Akana API Platform 8.2x or Installing Policy Manager 8.x.

Using Admin Console Installing Tools Installing Plug-ins Configuration Actions

Supported Platforms: 8.4x

Table of Contents

Installation Procedure:
  1. Overview
  2. Step 1: Gather ZIP files and download to the install folder
  3. Step 2: Unzip files into the installation folder in the correct sequence
  4. Step 3: Run Configurator to create the first container
  5. Step 4: Install Policy Manager/Community Manager features on the container
  6. Step 5: (as needed) Install plug-ins on the container
  7. Step 6: Complete pending tasks to configure container features
  8. Step 7: Create and configure additional containers
  9. Step 8: Add Network Director to Policy Manager
  10. Step 9: Create Community Manager tenant using the Jython script
  11. Step 10: Run the developer portal
Installation Tasks/Reference:
  1. Supported databases
  2. Database notes
  3. Database drivers
  4. Installation folder structure
  5. Clear Configurator cache
  6. Starting a container
  7. Stopping a container
  8. Creating a container via the GUI
  9. Creating a container using silent install (Linux)
  10. Unregistering and re-registering the Windows service
  11. Linux install: exporting the JAVA_HOME variable
  12. Installation wizard: Manage PKI Keys
  13. Installation wizard: Add Database
  14. Installation wizard: Manage Schemas
  15. Installation wizard: Define Policy Manager Administrator Credentials
  16. Installation wizard: Provisioning
  17. Installation wizard: Configure Container Instance
  18. Installation wizard, ND container: Configure WS-Metadata Exchange Options
  19. Installation Options: Full List
  20. Policy Manager Add Container wizard
  21. Sample installation scenarios
  22. Feature notes: Scheduled jobs
  23. Feature Notes: Akana Embedded Elasticsearch Node feature

Installation Procedure:

Overview

This document provides instructions for installing the Akana API Platform version 8.4.

It covers a very simple scenario of setting up two containers:

  1. One container for Policy Manager and Community Manager.
  2. One container for Network Director.

This document covers the following broad activities associated with the installation process:

  • Preparation (Steps 1 and 2)
  • Creating the first container, installing features and plug-ins, and configuring the container (Step 3 to Step 6)
  • Creating and configuring additional containers (Step 7, which is Step 3 to Step 6 repeated for each container as needed)
  • Adding Network Director to Policy Manager (Step 8)
  • Creating and running the API Platform tenant (Step 9 and Step 10)
Note: Installation task sequence

There are different approaches to the install tasks:

  • You can create one container, configure it, and then create the next container, or you can create all containers and then configure the containers. It really doesn't matter. This documentation creates and configures the first container and then the next.
  • You can install features and then configure them before installing plug-ins, or you can install features and plug-ins and then configure them. Again, it really doesn't matter. Just make sure all pending installation tasks are complete, on all containers, before creating the developer portal tenant. This documentation installs features and plug-ins and then configures.

Step 1: Gather ZIP files and download to the install folder

The first step is to gather the installation ZIP files from the Akana Library (https://library.akana.com/display/MAIN/Akana+Library. On the left, click Downloads.

Note: If you don't see the 8.4 files, contact Technical Support for access.

Create a folder for your installation; for example, aap84. Gather all applicable ZIP files in the installation folder.

You'll need at minimum the following files:

  1. Akana Platform ZIP file: choose the appropriate file for the operating system you're using:
    • Windows (includes JRE: akana-platform-win-jre-8.4.xxx.zip
    • Linux ( includes JRE): akana-platform-linux-jre-8.4.xxx.zip
    • Windows, Linux, or Solaris (does not include JRE; provide your own JRE, version 1.8): akana-platform-8.4.xxx.zip
  2. Akana API Platform ZIP file (contains all necessary files for Akana API Platform installation, including Policy Manager and Community Manager installation): akana-api-platform-8.4.xxx.zip.

Depending on the scenario, you might also need the following files:

  • Incremental updates to the Akana Platform: download any that are available, up to the latest version.
  • Incremental updates to the Akana API Platform: download any that are available, up to the latest version.
  • Plug-ins: The ZIP file, and any updates, for any plug-ins you want to use in your installation.

back to top

Step 2: Unzip files into the installation folder in the correct sequence

When you've downloaded all applicable ZIP files, extract the files into your aap84 folder in the sequence listed below.

Note: The sequence is very important. Be sure to install products, and updates, in the sequence given below.

  1. Akana Platform main file.
  2. Akana Platform updates if applicable: One or more updates if there are any, beginning with the earliest update, up to the latest. If you're prompted whether to overwrite a file, select Yes.
  3. Akana API Platform main file.
  4. Akana API Platform updates if applicable: One or more updates if there are any, beginning with the earliest update, up to the latest. If you're prompted whether to overwrite a file, select Yes.
  5. Plug-ins for your installation, if any.
  6. Updates to the plug-ins, if applicable: earliest to latest, overwriting if needed, as above.

back to top

Step 3: Run Configurator to create the first container

The Configurator steps you through creating a container, specifying basic values about the container.

Once you've created the container, you can go into the Akana Administration Console for the container and install features into it.

You can create a container:

Follow the applicable linked procedure to create the first container, and then continue to the next step.

back to top

Step 4: Install Policy Manager/Community Manager features on the container

Follow the short procedure below to install the Policy Manager/Community Manager features on the first container for this two-container scenario (one PM/CM, one ND). For additional information on features for different scenarios, see Sample installation scenarios.

For a summary of features and add-ins for this scenario, see One container with both Policy Manager and Community Manager installed.

To install Policy Manager/Community Manager features on the container
  1. In the Akana Administration Console, go to the Available Features list.
  2. Choose the options applicable to your install, and then click Install Feature; then, at the Resolution Summary, click Install Feature again. In this example, you'd choose the features below for the PM/CM container:
    • Akana Community Manager
    • Akana Community Manager APIs
    • Akana Community Manager OAuth Provider
    • Akana Community Manager Scheduled Jobs
    • Akana Embedded Elasticsearch Node
    • Akana OAuth Provider
    • Akana Policy Manager Console (for more information on this feature see Using the Policy Manager Console Feature)
    • Akana Policy Manager Services (Includes Akana Management Services, Akana Security Services, and Akana Scheduled Jobs. For more information on this feature see Using the Policy Manager Services Feature.)
  3. At the Installation Complete summary, click Configure (if you are installing plug-ins, click Close and install plug-ins first).

For additional information, if needed, refer to the following topics:

The next step is to install any plug-ins that are needed for the container.

back to top

Step 5: (as needed) Install plug-ins on the container

Depending on your installation scenario, you might need to install one or more plug-ins on your container to support the container features.

The procedures below walk you through installing the plug-ins for a PM/CM container.

To install plug-ins on the PM/CM container
  1. At the Available Features list, from the Filter drop-down list at the top left, choose Plug-Ins.
  2. Choose features to install. For example, if Community Manager is installed on the container you'd choose the Akana Community Manager Policy Console and one or more themes:
    • Akana Community Manager Policy Console
    • Akana Community Manager Default Theme
    • Akana Community Manager Hermosa Theme
    • Akana Community Manager Simple Developer Theme
  1. Click Install Feature; then, at the Resolution Summary, click Install Feature again.
  2. Review the installation summary. To continue to the configuration step, click Configure.

back to top

Step 6: Complete pending tasks to configure container features

The next step is to configure the features you've just installed on the container. You can either:

  • Click Configure at the end of the installation process in the previous step. The process steps you through the wizards for each configuration step.
  • Manually start the configuration tasks at any point. In the Akana Administration Console for the container, click the Installed Features tab. Pending installation steps are listed at the bottom left. Click Complete Configuration to start the process.

Note: Before configuring the database, make sure you have the applicable database driver in place. See Database drivers.

Pending installation tasks for this installation scenario are shown below.

Pending installation tasks
  • Manage PKI keys: Specifies key management options.
  • Add Database: Creates the database for the installation.
  • Manage Schemas: Manages the database schemas for the container.
  • Create Policy Manager Admin User: Creates the top-level Policy Manager user.
  • Provisioning: Initializes resources associated with the features installed on the container.
To configure features for the PM/CM container
  1. Start the configuration step, either by clicking Configure at the end of the installation process or by choosing Installed Features > Complete Configuration as shown above. Configuration steps vary depending on the features you're installing. The tasks below apply to the PM/CM container scenario.
  2. At the Manage PKI Keys wizard, choose key management options and other values and then click Finish. Review the summary and then click Go to Next Task.

    For more information on this wizard, see Installation wizard: Manage PKI Keys below.

  3. At the Configure Database Options Wizard, specify your database and other values. Since this is the first container, select Create new database/ For subsequent containers, you'll use the same database, so for a subsequent container you'd select Use existing database.

    Notes:

    • You'll need to have your database driver in place, in the {installation}\instances\{containername}\deploy folder, before running this wizard. See Database drivers.
    • Oracle: If you're using a new Oracle database, see Database notes: Oracle for additional Oracle-specific information about DBA permissions and password configuration.
    • MySQL: If your installation will include Lifecycle Manager, you'll need to add the required grants to the DB user before continuing to Step 4. For details, see Database notes: MySQL with Lifecycle Repository.

    For more information on this wizard, see Installation wizard: Add Database below.

  4. At the Manage Schemas wizard, check the checkbox for the Policy Manager schema, as shown below, and click Finish. Review the summary and then click Go to Next Task.

    For more information on this wizard, see Installation wizard: Manage Schemas below.

  5. At the Define Policy Manager Administrator Credentials Wizard, specify Administrator credentials (username and password). Click Finish. Review the summary and then click Go to Next Task.

    For more information on this wizard, see Installation wizard: Define Policy Manager Administrator Credentials below.

  6. At the Provisioning Wizard, make sure the box is checked, and then click Finish.

    For more information on this wizard, see Installation wizard: Provisioning below.

  7. When the provisioning task is complete, you'll see a message box prompting you to restart your system. Click OK.
  8. At the Complete Configuration page, click Close.

Configuration of the first container is now complete.

back to top

Step 7: Create and configure additional containers

Once you have the first container set up, it's time to create and configure additional containers. Essentially you'll follow these steps for each container: Step 3: Run Configurator to create the first container through Step 6: Complete pending tasks to configure container features. See To create an additional container below.

Create containers in this sequence:

  1. First, create all Policy Manager/Community Manager containers.
  2. Then, create all Network Director containers.

    You can create a Network Director container using either GUI or Silent options. For instructions on how to install a Network Director Container (ND1), install and configure the Network Director feature, and register the ND1 container in Policy Manager, refer to Using Network Director Feature.

To create an additional container
  1. Run Configurator to create the container. See Step 3: Run Configurator to create the first container. Note these differences:
    • Use a different port number for each container.
  2. Install features on the container. See Step 4: Install Policy Manager/Community Manager features on the container. For information on which features you might choose, see Sample installation scenarios. For the Network Director container in this scenario, you would install:
    • Akana Network Director
  3. Install any needed plug-ins on the container.

    For the Network Director container, you don't need any plug-ins unless you are setting up a cluster.

  4. Configure the features. See Step 6: Complete pending tasks to configure container features. Note these differences:
    • If you had to copy a database driver for the first container, you'll need to complete the same action for each subsequent container.
    • In the Configure Database Options Wizard, choose Use existing database, and add the information about the database you set up for the first container.
    • For the Network Director container, you'll need to configure WS-MetaDataExchange options. Make sure the URL is set to {PM_URL}/wsmex. For example: http://localhost:9900/wsmex. If you have multiple PM/CM containers set up as a cluster, use the URL for the master node.

    Pending installation tasks for a Network Director container are shown below. For more information on these tasks, see Installation wizard, ND container: Configure WS-Metadata Exchange Options and Installation wizard: Manage PKI Keys.

    Pending Installation tasks, ND container

Follow the steps for each container until all containers are set up and configured.

As you complete the configuration for each container, be sure to restart at the prompt.

back to top

Step 8: Add Network Director to Policy Manager

The next step is to add the Network Director to Policy Manager so that you can access the developer portal and start sending traffic.

Note: If you are using the developer portal, it's not strictly necessary to complete this step, since in version 8.4 you can add and manage API Gateways in the developer portal. However, you'll still need this step if you are setting up a single API Gateway to be used by multiple tenants in a multi-tenant deployment.

To add Network Director to Policy Manager
  1. Using the URL you set up for Policy Manager (Step 3 above), access Policy Manager in the browser. For example: http://localhost:9900. This redirects to the Policy Manager login page: {pm_url}/admin/login.html. Log in using the credentials you set up.
  2. In the Organization Tree, under Containers, click Add Container, as shown below.

    add container

  3. At the Add Container wizard:
    • Select Container Type: Container or Container Cluster. Click Next.
    • Specify Metadata Import Options: Set up the metadata URL for the Network Director container, using the URL you set up for the container and appending /metadata. For example: http://localhost:9902/metadata. Click Next.
    • X.509 Certificate Not Trusted: If you get this message, modify the certificate or accept the default to add the certificate to the Policy Manager trusted certificate store. Click Next.
    • Specify Container Details: Provide an instance name (for example, ND1). Click Finish.
    • Completion Summary: review the summary and then click Close.
  4. Check that the container appears in Policy Manager. It should look something like the below. The initial state value is Stopped, but after a short time it changes to Started as shown below.

    Network Director container in Policy Manager

If you're using the developer portal, the next step is to create the Community Manager tenant.

back to top

Step 9: Create Community Manager tenant using the Jython script

The next step is to create the tenant for the developer portal. To do this, you'll need to do the following, in sequence.

Conditional, Linux users only Export the JAVA_HOME location to your installation directory. See Linux install: exporting the JAVA_HOME variable.
All users Determine the values you'll use in your Jython script. The script includes various parameters that you can use to specify values for your tenant. See Developing and running the Jython script below.
All users Run the Jython script at the command line. See To run the Jython script below.
Conditional, for custom tenant name If you choose a tenant name other than the default (atmosphere), update a configuration setting to the new value, in the Akana Administration Console for the CM container. See Conditional: updating configuration setting for new context root below.

Developing and running the Jython script

In composing your script, refer to the examples below:

  • Example 1: Template script with each parameter on a separate line, with placeholder values.
  • Example 2: An example with each parameter on a separate line, with sample values.
  • Example 3: Jython script example for Unix.

For detailed information about the various parameters that make up the Jython script, and the values you can choose, see Jython Script Elements.

Note: The default value for the context path in the consoleAddress parameter is atmosphere. If you change the value, as in Example 2 below where the value is set to acmepaymentscorp, there is an additional step you'll need to take before running the developer portal, to update the atmosphere.context.root value in the Akana Administration Console. See Conditional: updating configuration setting for new context root below.

Example 1: Template script with placeholders

In the template script below, each parameter is shown on a separate line, for clarity. Replace the values enclosed in curly brackets with the values for your implementation (remove the curly brackets). When running the script, remove the line breaks and leave a space between parameters.

jython.bat ../scripts/Lib/soa/atmosphere/tenant.py -a -v 
--url {CM_URL} 
--tenantName {tenantid} 
--tenantId {tenantid} 
--address {CM_URL} 
--consoleAddress {CM_URL/{context_path} 
--theme default 
--themeImpl default
--email {emailaddress} 
--password {password} 
--contactEmailAddress {emailaddress} 
--fromEmailAddress {emailaddress}
--username {username} 
--userpassword {password}

Example 2: Each parameter on a separate line, with sample values

In the example below, line breaks have been added between the Jython script elements, for clarity. When running the script, remove the line breaks and leave a space between parameters.

This example installs Hermosa theme (theme = hermosa, themeImpl = default).

jython.bat ../scripts/Lib/soa/atmosphere/tenant.py -a –v 
--url http://localhost:9901 
--tenantName acmepaymentscorp 
--tenantId acmepaymentscorp 
--address http://localhost:9901 
--consoleAddress http://localhost:9901/acmepaymentscorp 
--theme hermosa 
--themeImpl default 
--email administrator@acmepaymentscorp.com 
--password MyPassword 
--contactEmailAddress support@acmepaymentscorp.com 
--fromEmailAddress notifications@acmepaymentscorp.com
--username admin_123
--userpassword AdminPassW0rd123

Example 3: Unix example

In the example below, a few line breaks have been added, for display purposes.

./jython.sh ../scripts/Lib/soa/atmosphere/tenant.py -a -v --url http://pm84-13.local.akana.com:9900 
--tenantName EnterpriseAPI --tenantId enterpriseapi --address http://pm84-13.local.akana.com:9900 
--consoleAddress http://pm84-13.local.akana.com:9900/enterpriseapi --theme default --themeImpl default 
--email support@acmepaymentscorp.com --password password --contactEmailAddress support@acmepaymentscorp.com 
--fromEmailAddress no_reply_cm@acmepaymentscorp.com --username admin_123 --userpassword AdminPassW0rd123
To run the Jython script
  1. At a command prompt, go to the \bin folder for your installation.
  2. Run the Jython script command, customized for your installation, as shown in the example above.
  3. The script runs, and returns a response code 200 with a message that it was successful, as shown in the example below.

    Jython script successful

Note: If you get a 404, make sure that the container is started. Start the container and run the script again.

Conditional: updating configuration setting for new context root

The default value for the context path in the consoleAddress parameter is atmosphere. If you use a different value in the Jython script, you'll need to change a configuration setting before running the developer portal. Follow the instructions below. For example, if you choose / as the context root (consoleAddress value of {CM_URL}/), change this configuration setting to /.

To update the configuration setting for the new context root
  1. Log in to the Akana Administration Console for the CM container.
  2. Click the Configuration tab.
  3. On the left, under Configuration Categories, find the com.soa.atmosphere.console category.
  4. On the right, find the atmosphere.context.root property, and update the value. An example is shown below.

    updating configuration

  5. Click Apply Changes.
  6. Restart the container so that the changes take effect.

Now, you can log in to the developer portal and start configuring settings and adding apps and APIs. See Step 10: Run the developer portal below.

back to top

Step 10: Run the developer portal

Installation steps are now complete, and you can run the develop portal and set up domains and users, configure settings, and add apps and APIs.

To run the developer portal
  1. Compose the developer portal URL as follows:
    • Take the root address for the container that CM is installed on: for example, http://localhost:9901.
    • Append /{tenantid}. For example: http://localhost:9901/acmepaymentscorp.
  2. Paste the URL in the browser. The browser redirects to the default landing page; for example: http://localhost:9901/acmepaymentscorp/#/home/landing.
  3. Log in, using the username and password from the Jython script.

For information about tasks relating to the developer portal, including Site Admin tasks such as configuring platform login, setting up domains, and choosing platform settings, as well as user tasks such as adding apps and APIs, refer to the platform help: http://docs.akana.com/cm/learning.html.

back to top

Installation Tasks/Reference:

Supported databases

Akana API Platform 8.4.x supports the following database versions:

Database notes

This section includes notes and additional information relating to installation with supported databases. It includes:

Database notes: Oracle

Please note the following if you're working with an Oracle database:

Oracle password

If you're creating a new Oracle database using the Create New Database wizard (standard installation procedure), make sure the Oracle database password does not start with a number or special character.

Database permissions, Oracle 12c only

When using Oracle 12c to configure a new database, the DBA must GRANT SELECT ON SYS.USER$ TO SYSTEM; (substitute the SYSTEM user for the user specified for the Administrator credentials). This is because Oracle 12c introduced restricted access to SYS.USER$, which the platform uses to query on.

Database drivers

For Oracle database drivers, see Database drivers below.

Database notes: Microsoft SQL Server

Please note the following if you're working with a Microsoft SQL Server database:

Updating the quartz trigger property for Microsoft SQL Server

If you're using Microsoft SQL Server, you must configure a setting in the Akana Administration Console. The quartz trigger property must be set to True. Follow the steps below.

  1. Log in to the Akana Administration Console for the CM container.
  2. Click the Configuration tab.
  3. On the left, under Configuration Categories, find the com.soa.scheduler.quartz category.
  4. On the right, find theorg.quartz.jobStore.acquireTriggersWithinLock property, and set it to True.
  5. Save your changes.
Database notes: Microsoft SQL Server with Lifecycle Repository

When using any version of MSSQL with Lifecycle Repository, the DBA will need to manually alter the database to set read committed snapshot and enable snapshot isolation mode. This is not required for installation; however, it will affect how the application behaves once asset content is being populated. Run the following:

ALTER DATABASE {db.instance.name}
  SET READ_COMMITTED_SNAPSHOT ON;
ALTER DATABASE {db.instance.name}
  SET ALLOW_SNAPSHOT_ISOLATION ON;

MySQL: database settings for the API Platform

If you're using MySQL 5.6, the settings below are required for the API Platform. You'll need to configure these settings in the my.ini file before loading the database schema in MySQL.

Specific properties are listed below, with references to the applicable MySQL documentation:

For more information, refer to MySQL Database Property Settings.

Database notes: MySQL with Lifecycle Repository

For Akana API Platform 8.4 installs using the Lifecycle Repository feature, the Lifecycle Manager database user requires specific additional grants when using MySQL. These grants are required for successful completion of the Initialize Repository Database configuration task; otherwise, the task fails.

The Lifecycle Repository feature is part of the following installation features:

  • Lifecycle Coordinator (API Promotion)
  • Lifecycle Platform (Custom Metadata)

For MySQL installs, the user must have the following grants:

  • TRIGGER
  • CREATE ROUTINE
  • ALTER ROUTINE

You'll need to run the following MySQL statement to add the correct permissions:

GRANT ALTER ROUTINE, CREATE ROUTINE, TRIGGER ON {database_instance_name}.* TO '{database_user}'@'%';

For example:

GRANT ALTER ROUTINE, CREATE ROUTINE, TRIGGER ON LXC1PM8X21.* TO 'LXC1PM8X21'@'%';

In the above, LXC1PM8X21 is both the database instance name and the database user name.

Use the following command to confirm the change:

mysql> show grants for 'LXC1PM8X21'@'%';

You'll see a response such as the following, which confirms that the grants were updated successfully:

+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Grants for LXC1PM8X21@%                                                                                                                                                                                                                               |
 +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, RELOAD, PROCESS, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, EXECUTE, CREATE VIEW, SHOW VIEW ON *.* TO 'LXC1PM8X21'@'%' IDENTIFIED BY PASSWORD '*2A5FDEE54AE88A62B88A1A6C5389C23A529F20EE' |
 | GRANT ALTER ROUTINE, CREATE ROUTINE, TRIGGER ON 'LXC1PM8X21'.* TO 'LXC1PM8X21'@'%'                                                                                                                                                                                   |
 +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 2 rows in set (0.00 sec)

Note: Lifecycle Manager on MySQL imposes limitations on such things as Advanced Queries using custom XPathCriteria, and only a limited number of fixed XPathCriteria are support in the default searches.

back to top

Database drivers

Depending on which database server you're using, you might need to install a database driver before running the Configure Database Options Wizard.

If you need to install a database driver, place it in this location:

  • /instances/{container_name}/deploy folder

Database options, with driver information:

back to top

Installation folder structure

The installation process creates the folder structure shown below.:

Installation folder structure

Installation includes the following folders:

bin
Includes the Akana Platform shell and batch scripts. This includes Start/Stop scripts for all the Akana Platform processes, scripts used to register and un-register Windows services, and scripts for launching the Akana Platform administration and configuration wizards. This folder also includes a script to run the Akana Platform product as a unique Cron job.
config
Includes Akana Platform properties files. Reserved for system use.
docs
Includes product documentation.
instances
After installation, the initial instances folder includes config.properties and system.properties files.
When you launch and complete the Configure Container Instance wizard, a Configurator folder is created that includes the following sub-folders:
  • asynchworkflow—Stores code samples for platform APIs.
  • cache—Stores OSGi bundles for installed features.
  • deploy—Includes properties files (com.soa.config.cfg and com.soa.log.cfg) that include Akana Platform default configuration settings. These files are used to push default configuration information to the Administration Console and are typically for one-time use only. After initial configuration, you can update properties in the Administration Console via the Configuration tab. Bundles and other .cfg files can also be added to the \deploy folder and will be published to the Administration Console. These properties can also be updated via the Configuration tab.
  • log—Stores log files that are automatically generated when an Akana Platform function is operating. The logging process records the actions performed for each Akana Platform function and stores the information in the log file. You can archive log files for historical record as needed.
Each time a new container instance is created, the platform creates a new folder using the container name. For example, if you install the Policy Manager ZIP file and name the container instance, the associated folder includes the above folders plus the following:
  • cachedir—Reserved for system use.
  • cm—Stores configuration data associated with the Akana Administration Console Configure tab.
  • scriptStore—Stores code samples for platform APIs.
  • snapshot—Stores changes to a container made during updates. Also used for update rollbacks.
  • wsdlStore—Stores code samples for platform APIs.
jre
A Java Runtime Environment (JRE) folder that is automatically created during an Akana product installation. The Akana Platform is packaged with the applicable JRE version for each release.
jreupdate
Includes an ext folder that stores bouncy castle artifacts, and a security folder that provides security algorithms and is used for PKCS12 keystore management.
lib
Includes the jar files needed by the available Akana features.
scripts
Includes script utilities that you can use to create containers without using the Configure Container Instance wizard UI.
yajsw
Includes files used by the Akana Platform to support YAJSW. See http://yajsw.sourceforge.net.

back to top

Clear Configurator cache

You might need to clear the configurator cache. Follow the steps below.

To clear configurator cache
  1. Locate the configurator cache folder: \instances\configurator\cache, as shown below.

    Configurator cache folder

  2. Delete the folder if it exists (if there is no cache, the folder will not be there).

back to top

Starting a container

There are several approaches to starting a container:

To start a container in Windows at a command prompt
  1. At a command prompt, navigate to the \bin folder for the implementation. For example: c:\akana\aap84\bin.
  2. Type:
    startup {containername}

There might be a short delay while the container starts.

To start a container as a Windows service

Note: You can only start a container as a Windows service if it was installed as a Windows service.

  1. Launch the Services list (Control Panel > Administrative Tools > Services).
  2. Select the instance name on the list.
  3. From the right-click Actions menu, choose Stop.

There might be a short delay while the container starts.

To start a container in Unix
  1. At the command line, navigate to the /bin folder for the implementation. For example: /akana/aap84/bin.
  2. Type:
    startup.sh {containername}

There might be a short delay while the container starts.

To start a container in Unix (background)
  1. At the command line, navigate to the /bin folder for the implementation. For example: /akana/aap84/bin.
  2. Type:
    startup.sh {containername} -bg

There might be a short delay while the container starts.

back to top

Stopping a container

You can stop a container in several ways.

To stop a container at a command prompt
  1. Go to the command prompt window where the process is running.
  2. Type Ctrl+C or close the command prompt.
To stop a container as a Windows service

Note: You can only start/stop a container as a Windows service if it was installed as a Windows service.

  1. Launch the Services list (Control Panel > Administrative Tools > Services).
  2. Select the instance name on the list.
  3. From the right-click Actions menu, choose Stop.
To stop a container in Unix
  1. Go to the command line window where the process is running.
  2. Send the process a KILL signal or type Ctrl+C.
To stop a container in Unix (background)
  1. At the command line, navigate to the /bin folder for the implementation. For example: /akana/aap84/bin.
  2. Type:
    shutdown.sh

back to top

Creating a container via the GUI

As part of Step 3: Run Configurator to create the first container, you might choose to create the container via the GUI, a Windows-based wizard that steps you through the installation process.

To create a container via the GUI

For more information on the wizard, see Installation wizard: Configure Container Instance.

  1. Open a command prompt.

    Note: if you want to install the container as a Windows service, open the command prompt in Administrator mode.

  2. Go to the new folder where you unzipped the version 8.4x files (for example, aap84).
  3. Navigate to the \bin subfolder and run one of the following commands, depending on your operating system:

    Windows:

    startup.bat configurator

    Unix:

    startup.sh configurator

    The Configurator starts with the Welcome to Configure Container Instance wizard page, as shown below.

    Configurator

  4. Click Next. The wizard steps you through the following pages:
    1. Instance Name: Specify the name of the Akana container instance; for example, pmcm1. Click Next.
    2. Default Admin User: Specify Administrator Credentials (username and password). Click Next.
    3. Default HTTP Listener: Specify port, host IP address, and bind to all interfaces/specified interface only, or accept defaults. Click Next.
    4. Instance Startup: Choose Standalone, Install as Windows Service, or Do Not Start Instance. Click Next.

      Note if you want to install as Windows service, the command prompt you used to start the Configurator must be running in Administrator mode.

    5. Launch Admin Console: The checkbox is selected by default. If you do not want to launch the Akana Administration Console, clear the checkbox. Click Next.
    6. Instance Configuration Summary: Review the summary. If all OK, click Finish. The container is configured. When configuration is complete, the Akana Administration Console starts automatically (unless you cleared the checkbox in the previous step; if so, you'll need to start it manually).

When you've created the container, continue with the next step of the installation procedure: see Step 4: Install Policy Manager/Community Manager features on the container.

back to top

Creating a container using silent install (Linux)

As part of Step 3: Run Configurator to create the first container, in some scenarios such as Linux installations, you'll create the container using silent install.

Before you begin, make sure you have Administrator rights on the machine you're using.

A silent installation is an automatic process that installs the Akana Platform without any user interaction. Before running the silent install, you must configure the properties file (installer.properties). For example, you must specify a target installation directory, install set, and input options to be executed at the end of the installation. Once you've configured the properties file, you can deploy the platform onto multiple computers in a scripted, non-interactive way.

One way to generate a properties file is to first perform a standard Akana Platform installation using the correct files for your installation. When platform installation is complete, the properties file is automatically saved in the directory from which you launched the setup file. The file includes the configuration settings you specified during setup; from here, you can customize further as needed.

You can also create the properties file from scratch. An example is shown below. For more details about the properties file, see Configure Container (Silent Option).

Properties file with placeholders:

//Required properties
container.instance.name={instancename}
credential.username = {username}
credential.password = {password}
default.host={hostname}
default.port={port}

//Optional properties
container.key={container_key_name}

Sample properties file with values:

container.instance.name=AAP84
credential.username = administrator
credential.password = password
default.host=rhe12345.akana.local
default.port=9945
container.key=AAP84

To run the properties file in a Linux environment, go to the {release_directory}/bin folder and run the following command:

startup.sh configurator -Dsilent=true -Dproperties={full path to properties file}/{filename}.properties

For example:

startup.sh configurator -Dsilent=true -Dproperties=properties/pmcm_silentinstall.properties

Then:

For full instructions, refer to: Configure Container (Silent Option).

Note: Silent install is not supported for Windows machines.

back to top

Unregistering and re-registering the Windows service

If you have a container registered as a Windows service so that the container will start automatically when Windows starts, and you want to unregister and re-register the Windows service, follow the steps below for each container.

Unregistering/re-registering the Windows service is generally part of upgrade procedure, but you might need to do this for some other reason.

If you're not sure which containers are registered as a Windows service, you can check (Control Panel > Administrative Tools > Services).

Note: To change the services, you must run the process as an Administrator. If you don't use Administrator mode, Windows prompts for Admin permission before unregistering/registering the service, but doesn't actually start the service.

To unregister and re-register the Windows service
  1. Open a command prompt in Administrator mode.
  2. Run the command below:
    .\sm70\bin\unregisterContainerServiceYAJWS.bat{instance_name}
  3. Register the new version as a Windows service:
    .\{aap84_foldername}\bin\registerContainerServiceYAJWS.bat {instance_name}

    If you're running in Administrator mode, Windows registers the service and also starts it.

  4. Repeat steps 2 and 3 for each additional container that's registered as a Windows service.

back to top

Linux install: exporting the JAVA_HOME variable

Because Linux containers don't have a JAVA_HOME environment variable set, you'll need to export the JAVA_HOME location to your installation directory.

For example:

export JAVA_HOME=/opt/akana/aap84/jre

If you omit this step, you'll get an error during the installation.

back to top

Installation wizard: Manage PKI Keys

The Manage PKI Keys pending installation task opens the Manage PKI Keys wizard. This task allows you to specify key management options. The wizard has two pages, as shown below.

Manage PKI Keys wizard, page 1

Manage PKI Keys wizard, page 2

back to top

Installation wizard: Add Database

The Add Database pending installation task opens the Configure Database Options wizard. This task creates the database for the installation. The wizard has two pages, as shown below.

On the first page, specify new, existing, or JNDI database, and then click Next.

 Configure Database Options wizard, page 1

On the second page, enter all the database details such as type and credentials, and then click Finish.

 Configure Database Options wizard, page 2

back to top

Installation wizard: Manage Schemas

The Manage Schemas pending installation task opens the Manage Schemas wizard. This task manages the database schemas for the container.

Make sure available schemas are checked, and then click Finish.

 Manage Schemas wizard, page 1

When schema installation is complete, a Summary page is displayed. Click Go to Next Task.

back to top

Installation wizard: Define Policy Manager Administrator Credentials

The Create Policy Manager Admin User pending installation task opens the Define Policy Manager Administrator Credentials wizard. This task creates the top-level Policy Manager user.

Enter the user credentials, and then click Finish.

 Define Policy Manager Administrator Credentials wizard

Review the summary page and then click Go to Next Task.

back to top

Installation wizard: Provisioning

The Provisioning pending installation task opens the Provisioning wizard. This task Initializes resources associated with the features installed on the container.

Make sure the box is checked, and then click Finish.

 Provisioning wizard

back to top

Installation wizard: Configure Container Instance

Configure Container Instance wizard pages:
  • Instance Name: provide name; for example, aap84.
  • Default Admin User: specify Administrator Credentials (username and password).
  • Default HTTP Listener: port, host IP address, bind to all interfaces/specified interface only.
  • Instance Startup: Choose Standalone, Install as Windows Service, or Do Not Start Instance.

    Note: If you want to run Install as Windows Service, the command prompt you used to start the Configurator must be in Administrator mode. If necessary, restart the Configurator in a new window in Administrator mode.

  • Launch Admin Console: The checkbox is selected by default. If you do not want to launch the Akana Administration Console, clear the checkbox. Click Next.
  • Instance Configuration Summary: review options. If all OK, click Finish.

back to top

Installation wizard, ND container: Configure WS-Metadata Exchange Options

The Configure WS-Metadata Exchange Options task for the Network Director container opens the WS-Metadata Exchange Options wizard. This task Initializes resources associated with the features installed on the container.

Put in the metadata URL for the Network Director container, using the URL you set up for the container and appending /wsmex; for example: http://localhost:9902/wsmex. Click Finish.

 Specify Metadata Import Options

back to top

Installation Options: Full List

Installation can include one or more of the following:

  • Features: Core products or major features that support core products.
  • Plug-Ins: Additions to core products that add to the functionality.
  • Tools: Tools that provide specific functionality for maintaining or upgrading features and plug-ins.

The full list of installation features is shown below.

 Features

The full list of plug-ins is shown below.

 Plug-Ins

The full list of tools is shown below.

 Tools

back to top

Policy Manager Add Container wizard

When adding the Network Director to Policy Manager (step 8 above) you'll use the Add Container wizard. The pages for this wizard are shown below.

Page 1: Select Container Type

Select Container Type and click Next.

 Add Container wizard, Select Container Type page

Page 2: Specify Metadata Import Options

Specify the metadata URL and click Next.

 Add Container wizard, Specify Metadata Import Options

X.509 Certificate Not Trusted

If you get this message, you'll need to decide whether to add the certificate to the Policy Manager certificate store.

 Add Container wizard, X.509 Certificate Not Trusted

Page 3: Specify Container Details

If needed, add information about the container.

 Add Container wizard, Specify Container Details

Completion Summary

At the Completion Summary page, click Close.

 Add Container wizard, Completion Summary

back to top

Sample installation scenarios

The examples below show which features to install for some sample scenarios, including:

One container with Policy Manager installed (no Community Manager)

Install these features on the Policy Manager container:

  • Akana Policy Manager Console
  • Akana Policy Manager Services (Includes Akana Management Services, Akana Security Services, and Akana Scheduled Jobs. For more information on this feature see Using the Policy Manager Services Feature.)

Install this feature on the Network Director container:

  • Akana Network Director

Multi-container setup with Policy Manager installed (no Community Manager)

Policy Manager Container Features:

  • Akana Policy Manager Console
  • Akana Policy Manager Services (Includes Akana Management Services, Akana Security Services, and Akana Scheduled Jobs. For more information on this feature see Using the Policy Manager Services Feature.)

Network Director Container Features:

  • Akana Network Director

One container with both Policy Manager and Community Manager installed

Community Manager Container Features:

Install these features:

  • Akana Community Manager APIs
  • Akana Community Manager OAuth Provider
  • Akana Community Manager Scheduled Jobs
  • Akana Embedded Elasticsearch Node
  • Akana OAuth Provider
  • Akana Policy Manager Console
  • Akana Policy Manager Services (Includes Akana Management Services, Akana Security Services, and Akana Scheduled Jobs. For more information on this feature see Using the Policy Manager Services Feature.)
  • Akana Community Manager
Community Manager Container Plug-ins:

Install these plug-ins:

  • Akana Community Manager Policy Console
  • One or more of the following (at least one theme is required for Community Manager):
    • Akana Community Manager Default Theme
    • Akana Community Manager Hermosa Theme
    • Akana Community Manager Simple Developer Theme

Install this feature on every Network Director container:

  • Akana Network Director

Needed in any multi-container deployment that does not include Community Manager

Install these features on every non-Network Director container:

Install this feature on every Network Director container:

  • Akana Network Director

back to top

Feature Notes: Scheduled jobs

Platform installation options include the following scheduled jobs features:

  • Akana Scheduled Jobs—bundled with the Akana Policy Manager Services feature
  • Akana Community Manager Scheduled Jobs

There might be additional scheduled jobs features for additional add-ons; for example, the LaaS Add-On includes a scheduled jobs feature.

In general, we recommend that you install all scheduled jobs on the same container. In a scenario where Policy Manager and Community Manager are on different containers, you'd most likely install the scheduled jobs on the Policy Manager container. This helps avoid overload on the Community Manager container, since Community Manager might be processing a lot of traffic, whereas the Policy Manager container is likely to be inside the firewall and used internally.

back to top

Feature Notes: Akana Embedded Elasticsearch Node feature

If you are using Elasticsearch in Embedded Mode, note that the Akana Embedded Elasticsearch Node feature requires that the Akana Community Manager Scheduled Jobs feature is installed on the same container, as well as the Community Manager portal features where the search is being performed.

However, bear in mind that we do not recommend using Elasticsearch Embedded mode in a production environment.

If you are running an external Elasticsearch server with Transport Client mode, it's not necessary to install the Akana Embedded Elasticsearch Node feature.

For more information on installing and configuring Elasticsearch, see Elasticsearch: Information for Site Admins (developer portal help).

back to top

All Versions:

Version 8.2:

Version 8.0: