Installation Jython Script

This document provides reference information and examples relating to the installation Jython script used to create an instance of the Akana API Platform developer portal (tenant).

It includes:

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. Script elements are explained below.

Required Jython Script Elements

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

--url
The hostname for the container that the developer portal is running on. The URL is normally structured along these lines: {protocol}://{hostname}:{port}
Example: http://server-10.acmepaymentscorp.com
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 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, URLs, and 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.
Note: Once the tenant is created, the tenantId value cannot be changed.
--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:9901
--consoleAddress
The same as the --address element, but includes the context in which the developer portal is running, if a context is specified. Context could be a value, such as acmepaymentscorp, or could just be root (/). This is the address of the developer portal; the full URL that will be used in the browser when accessing the developer portal user interface. The browser then redirects to the default login page.
Examples: http://acmepaymentscorp:9901/acmepaymentscorp, http://acmepaymentscorp:9901/.
--username (Version 8.3 and later)
Username for authorized user. Needed, along with the userpassword element, for the BasicAuth security required for adding a tenant.
Example: johnsmith
--userpassword (Version 8.3 and later)
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 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 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 developer portal user interface.
You can specify a custom theme name; the theme is determined by the value in the themeImpl script element. You can use these two elements together to extend a platform theme, so that you can have multiple instances of the same theme, each with different customizations. themes, since you can have multiple custom names. For more information, see Using theme and themeImpl to specify a theme and Cloning a platform theme.
--themeImpl
An element that works with the theme element to support the ability to extend developer portal user interface themes, so that you can have multiple instances of one theme with separate customization for each.
There are three possible values: default, simpledev, and hermosa.
Extending themes is most easily accomplished via the developer portal user interface from version 8.5 onwards; see see How do I extend a platform theme? (developer portal help).
 
For examples and other information about how the theme and themeImpl elements are used together to support creating multiple instances of the same theme, see Using theme and themeImpl to specify a theme and Extending a platform theme.
--virtualHosts
A comma-separated list of host names that the portal can be accessed from. For example:
--virtualHosts open.acmepaymentscorp.com,open.example.com
--ignoreCerts
(Version 8.4.4 and later) 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 code will accept all certs when calling an HTTPS endpoint to create a new tenant.

Back to top

Using theme and themeImpl to specify a theme

If you want to install only one platform theme, use the values below to specify which theme you want.

Note: You must also install the plug-in for the theme you want to use, as part of the installation process. See Community Manager Container Plug-ins (version 8.4).

To install this theme... Use this theme parameter value... use this themeImpl parameter value...
Default Theme {any_name} default
Hermosa Theme hermosa default
Simple Developer Theme {any_name} simpledev

Back to top

Extending a platform theme

You can have multiple versions of a single platform themes 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 three themes: default theme, simple dev, and hermosa.

In earlier versions of the developer portal, extending of themes had to be done via the Jython script. However, from version 8.4 onwards, you can extend themes via the developer portal user interface; Administration > Site > Add Theme, and choose the Custom Theme option.

Cloning of Hermosa theme is supported from version 8.5 onwards.

For instructions, see How do I extend a platform theme? (developer portal help).

Back to top

Installation scripts with 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 tables above.

Windows

Script:

Jython.bat ../scripts/Lib/soa/atmosphere/tenant.py -a -v --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} 

Example:

jython.bat ../scripts/Lib/soa/atmosphere/tenant.py -a -v --url http://enterprise.soa.local:9900 
--tenantName EnterpriseAPI --tenantId enterpriseapi --address http://enterpriseapi.soa.local:9900 
--consoleAddress http://enterpriseapi.soa.local:9900/enterpriseapi --theme default --themeImpl {default} 
--email administrator@{yoursite}.com --password password 
--contactEmailAddress yourname@acmepaymentscorp.com 
--fromEmailAddress yourname@acmepaymentscorp.com 

UNIX

Script:

/jython.sh../scripts/Lib/soa/atmosphere/tenant.py -a -v --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}

Example:

./jython.sh ../scripts/Lib/soa/atmosphere/tenant.py -a -v --url http:// enterpriseapi.soa.local:9900 
--tenantName EnterpriseAPI --tenantId enterpriseapi --address http://enterpriseapi.soa.local:9900 
--consoleAddress http://enterpriseapi.soa.local:9900/enterpriseapi --theme default --themeImpl default 
--email administrator@{yoursite}.com --password password 
--contactEmailAddress yourname@acmepaymentscorp.com 
--fromEmailAddress yourname@acmepaymentscorp.com

Back to top

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. An example is shown below. Substitute values such as filename and location and keystore name and location.
    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.

    Windows:

    jython.bat ../scripts/Lib/soa/atmosphere/tenant.py -a -v --url https://enterprise.soa.local:9443 
    --tenantName EnterpriseAPI--tenantId enterpriseapi --address https://enterpriseapi.soa.local:9443 
    --consoleAddress https://enterpriseapi.soa.local:9443/enterpriseapi --theme default 
    --email administrator@{yoursite}.com --password password 
    --contactEmailAddress yourname@acmepaymentscorp.com 
    --fromEmailAddress yourname@acmepaymentscorp.com

    UNIX:

    ./jython.sh ../scripts/Lib/soa/atmosphere/tenant.py -a -v --url https:// enterpriseapi.soa.local:9443 
    --tenantName EnterpriseAPI --tenantId enterpriseapi--address https://enterpriseapi.soa.local:9443 
    --consoleAddress https://enterpriseapi.soa.local:9443/enterpriseapi --theme default 
    --email administrator@{yoursite}.com --password password 
    --contactEmailAddress yourname@acmepaymentscorp.com 
    --fromEmailAddress yourname@acmepaymentscorp.com 

    An example is shown below.

    jython ../scripts/Lib/soa/atmosphere/tenant.py -a -v --url https://acmepaymentscorp.com:9443 
    --tenantName admin@acmepaymentscorp --tenantId admin@acmepaymentscorp 
    --address https://acmepaymentscorp.com:9443 
    --consoleAddress https://acmepaymentscorp.com:9443/atmosphere 
    --theme default --contactEmailAddress admin@acmepaymentscorp.com 
    --fromEmailAddress admin@acmepaymentscorp.com --virtualHosts acmepaymentscorp.com

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, Step 3).
  5. Click Finish.
  6. In the summary page, in the Certificate Details section, verify that the values for Subject DN and Issuer DN match.

back to top