Installing the Akana API Platform 2022.1.x

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

Note: This document covers instructions for version 2022.1. For an earlier version, refer to Installing the Akana API Platform.

Supported Platforms: 2022.1

Table of Contents

Planning the Installation

Performing the Installation:

Installation Tasks/Reference:

Planning the Installation:

Overview

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

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

  • One container with Policy Manager and Community Manager installed
  • One container running the API Gateway (Network Director)

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

  • Preparation (Steps 1-1 and 1-2)
  • Creating the first container, installing features and plug-ins, and configuring the container (Step 2-3 to Step 2-6)
  • Creating and configuring additional containers (Step 2-7, which is Step 2-3 to Step 2-6 repeated for each container as needed)
  • Adding Network Director to Policy Manager (Step 2-8)
  • Creating and running the API Platform tenant (Step 2-9 and Step 2-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 Community Manager developer portal tenant. This documentation installs features and plug-ins and then configures.

Step 1-1: Plan the installation

Before you start, plan your installation. In particular, you'll need to:

  • Decide what containers you'll have, and which features will be installed in which containers. For a recommended simple configuration, see Sample Deployment Scenario.
  • Make sure your database is set up and that you have the credentials necessary to configure the Akana Platform to access the database. For information on supported databases, go to the System Requirements doc, database versions section.
  • Determine where you'll install Elasticsearch, needed for the search feature. For full information on Elasticsearch, see Installing and Configuring Elasticsearch.
  • Determine whether you'll be using a specific add-on feature that is packaged in a separate option packs ZIP file. Option packs include files for additional features such as:
    • SAML Web SSO
    • SiteMinder Plug-in
    • FreeMarker Activity
    • Headers Activity
    • Normalize Activity

    The option packs are in a separate ZIP file within the Akana Platform ZIP file.

Note: If you are using an external JRE, you'll need to make sure that a compatible JRE version is installed and that you have your PATH set to include the correct JAVA_HOME. After installation, as part of configuration, you'll also need to update the com.soa.security configuration settings. For instructions, refer to Configuring an External JRE.

Step 1-2: Install and configure Elasticsearch (if not already done)

Standalone Elasticsearch is required. REST Client mode is recommended.

For instructions, see Installing and Configuring Elasticsearch.

Performing the Installation:

Step 2-1: Download ZIP files

The first step is to download the required ZIP files.

Prerequisite:

  • Before you start, create a folder for your installation; for example, AAP202201.

Note: The version numbering for the Akana Platform and Akana API Platform files does not necessarily match. For version compatibility, check the release notes for the version you're installing.

To download the installation ZIP file or files

  1. Log in to the Rogue Wave Support Center (https://library.roguewave.com).

    Note: If you don't have login credentials for the site, contact Akana technical support to get access.

  2. Go to Product Downloads > Akana - Product Downloads > Akana 2022.1.x Product Downloads.
  3. Choose your Akana Platform + Akana API Platform download file, according to the point version that you want and your operating system version. For example:
    • Linux (includes JRE): api-platform-linux-jre-2022.1.0.zip
    • Windows (includes JRE): api-platform-win-jre-2022.1.0.zip
    • Windows, Linux, or Solaris (does not include JRE; provide your own JRE, version 1.8): api-platform-no-jre-2022.1.0.zip

    Note: For information on the different platform versions for different operating systems, see Akana Platform: Operating system versions below.

    Note: In versions prior to 2019.1.x, for point releases, it was necessary to download two ZIP files, one for the major version and one for the point release. In 2019.1.x and later major versions, everything is packaged together.

  4. Optional: if you're using one or more option packs, download the option packs ZIP file for the version you're installing: for example, option-packs-2022.1.0.zip.

Step 2-2: Extract installation files

The next step is to extract the files.

Note: You'll need a password to unzip the files. If you don't know the password, contact your Akana representative.

To unzip the installation files

For details about changes in this release, refer to the release notes: go to Release Notes landing page and choose the version.

  1. In your installation folder, unzip the Akana Platform + Akana API Platform ZIP file that you downloaded. It includes two embedded ZIP files. For example:
    • akana-platform-linux-jre-2022.1.x.x.zip
    • akana-api-platform-2022.1.x.xx.zip
  2. Unzip the Akana Platform ZIP file (passworded).
  3. Unzip the Akana API Platform ZIP file (passworded).
  4. Optional: If you're using one or more option packs, unzip the Option Packs ZIP file (same password as for Akana Platform). Then unzip the embedded Options Pack ZIP file.

Akana Platform: Operating system versions

The Akana Platform 2022.1.0 download ZIP file contains within it ZIP files for each operating system, so that you can choose the appropriate file for the operating system you're using:

  • Linux (includes JRE): akana-platform-linux-jre-2022.1.x.x.zip
  • Windows (includes JRE): akana-platform-win-jre-2022.1.x.x.zip
  • Windows, Linux, or Solaris (does not include JRE; provide your own JRE, version 1.8): akana-platform-2022.1.x.x.zip

    Note: If you're running on Windows and using your own JRE, be sure to set your JAVA_HOME system variable. The platform uses this when registering Windows services.

Step 2-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 Admin 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.

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

Follow the steps 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 deployment scenarios.

To install Policy Manager/Community Manager features on the container

  1. In the Admin Console, go to the Available Features list.
  2. Install the following features:
    • Akana Community Manager. Installing this feature also automatically installs the following bundled features:
      • Akana Community Manager APIs feature
      • Akana Community Manager Hermosa Theme plug-in
    • Akana Community Manager OAuth Provider (Should be installed for any Community Manager container)
    • Akana Community Manager Scheduled Jobs
    • Akana Management Services
    • Akana OAuth Provider
    • Akana Policy Manager Console
    • Akana Policy Manager Services—this feature bundle includes the Akana Scheduled Jobs feature which adds jobs to the Quartz scheduler. It also includes Akana Security Services. This feature is needed on all containers except Network Director.

    Note: If you're following the sample deployment scenario, see Community Manager/Policy Manager container features with access to MongoDB.

  3. Click Install Feature and then, at the Resolution Complete summary page, click Install Feature again.
  4. At the Installation Complete summary, click Configure (if you are installing plug-ins, click Close and install plug-ins first).

The next step is to install any additional features that are needed for the container, to support the initial group of features. See Step 2-5: (as needed) Install additional features on the container below.

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

Note: The instructions below are for the traditional Admin Console user interface. For the redesigned Admin Console, see Step 2-5b: (as needed) Install additional features on the container below.

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 (traditional Admin Console)

  1. At the Available Features list, from the Filter drop-down list at the top left, choose Plug-Ins.
  2. Install these plug-ins:
    • Akana Community Manager Policy Console plug-in
    • Optional: Akana OAuth Plug-In (must be installed on the Community Manager container if OAuth is installed on a separate container)
  3. If needed, install one or more additional themes (also in the plug-ins list):
    • Akana Community Manager Bonita Theme
    • Akana Community Manager DevOps Theme (applicable only if you have Lifecycle Manager integration)
    • Akana Community Manager Simple Developer Theme

    Note: Hermosa Theme is installed as part of the Akana Community Manager feature.

  4. Click Install Feature and then, at the Resolution Summary, click Install Feature again.
  5. Review the installation summary. To continue to the configuration step, click Configure.

Step 2-5b: (as needed) Install additional features on the container

Note: The instructions below are for the redesigned Admin Console user interface. For the traditional Admin Console, see Step 2-5a: (as needed) Install plug-ins on the container above.

Depending on your installation scenario, you might need to install additional features on your container, to support the initial group of features.

Note: The features listed below were plug-ins in versions of the platform earlier than 2022.1.0.

The procedures below walk you through installing these additional feature for a PM/CM container.

To install additional features on the PM/CM container (redesigned Admin Console)

  1. At the Available Features list, install the following:
    • Community Manager Policy Console

      Provides Policy Manager Console extensions supporting Community Manager security policies for application and end-user authentication. Must be installed with Policy Manager Console.

    • Optional: OAuth

      Provides OAuth server integration, ensuring that OAuth tokens stay in sync with changes to apps and APIs. Install into the Community Manager container and Policy Manager container when Community Manager OAuth Provider is deployed in a standalone container.

  2. If needed, install one or more additional themes:
    • Theme: Bonita
    • Community Manager DevOps Theme (applicable only if you have Lifecycle Manager integration)
    • Theme: Simple Developer

    Note: Hermosa Theme is installed as part of the Akana Community Manager feature.

  3. Click Install Feature and then, at the Resolution Summary, click Install Feature again.
  4. Review the installation summary. To continue to the configuration step, click Configure.

Step 2-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 do either of the following:

  • 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 Admin 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.

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. Be sure to follow any applicable database-specific notes from the list below.

    Notes:

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

  4. At the Manage Schemas wizard, check the checkboxes for all listed schemas 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.

    Note: It's important to make sure that the Provisioning task is 100% complete before restarting.

  8. At the Complete Configuration page, click Close.

Configuration of the first container is now complete.

Step 2-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 2-3: Run Configurator to create the first container through Step 2-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 2-3: Run Configurator to create the first container. Note these differences:
    • Use a different port number for each container; for example, 9900 for the PMCM1 container and 9905 for the ND1 container.
  2. Install features on the container. See Step 2-4: Install Policy Manager/Community Manager features on the container. For information on which features you might choose, see Sample deployment scenarios. For the Network Director container in this scenario, you would install:
    • Akana Network Director
  3. Install any needed plug-ins/additional features on the container.

    For the Network Director container:, install the following plug-in / additional feature:

    • Traditional Admin Console—Akana API Platform ND Extensions Feature
    • Redesigned Admin Console—API Platform ND Extensions
  4. Configure the features. See Step 2-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 primary 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.

Step 2-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 Community Manager developer portal and start sending traffic.

Note: If you are using the Community Manager developer portal, it's not strictly necessary to complete this step, since you can add and manage API Gateways in the Community Manager 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 2-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 Community Manager developer portal, the next step is to create the Community Manager tenant.

Step 2-9: Create Community Manager tenant using the Jython script

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

Scenario Action
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 Admin 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: Script example with sample values.
  • Example 3: Jython script example for Unix.

Note: Hostnames in the Jython script must be lowercase.

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 Community Manager developer portal, to update the atmosphere.context.root value in the Admin 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

The example below 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

./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 part of the consoleAddress parameter is atmosphere. This means that, by default, the Community Manager developer portal will be accessible via this URL: {consoleAddress}/atmosphere. If you prefer to use a different value for the context path, you'll have to use that value in the Jython script (--consoleAddress {CM_URL}/{new context path value}.

If you make this change in the Jython script, you'll also need to update a configuration setting to the new value so that you can access the portal using the new context path.

Note: There are certain values that are reserved for other uses. They include: /portal, /api. If you need to change atmosphere.context.root, do not use these values.

Follow the instructions below.

To update the configuration setting for the new context root

  1. Log in to the Admin 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 Community Manager developer portal and start configuring settings and adding apps and APIs. See Step 2-10: Run the Community Manager developer portal below.

Step 2-10: Run the Community Manager 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 Community Manager developer portal

  1. Compose the Community Manager 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 Community Manager 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, see Community Manager Developer Portal Help Content Overview.

Installation Tasks/Reference:

Supported databases

For information on the supported database versions for the Akana API Platform 2022.1.x, refer to System Requirements.

Notes:

Database notes

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

For database driver information for all database types, see Database drivers.

Database notes, all: user permissions

You'll need to grant the following database permissions, depending on the user role:

  • User creating the database: This user will need to have permissions to:
    • Create a user.
    • Create the schema, including creating, altering and dropping tables, indices and constraints.
  • Runtime user: The runtime user created by the scripts should have a minimal set of permissions for runtime plus schema updates. If you remove this user's ability to add/alter/drop objects, you'll need to add them back when it's time to perform schema updates.

Database notes: Oracle

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

Database drivers

For Oracle database drivers, see Database drivers below.

Oracle database password restriction

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.

Use Oracle Service Name, not SID

When you're setting up an Oracle database, the wizard offers two options, Oracle Service Name and SID.

It's best to use Oracle Service Name, as recommended by Oracle. This is true for any version Oracle 12cR1 or later.

Database permissions, Oracle 12c R2 or later

When using Oracle 12c or later 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 creation, Oracle 18c or later

When using Oracle version 18c or later, and deploying with the new Oracle component database architecture (CDB), it's important that you create the database first, and then, in the Configure Database Options wizard, choose the Use Existing Database option (see Installation wizard: Add Database). This is because the Create option in the wizard does not currently support the new Oracle architecture for component/pluggable databases.

When you're creating the database, follow the steps below to create the tablespace and to create the user.

Create tablespace

Run the following, substituting your own values for the MYTABLESPACE and MYDATAFILE values given below:

CREATE TABLESPACE MYTABLESPACE DATAFILE MYDATAFILE.dbf' SIZE 100M REUSE AUTOEXTEND ON NEXT 50M MAXSIZE UNLIMITED NOLOGGING;

Create user

Run the following, substituting your own values for the AKANAUSER, Password, and MYTABLESPACE values given below:

CREATE USER AKANAUSER IDENTIFIED BY "Password" DEFAULT TABLESPACE MYTABLESPACE;
GRANT CONNECT TO AKANAUSER;
GRANT RESOURCE TO AKANAUSER;
GRANT UNLIMITED TABLESPACE TO AKANAUSER;
GRANT CREATE ANY VIEW TO AKANAUSER;
GRANT CREATE ANY SYNONYM TO AKANAUSER;
GRANT DROP ANY SYNONYM TO AKANAUSER;

Then, when you run the Configure Database Options wizard, choose the option to connect to an existing database rather than letting the wizard create the database.

Database notes: Microsoft SQL Server

If you're working with a Microsoft SQL Server database, please note the following:

For additional information on using a Microsoft SQL Server database with Akana products, see Microsoft SQL Server Database Installation and Configuration.

Verifying the quartz trigger property for Microsoft SQL Server

If you're using Microsoft SQL Server, you must make sure that the quartz trigger property in the Admin Console is set to True. Follow the steps below.

  1. Log in to the Admin 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 the org.quartz.jobStore.acquireTriggersWithinLock property, and make sure it is set to True. Change it if needed.
  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;

Database Notes, MySQL

If you're working with a MySQL database, please note the following:

Database notes: MySQL with Lifecycle Coordinator/Lifecycle Repository

For Akana API Platform installs using the Lifecycle Coordinator or Lifecycle Repository features, there are some constraints.

The Lifecycle Repository feature requires the following installation features:

  • Akana Lifecycle Repository (Provides metadata repository and configuration services)
  • Akana API Platform Repository Plug-In (Extended Properties and Workflow feature)

The Lifecycle Coordinator feature requires the following installation features:

  • Akana Lifecycle Coordinator (Lifecycle Coordinator for the Akana Platform)

Review the following information:

LC/LR: Additional database privileges required for installation

When installing on MySQL, you'll need to do one of the following:

  • Disable MySQL binary logging. Note that this might not be feasible in some cases because binary logging is a hard requirement for replication. In addition, if you're using AWS RDS with a Multi-AZ deployment, the replication used for Multi-AZ implicitly enables binary logging.

    For more information on binary logging, see https://dev.mysql.com/doc/refman/5.7/en/stored-programs-logging.html (MySQL documentation).

  • Grant the super privilege to the database user for the Akana API Platform for the duration of the time that Lifecycle Coordinator/Lifecycle Repository features are being installed and libraries (either tenant libraries or topology libraries) are being created.

    An alternative to granting the super privilege is to modify the log_bin_trust_function_creators variable. See LC/LR: Setting the log_bin_trust_function_creators system variable below.

LC/LR: Adding the correct database permissions

With the Lifecycle Coordinator or Lifecycle Repository features, the 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.

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 Coordinator and/or Lifecycle Repository 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.

LC/LR: Setting the log_bin_trust_function_creators system variable

Additional user privileges are needed to successfully initialize the repository database. If the privileges are not in place, the Initialize Repository Database task might fail, with the following error message:

exception:java.sql.SQLException: You do not have the SUPER privilege and binary logging is enabled (you *might* want to use the less safe log_bin_trust_function_creators variable)

In some cases, it might not be feasible to grant the super privilege to the database user or to disable binary logging. An alternative approach is to set the log_bin_trust_function_creators system variable to a value of 1, as shown below:

mysql> set global log_bin_trust_function_creators=1;
Query OK, 0 rows affected (0.00 sec)

However, this is only an in-memory variable. For persistence, you could add the following to the /etc/my.cnf file:

log-bin-trust-function-creators=1

LC/LR: Create libraries before enabling extended properties in the Community Manager developer portal

For more information on using the log_bin_trust_function_creators system variable, see https://dev.mysql.com/doc/refman/5.7/en/faqs-stored-procs.html, sections A.4.25 and A.4.26 (MySQL documentation).

When the Akana API Platform is installed on MSSQL, tenant (repository) libraries should initially be created using the Synchronize Lifecycle Manager Data admin task, before enabling the Extended Properties and Workflow flag in the Community Manager developer portal settings (Admin > Site).

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:

  • MySQL 8.0: install this file:

    mysql-connector-java-8.0.20.jar

    Downloadable from: https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.20/mysql-connector-java-8.0.20.jar

  • Oracle 12c Release 2, Oracle 18c (18.3) supported in 2019.1.0 and later, Oracle 19c: install this file:

    Ojdbc8.jar

    Downloadable from: http://www.oracle.com/technetwork/database/features/jdbc/jdbc-ucp-122-3110062.html (download requires accepting the agreement and logging in).

    Also see Database permissions, Oracle 12c R2 or later.

  • Microsoft SQL Server 2012 SP4: no database driver installation is required.
  • Microsoft SQL Server 2016 SP2: no database driver installation is required. If you don't install a driver, the default JTDS driver is used.

    Akana API Platform has also been tested with the following driver:

    mssql-jdbc-7.0.0.jre8.jar

    Downloadable from: https://www.microsoft.com/en-us/download/details.aspx?id=57175.

    If you use this driver, you'll need to install using the default JTDS driver, then run the first two pending tasks, Manage PKI Keys and Add Database, and then modify some configuration settings and restart the container. You can modify the settings in the Admin Console or by editing the configuration file ({install_dir}/instances/{instance}/cm/com/soa/database/config/{config_file}). The settings you'll need to update are:

    • com.soa.database.config > driver: change to com.microsoft.sqlserver.jdbc.SQLServerDriver.
    • com.soa.database.config > url: change to jdbc:sqlserver://{server}:{port}/{database};user={user};password={password}. Be sure to substitute the correct values for your installation.

    When you've updated the settings, remember to restart the container, and then resume the standard installation process from Step 2-6: Complete pending tasks to configure container features with the Manage Schemas pending task.

Installation folder structure (Akana Platform)

When you install the Akana Platform, the installation process creates the folder structure shown below:

Installation folder structure: Akana Platform

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 Admin 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.
lib
Includes the jar files needed by the available Akana features.
recipes
A set of JSON files that can be used in automating processes.
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.

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).

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\aap202201\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/aap202201/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/aap202201/bin.
  2. Type:
    startup.sh {containername} -bg

There might be a short delay while the container starts.

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/aap202201/bin.
  2. Type:
    shutdown.sh

Creating a container via the GUI

As part of Step 2-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. In Windows, open a command prompt.

    Note: if you want to install the container as a Windows service, open the command prompt in Administrator mode. For example, type cmd, right-click, and choose Run as Administrator.

  2. Go to the new folder where you unzipped the version 2022.1.x files (for example, aap202201).
  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 Admin 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 Admin 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 2-4: Install Policy Manager/Community Manager features on the container.

Creating a container using silent install (Linux)

As part of Step 2-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 that you'll use for the installation. This file will include the specific values that you'd provide in the user interface if you're doing an installation using the GUI. 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 machines in a scripted, non-interactive way.

The name of the properties file you use doesn't matter as long as you reference it correctly when running the silent install.

One way to generate a "starter" properties file is to first create a container using the GUI. When you do this, the properties file for the container is automatically saved in the directory for the container (../instances/{container_name}/system.properties). For example, if you create a pm01 container via the GUI, you can then look in the /instances/pm01 folder and you'll see the system.properties file for the container. You can use the values in this file as a help in setting up the properties file for creating subsequent containers, such as pm02, using the silent install method.

Be sure to copy and modify the file rather than changing the original file, and update the container.key property so that it's unique. Note: container.key can only be specified at the time of container creation; you cannot change it later.

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).

Note: When you create the properties file, make sure there are no trailing spaces.

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=aap202201
credential.username = administrator
credential.password = password
default.host=rhe12345.akana.local
default.port=9945
container.key=aap202201

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=/root/akana/aap/properties/pmcm_silentinstall.properties

Then:

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

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:
    .\{platform_folder}\bin\unregisterContainerServiceYAJWS.bat {instance_name}
  3. Register the new version as a Windows service:
    .\{aap202201_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.

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/aap202201/jre

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

Saving the keystore/truststore and updating the path

The default settings for the keystore/truststore are shown below.

Configuring the keystore and truststore location

If you change the JRE, you must update these settings so that the Akana Platform can access the truststore with the trusted certificates.

For example, you could create a new folder, /{install_folder}/keystore, and copy certs into that folder.

To update the com.soa.security settings

  1. Install the product. For instructions, go to Installing the Akana API Platform and open the installation instructions file.
  2. Log in to the Admin Console.
  3. Click the Configuration tab.
  4. Update these two settings to the new location:
    • bootstrap.keystore.location. For example: file:///{install_folder}/keystore/certs.jks.
    • bootstrap.truststore.location. For example: file:///{install_folder}/keystore/certs.jks.
  5. Update other properties as needed. For example, you must set the correct passwords for the new keystore and truststore locations.
  6. Save the changes.

Note: If you don't set up the new location for this file and update the properties as above, when you restart the container there will be issues due to missing certificates.

Installation wizard: Manage PKI Keys

The Manage PKI Keys pending installation task opens the Manage PKI Keys wizard, as shown below.

We strongly recommend that you use an external keystore, and import private key and X.509 certificate. See:

Manage PKI Keys wizard

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.

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

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

Oracle notes:

  • For Oracle, choose Oracle Service Name (not SID).
  • If you're using Oracle 18c or later, it's important that you create the database first, and then choose the Use existing database option. For more information and instructions, see Database creation, Oracle 18c or later.

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

Installation wizard: Manage Schemas

The Manage Schemas pending installation task opens the wizard at the Install Schemas page. 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.

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.

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.

Note: Make sure the Provisioning task is 100% complete before moving to the next task.

Provisioning wizard

Installation wizard: Configure Container Instance

Configure Container Instance wizard pages:

  • Instance Name: provide name; for example, aap202201.
  • 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 Admin Console, clear the checkbox. Click Next.
  • Instance Configuration Summary: review options. If all OK, click Finish.

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

Installation Options: Full List

In the traditional Admin Console, installation can include one or more of the following:

In the redesigned Admin Console, all options are combined on a Features list. For a full list of features, see Admin Console Features List (2022.1.0).

Installation Features

The full list of installation features, on the Available Features list, is shown below.

Features

Installation Plug-ins

In the Admin Console, go to Available Features > Plug-In, as shown below.

Plug-Ins

Full list of available plug-ins:

Akana API Platform ND Extensions Feature
This feature includes Network Director extensions supporting API Platform security policies for application and end user authentication. This feature needs to co-exist with Akana Network Director feature.
Akana API Platform Plug-In
This feature adds Community Manager extensions to other features where Community Manager extensions are needed. For example, this plug-in adds API specific contract authorization logic to the PM Security Services feature, CM token authentication logic to the PM RESTful services in the PM Management Services feature, and OAuth application support to OAuth Provider feature.
Akana API Platform Repository Plug-In
Extended Properties and Workflow feature
Akana CA SiteMinder Security Provider
This plugin adds security integration with CA SiteMinder.
Akana CA SiteMinder Security Provider UI
This plugin contains the Identity System configuration wizard for the Security Integration with CA SiteMinder.
Akana External Keystore Feature
This feature enables a Container to use an external keystore for managing all the PKI keys and certificates it needs. Without installing this feature the default Policy Manager keystore will be used.
Akana FreeMarker Activity Runtime Plugin
This feature must be installed in Network Director to provide support for the 'FreeMarker Message' process activity. This activity facilitates the normalization of a message in the process.
Akana FreeMarker Activity UI Plugin
This feature must be installed along with the Policy Manager Console and the Community Manager User Interface to provide support for the 'FreeMarker Message' process activity. This activity facilitates the normalization of a message in the process.
Akana Header Activities Runtime Plugin
This feature must be installed in Network Director to provide support for the 'Map Headers' and 'Manage Headers' process activities. These activities facilitate the addition, removal and copying of transport and binding headers in the process.
Akana Header Activities UI Plugin
This feature must be installed along with the Policy Manager Console and the Community Manager User Interface to provide support for the 'Map Headers' and 'Manage Headers' process activities. These activities facilitate the addition, removal and copying of transport and binding headers in the process.
Akana Kafka Support for Network Director
This plugin must be installed in the Network Director container if you want to channel metric information from Network Director to the Policy Manager metrics database via Kafka.
Akana Kafka Support for Policy Manager
This plugin must be installed in the Policy Manager container if you want Policy Manager to consume metric information from the Gateways via Kafka.
Akana Kerberos Impersonation
This plug-in enables Kerberos constrained delegation, or impersonation. Requires Java 1.8.
Akana LaaS Add-On Scheduled Jobs
This feature enables LaaS Add-On scheduled jobs on the container.
Akana Lifecycle as a Service (LaaS) Add-On for Community Manager
This feature allows you to configure a custom workflow for certain objects in Community Manager, with custom forms to collect properties, and to exchange information between Community Manager and Lifecycle Manager.
Akana Master Router Plugin
This feature must be installed on all CM containers to route WRITE traffic to a designated master.
Akana Normalize Activity Runtime Plugin
This feature must be installed in Network Director to provide support for the 'Normalize Message' process activity. This activity facilitates the normalization of a message in the process.
Akana Normalize Activity UI Plugin
This feature must be installed along with the Policy Manager Console and the Community Manager User Interface to provide support for the 'Normalize Message' process activity. This activity facilitates the normalization of a message in the process.
Akana OAuth Plug-In
This feature provides OAuth server integration. It ensures OAuth tokens stay in sync with changes to apps and APIs.
Akana SAML 2.0 Web Browser SSO Service Provider
This plug-in includes the SAML 2.0 Web Browser SSO security module. Any SAML 2.0 provider that supports SP-Initiated-SSO as defined in SAML 2.0 Web Browser SSO profile is supported. As Community Manager and OAuth Provider can utilize this functionality, install this in any container that has Community Manager or the OAuth Provider feature installed.
Akana SAML 2.0 Web Browser SSO Service Provider UI
This plug-in adds support to the Policy Manager Console for configuring a SAML 2.0 Web Browser SSO service provider domain. Install this plug-in only on the containers where the Policy Manager Console feature is installed.
Akana Sample Datasets for Demo Charts
This plug-in provides a series of sample datasets for demo charts that can be installed to the Envision Console. When you install a sample dataset the associated Widget and Dashboard are added to the Envision Console. Requires installation of Akana Envision.

Installation Tools

The full list of tools is shown below.

Tools

Policy Manager Add Container wizard

When adding the Network Director to Policy Manager (step 2-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.

Note: We strongly recommend that you do not use self-signed certificates. Instead, use an external keystore. See:

If you install using a self-signed certificate, you will not be able to upgrade the container to a future version by replicating the existing container as covered in the upgrade documentation.

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

Sample deployment scenarios

The deployment scenarios below list the installation options you should choose depending on the features you'll be running in your containers. It includes the containers for the simple installation scenario covered in this document:

This section also includes feature installation information for the following additional container scenarios:

Community Manager/Policy Manager container features with access to MongoDB

For MongoDB access, the configuration is mainly the same as for a combo Community Manager/Policy Manager container:

However, for MongoDB access, install the following additional plug-in:

  • Akana MongoDB Support

Standalone API Gateway (Network Director)

Install the following feature on each container running Network Director:

  • Akana Network Director

Install the following plug-in:

  • Akana API Platform ND Extensions Feature (needed on the Network Director container for any installation that includes Community Manager)

Standalone OAuth container features

If you are using the Akana API Platform as your OAuth Provider, install the following features on the standalone OAuth container, or the container where you want the OAuth feature to reside. These are not required if you're using an external OAuth provider.

  • Akana OAuth Provider
  • Akana Community Manager OAuth Provider

Note: If you install OAuth on a separate container from Community Manager, make sure the Akana OAuth Plug-In is installed on the Community Manager container. This is needed so that you can configure OAuth via the Community Manager portal.

Scheduled Jobs container features

If you have a standalone container for the Scheduled Jobs features, that add jobs to the Quartz scheduler, install the following:

  • Akana Policy Manager Services—this feature bundle includes the Akana Scheduled Jobs feature which adds jobs to the Quartz scheduler. It also includes Akana Security Services. This feature is needed on all containers except Network Director.
  • Akana Community Manager Scheduled Jobs

Note: There are other scheduled jobs that are run on each container. For example, Network Director has a job scheduler that is responsible for reaching out to Policy Manager to get updated information on which APIs to load. These scheduled jobs are not separate installation features, they are built in to each container.

Container features for standalone Policy Manager container

Install the following features:

  • Akana Policy Manager Console
  • Akana Policy Manager Services—this feature bundle includes the Akana Scheduled Jobs feature which adds jobs to the Quartz scheduler. It also includes Akana Security Services. This feature is needed on all containers except Network Director.
  • Akana MongoDB Support (Plug-In) (if using MongoDB for analytics)

Community Manager with Policy Manager and OAuth

Install the following features:

Policy Manager with remote Community Manager

Install the following features:

Standalone Community Manager (developer portal)

Note: The Community Manager developer portal would be for app developers only.

Install the following features:

  • Akana Community Manager APIs

Install the following plug-ins for Community Manager:

  • Akana OAuth Plug-In (must be installed on the Community Manager container if OAuth is installed on a separate container)
  • If you want one of the following optional themes, install the plug-in for it (Hermosa Theme is installed by default as part of the Akana Community Manager feature:
    • Akana Community Manager Bonita Theme
    • Akana Community Manager DevOps Theme (applicable only if you have Lifecycle Manager integration)
    • Akana Community Manager Simple Developer Theme

Standalone Community Manager with OAuth

Install the following features:

Standalone Internal/External Gateway (Network Director) container features (without OAuth)

Install the following feature:

  • Akana Network Director

Install the following plug-in:

  • Akana API Platform ND Extensions Feature (needed on the Network Director container for any installation that includes Community Manager)

Container creation sequence

In terms of the sequence of containers, it's best to start by upgrading one of the Policy Manager containers. This accomplishes the database upgrade as well.

After that point, the sequence of containers really doesn't matter. These upgrade instructions suggest the following sequence once the first container has been updated:

  1. First, any additional containers running Policy Manager and/or the API Platform.
  2. Then, any Network Director or other containers.

However, the sequence is not important after the first container. You could upgrade the Network Director container at any point. There is no dependency; containers that have been upgraded will work with containers that haven't yet been upgraded. You can even upgrade additional containers in parallel.

Just make sure you upgrade an initial Policy Manager container first, with the associated database upgrade, and then follow any logical approach, making sure that each step completes successfully before starting the next one.

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.

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.

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 (Community Manager developer portal help).

Optional Additional Features

The platform installation includes some optional additional features:

  • Admin Monitoring tool: an optional plug-in, this tool provides a way to view the monitored attributes published by different components in the product. This tool is used mainly to monitor thread pools and usage data queues. For more information on this tool, see Using the Admin Monitoring Tool.

    Note: The product also includes the System Health tool (Admin Console for the container > Health tab), which is part of basic installation and also allows you to create your own monitoring dashboard. We recommend using the System Health tool rather than the Admin Monitoring tool. See Monitoring the Health of a Container: Akana System Health Tool.

  • Additional themes: As part of setting up Community Manager you'll need to set up at least one theme. However, you might want to use more than one. For example, you might install Hermosa Theme for the full functionality of the Community Manager developer portal and have a separate Simple Developer theme instance for your app developers to connect to APIs (streamlined UI with app and API functionality but without Site Admin functions).

Installing Repository Client (for the Lifecycle Coordinator or Extended Properties features)

If you will be using the Lifecycle Coordinator or Extended Properties features, it's best to use Repository Client, the standalone, Eclipse-based IDE, to define the library functionality that you will then use in the Community Manager developer portal.

Follow the procedures applicable for your operating system:

  1. Download: To download the Repository Client file
  2. Install: follow the applicable instructions:

To download the Repository Client file

  1. Download the Lifecycle Manager ZIP file. For instructions, see Installing Lifecycle Manager.
  2. Navigate to the /misc/ subfolder and get the Repository Client ZIP file that's correct for your operating system:
    • Windows: RepositoryManagerClient.zip
    • Mac: RepositoryManagerClientMaxOSX.zip
  3. Copy the file to your installation location and unzip it.

To install the Repository Client file: Windows

  1. Run the installer file (RepositoryClientInstall.exe) to install the Repository Client. After running the installer, the installation option will be available in the Akana Administration Console.

You can then finish installing the applicable feature:

To install the Repository Client file: Mac O/S

Repository Client has not been certified to work on Mac machines with non-Intel processors. Some users have successfully installed it, but it has not been tested.

Note: If you already installed the Repository Client file on Mac O/S and have trouble with permissions, follow the steps in this troubleshooting article: Cannot launch Repository Client app after installing on Mac O/S.

  1. After unzipping the downloaded binaries, it is important to change permissions for the Repository Client app file:
    1. Open a terminal and navigate to the directory where the Repository Client app file is unzipped. For example: RepositoryClient_2019.1.30.00000.app.
    2. Run the following:
      chmod -R +x {RepositoryClient app filename}

      For example:

      chmod -R +x RepositoryClient_2019.1.30.00000.app

You can then finish installing the applicable feature:

Troubleshooting

This section includes information to help troubleshoot the installation process if errors occur. It includes:

Error in determining if database is already installed. See log for details

When setting up the database, if you choose a database type that requires a driver, such as MySQL, but you don't put the driver in place, you'll get the following error:

Error in determining if database is already installed. See log for details

To resolve, follow the instructions in Database drivers, for the specific database type/version you're using.

Note: To review the logs, as suggested in the error message, go to the instances\{instancename}\log folder. The log file is named {instancename}.log. For example: pmcm1.log.

Cannot launch Repository Client app after installing on Mac O/S

If you installed the Repository Client on Mac O/S and did not change the permissions for the Repository Client app file, as covered in To install the Repository Client file: Mac O/S above, you might find that you are unable to launch the Repository Client app.

In this scenario, follow the steps below.

  1. From the Terminal, navigate to the install directory for the Repository Client. If you used the default path, this would be:
    /Applications/Repository Client
  2. Under the Contents/Eclipse folder, open the eclipse.ini file to edit it:
    vi /Applications/Repository Client/Repository Client.app/Contents/Eclipse
  3. In the file, after line #11, provide your JAVA_HOME/bin/java path with the -vm argument in the first line, and the location in the second line. For example:
    -vm
    /Library/Java/JavaVirtualMachines/jdk1.8.0_281.jdk/Contents/Home/bin/java

    Note: Be sure to add these two lines before the line containing -vmargs.

  4. Save and close the file.

After following the steps above, you should be able to launch the Repository Client using the .app file.