Community Manager Tenant Installation Jython Script

Provides reference information and examples relating to the installation Jython script used to create a tenant—an instance of the Akana API Platform Community Manager developer portal.

Table of Contents

• Jython Script Elements
  • Required Jython script elements
  • Optional Jython script elements
• Using theme and themeImpl to specify a theme
• Extending a platform theme
• Installation script examples
  • Calling the script: Windows
  • Calling the script: Unix
  • Script elements (same for all)
  • Script example: Windows
  • Script example: Unix
• Secure Installation

Jython Script Elements

The various Jython script elements allow you to specify tenant configuration values, to tailor the installation to your requirements. Some of the elements determine the look and feel of the resulting installation. Review the available options before writing your tenant Jython script:

• Required Jython script elements
• Optional Jython script elements

Required Jython script elements

Required script elements are given below, with an explanation of each.

--url

The URL for the container that the Akana Community Manager APIs feature is installed on. Can be a container URL or load balancer URL. The URL is normally structured along these lines: {protocol}://{hostname}:{port}

Example: http://server-10.acmepaymentscorp.com:9901

For a more detailed example, see URL values in the Jython script elements: example below.

There is normally no context unless the product is running in an application server.

--tenantName

A friendly name for the tenant, for use in certain scenarios such as email messages.

Example: Acme

Note: The tenantName value can be changed, later, from the Community Manager developer portal.

--tenantId

The internal ID of the tenant. When choosing the TenantID, it's best to choose an ID that's as short as possible, since it's used in many other IDs (such as AppID, APIID), in URLs, and in message payload content. It cannot have spaces or special characters, and should be lowercase. Keep it simple. The tenantID is normally the lowercase version of the tenant name above (without spaces); for example, acmepaymentscorp. It will appear in all object IDs and the URLs in the system.

Notes:

• Once the tenant is created, the tenantId value cannot be changed.
• If you are using multiple environments, and might be using import/export or promotion of data between environments, the value for tenantid must be the same for all environments.

--address

The base URL of the tenant. The hostname must be unique. There is normally no context unless the product is running in an application server.

This is the default address from which the tenant is accessed. Multiple additional virtual hostnames are allowed, but the hostname provided in this element is the primary hostname.

This value is used in certain notifications that provide a URL for accessing the tenant; for example, the signup confirmation email.

Example: http://acmepaymentscorp.com

For a more detailed example, see URL values in the Jython script elements: examples below.

Note: Hostnames in the Jython script must be lowercase.

--consoleAddress

The same as the --address element, but includes the context in which the Community Manager developer portal is running, if a context is specified. Context could be a value, such as apiportal, or could just be root (/). This is the address of the Community Manager developer portal—the full URL that will be used in the browser when accessing the Community Manager developer portal user interface. The browser then redirects to the default login page.

Example: http://acmepaymentscorp.com/apiportal or http://acmepaymentscorp.com.

For a more detailed example, see URL values in the Jython script elements: examples below.

Note: Hostnames in the Jython script must be lowercase.

Note: This parameter corresponds to the atmosphere.context.root settings in the underlying Administration Console. See com.soa.atmosphere.console (Community Manager developer portal Site Admin doc). There are certain values that are reserved for other uses. They include: /portal, /api. If you're choosing a custom value for this setting, do not use these values.

--username

Username for authorized user. Needed, along with the userpassword element, for the BasicAuth security required for adding a tenant.

Example: johnsmith

--userpassword

Password for authorized user. Needed, along with the username element, for the BasicAuth security required for adding a tenant.

Example: securepassword_976

Optional Jython script elements

Optional script elements are given below, with an explanation of each.

--contactEmailAddress

The email address that users should contact for help with any issues in the tenant. This address is used in some links in tenant pages—for example, in the footer template for pages on the Community Manager developer portal.

--email

The email address for the default tenant administrator.

From version 8.1 onwards, you can add multiple email addresses, as a comma-separated list. Each administrator created via the script has both SiteAdmin and BusinessAdmin roles.

Note: If you don't include this parameter, the following default value is assigned: administrator@{tenantid}.

--esIndexName

Optional: the name of the Elasticsearch index. This is only needed if you're using some advanced options in a larger deployment, to have a separate, independent Elasticsearch index for each tenant. By default, an index with the name default is used. If this parameter is not included, the default index is used for the tenant.

Generally, this parameter is only applicable to a very large installation with multiple tenants.

--fromEmailAddress

The email address that is displayed in the "From" field for email notifications sent out by the platform.

--password

The password for the default tenant administrator.

If you specify a password, and include multiple email addresses, all tenant administrators will have the same password for first login.

If password is not specified, the platform generates a random password, unique to each user. The password is sent to the specified email address in the initial email notification.

Users must change the password on first login.

--theme

A value that determines which of the available themes is used for the Community Manager developer portal user interface.

Possible values depend on the product version you're using. In addition, for some themes, themeimpl is also needed (see below). For information about the values to specify, see Using theme and themeImpl to specify a theme below.

--themeImpl

A property that works with theme to support the ability to extend Community Manager developer portal user interface themes, so that you can have multiple instances of one theme with separate customization for each. However, extending themes is most easily accomplished via the Community Manager developer portal user interface. See How do I extend a platform theme? (Community Manager developer portal help).

For information about the values to specify, see Using theme and themeImpl to specify a theme below.

--virtualHosts

A comma-separated list of host names that the portal can be accessed from. For example:

--virtualHosts server-10.acmepaymentscorp.com,acmepaymentscorp.com

For a more detailed example, see URL values in the Jython script elements: examples below.

Note: Hostnames in the Jython script must be lowercase.

--ignoreCerts

An optional parameter you can use if you want to ignore SSL certs when creating the tenant. Defaults to False; if you include this parameter with value True (case sensitive), the platform accepts all certs when calling an HTTPS endpoint to create a new tenant.

URL values in the Jython script elements: examples

• Example #1 (with virtual hosts)
• Example #2 (simple example)

Example #1 (with virtual hosts)

Let's say for example you create a container on http://server-10.acmepaymentscorp.com:9901, and install the Akana Community Manager APIs feature. You might choose to have the Akana Administration Console on a different port, for security reasons, so the URL might be http://server-10.acmepaymentscorp.com:9005/admin.

In this example, the values for the Jython script elements might be as shown below.

Jython script element...	Possible value...
--url	http://server-10.acmepaymentscorp.com:9901
--address	http://acmepaymentscorp.com
--consoleAddress	http://acmepaymentscorp.com/apiportal
--virtualHosts	server-10.acmepaymentscorp.com,acmepaymentscorp.com

Example #2 (simple example)

A very simple example might not use load balancing or virtual hosts. For example:

• --url http://localhost:9000
• --address http://localhost:9000
• --consoleAddress http://localhost:9000/enterpriseapi

In this example, --virtualHosts is not needed.

Using theme and themeImpl to specify a theme

To install the first platform theme, use the values below to specify which theme you want.

Note: You might also need to install the plug-in for the theme you want to use, as part of the installation process. Refer to the installation doc for your version: go to Installing the Akana API Platform and open the installation instructions file.

To install this theme...	Use this theme parameter value...	Use this themeImpl parameter value...	Valid in these versions...
Bonita Theme	bonita	simpledev	2020.1.0 and later
Default Theme	default	None needed	Versions earlier than 2020.2.0. Deprecated in 2020.1.0, removed in 2020.2.0
Dev Ops Theme	devops	None needed	All
Hermosa Theme	hermosa	default	All
Simple Dev Theme	simpledev	None needed	Versions earlier than 2020.2.0. Deprecated in 2020.2.0.

For more information, see Extending a platform theme below.

Extending a platform theme

You can have multiple versions of a single platform theme by extending the theme. When you extend the theme, you essentially create one or more additional, custom themes, each with a different name. The steps are:

1. Defining the custom theme.
2. Specifying the standard theme that it's based on.
3. Modifying the custom theme.

Each instance has its own URL (virtual host) and can be separately customized, but they all use the same code base and database. This allows you to provide a different user experience to different user groups.

The platform supports extending of all themes.

You can also extend themes via the Community Manager developer portal user interface: Administration > Site > Add Theme, and choose the Custom Theme option.

Extending Hermosa theme is also supported. For instructions, see How do I extend a platform theme? (Community Manager developer portal help).

Installation script examples

From the /bin folder of your installation, run the applicable Jython script below, using appropriate values for your installation. For definitions, refer to the sections above. Choose the section for your operating system:

• Calling the script: Windows
• Calling the script: Unix
• Script elements (same for all)
• Script example: Windows
• Script example: Unix

Calling the script: Windows

For Windows the first part of calling the script is shown below. For information on the script parameters, see Script elements (same for all).

Jython.bat ../scripts/Lib/soa/atmosphere/tenant.py -a -v

Calling the script: Unix

For Unix the first part of calling the script is shown below. For information on the script parameters, see Script elements (same for all).

/jython.sh../scripts/Lib/soa/atmosphere/tenant.py -a -v

Script elements (same for all)

After the first part of the script, list the script elements and their values. Script elements are shown below.

Line breaks have been added for display purposes. Remove line breaks when copying and pasting.

--url {url} 
--tenantName {tenantName} 
--tenantId {tenantId} 
--address {tenantAddress} 
--consoleAddress {consoleAddress} 
--theme {theme} 
--themeImpl {themeImpl} 
--email {default tenant administrator} 
--password {default tenant administrator password} 
--contactEmailAddress {contactEmailAddress} 
--fromEmailAddress {fromEmailAddress} 
--virtualHosts {virtualHosts} 
--username {username} 
--userpassword {user password}

Script example: Windows

An example of a script for Windows is shown below.

jython.bat ../scripts/Lib/soa/atmosphere/tenant.py -a -v --url http://server-10.acmepaymentscorp.com:9901 --tenantName EnterpriseAPI --tenantId enterpriseapi --address http://acmepaymentscorp.com --consoleAddress http://enterpriseapi.soa.local:9900/enterpriseapi --theme default --themeImpl {default} --email administrator@acmepaymentscorp.com --password Admin_Password --contactEmailAddress yourname@acmepaymentscorp.com --fromEmailAddress yourname@acmepaymentscorp.com --virtualHosts server-10.acmepaymentscorp.com,acmepaymentscorp.com --username janemead --userpassword pwdFk24y1iY3U4dpwd

Script example: Unix

An example of a script for Unix is shown below.

./jython.sh ../scripts/Lib/soa/atmosphere/tenant.py -a -v --url http://server-10.acmepaymentscorp.com:9901 --tenantName EnterpriseAPI --tenantId enterpriseapi --address http://acmepaymentscorp.com --consoleAddress http://enterpriseapi.soa.local:9900/enterpriseapi --theme default --themeImpl default --email administrator@acmepaymentscorp --password Admin_Password --contactEmailAddress yourname@acmepaymentscorp.com --fromEmailAddress yourname@acmepaymentscorp.com --virtualHosts server-10.acmepaymentscorp.com,acmepaymentscorp.com --username janemead --userpassword pwdFk24y1iY3U4dpwd

Secure Installation: Steps before Running Jython Scripts

If you will be using HTTPS URLs for your Akana API Platform installation, there are some additional steps you must perform before running the Jython script. If these setup steps are not in place, the Jython script will fail.

The Jython installation script invokes a REST API call on the API Platform. If the API Platform container is configured with HTTPS, the Jython script must use a keystore with a trusted certificate; otherwise, it will not be able to connect to the API Platform.

If the certificate is a default trusted certificate issued by one of the trusted CAs already recognized by the JRE, no extra steps are needed. However, if the API Platform container is configured with HTTPS, you'll need to add the issuer to the certificate file before running the Jython script if your API Platform SSL certificate meets any of these conditions:

• The certificate is self-signed.
• The certificate is generated by the Akana platform's internal CA.
• The certificate is generated by a non-commercial issuer.

Setting up security for an Akana API Platform tenant with HTTPS URLs

To add the issuer to the certificate file, you must get the certificate issuer of the container, set the path, and then set the Jython ops command. You can then run the Jython script. Follow the steps below.

To set up security for a CM tenant with HTTPS URLs

1. In Akana Policy Manager, create a keystore with the issuer certificate of API Platform SSL Certificate.

   You could use a tool such as the Java Keytool utility (http://sourceforge.net/projects/keytool) or the Elysian Keytool Advanced GUI (http://sourceforge.net/projects/ssltools) to create the keystore. An example using Keytool is shown below:

   keytool -genkey -alias mydomain -keyalg RSA -keystore keystore.jks -keysize 2048

2. Import the trusted certificate into the keystore. Substitute the correct values for filename, file location, keystore name, and keystore location. An example is shown below.

   keytool -importcert -v -trustcacerts -alias atmo -file C:/akana/CA.cer -keystore c:/akana/keystore.jks -storepass password -storetype JKS

   Once this step is complete, the keystore is ready with the API Platform SSL certificate.

   Note: As an alternative to the above step, which uses the default cacerts keystore and adds the new certificate issuer, you could create a blank cacerts file with just this issuer, the API Platform certificate issuer. If you take this approach you would still have to follow Step 3 below, and then run the Jython script.

3. In the bin folder for your installation, at the command line, execute the following command, substituting the keystore path and filename:

   set JYTHON_OPTS="-Djavax.net.ssl.trustStore={keystore_path_and_filename}"

   An example is shown below.

   set JYTHON_OPTS="-Djavax.net.ssl.trustStore=C:/testdata/mykeystore.jks"

4. Run the Jython script with the values for your installation. For examples, see:
   • Windows: Script example: Windows
   • Unix: Script example: Unix

If you are not sure how to do SSL configuration for your listener, follow the instructions below.

Configure HTTPS listener when using the Akana Platform internal Certificate Authority

To configure the HTTPS listener, there are three basic steps:

1. Step 1: In Policy Manager, configure the Certificate Authority
2. Step 2: Add HTTPS listener to CM container
3. Step 3: Manage PKI Keys for HTTPS Listener

Step 1: In Policy Manager, configure the Certificate Authority

The first step is to configure the Certificate Authority.

To configure the CA in Policy Manager

1. In Policy Manager, go to Configure, then Security, then Certificates, then Certificate Authority.
2. Click Configure Certificate Authority.
3. At the Select Certificate Configuration Option page, click Generate X.509 CA Certificate and PKI Keys.
4. At the Generate CA Certificate and PKI Keys page, provide values and then click Finish.
5. At the summary page, click Export CA Certificate. Save it to a location on your local filesystem.

Step 2: Add HTTPS listener to CM container

Next, add an HTTPS listener to the container.

To add an HTTPS listener to the CM container

1. In the Akana Policy Manager Workbench, go to Akana API Platform, then Containers, then CM Container, then Details, then Inbound Listeners.
2. Click Add Container Listener.
3. At the Select Container Listener Type page, select HTTPS and click Next.
4. Provide values for the listener: Name and Description, Bind to all interfaces checkbox, Host Name, Port Number, Content Path, and thread pool details.
5. Click Finish. The HTTPS listener is added.

Step 3: Manage PKI Keys for HTTPS Listener

Your subject DN must match with the CA, and the HTTPS listener certificate must use the same hostname that you are using, otherwise the Jython script will fail.

Follow the steps below.

To manage PKI keys for the HTTPS Listener

1. In the Policy Manager Organization Tree, under API Platform, Containers, CM Container, Details, choose Inbound Listeners.
2. From the Actions drop-down menu, click Manage PKI Keys.
3. In the Select Key Management Options page, under Key Management Options, choose Generate PKI Keys and X.509 Certificate. Click Next.
4. In the Generate PKI Keys and X.509 Certificate page, provide the same details you set up for the Certificate Authority's Subject DN (see To configure the CA in Policy Manager).
5. Click Finish.
6. In the summary page, in the Certificate Details section, verify that the values for Subject DN and Issuer DN match.

Related Topics