Setting up Platform Assets

In this procedure you will create a local directory structure and use Jinni to create a setup for further platform asset development.

For information on handling artifact bias, see Handling Artifacts with .pc_bias.

Installing Jinni

Jinni is an application used to set up Tribefire by evaluating platform setup requests. You can pass service requests to Jinni with the command line or using a JSON file. Jinni is necessary to work with platform assets.

Note that Jinni uses Maven to resolve dependencies, so configuring your Maven settings correctly is necessary for Jinni to work.

To set up Jinni:

1. Configure Apache Maven as described below.
   1. Navigate to https://maven.apache.org/download.cgi/, download, and install Maven 3.5.2 or later.
   2. Make sure that the PATH system environment variable is set to the root directory of your Maven installation (one containing the bin folder). You can check it by opening a command prompt and running the mvn --version command.
   3. Add the following system environment variables (we're using them later in the provided Maven settings file):

   Name	Value
   MYPROJECT_LOCAL_REPOSITORY	Path to your local Maven repository
   MYPROJECT_TRIBEFIRE_REPOSITORY_USER	Your user name on the remote Tribefire repository
   MYPROJECT_TRIBEFIRE_REPOSITORY_PASSWORD	Your password on the remote Tribefire repository
   MYPROJECT_TRIBEFIRE_REPOSITORY_NAME	The name of a repository you want to download dependencies from, typically core-stable. For more information, see the section below.
   MYPROJECT_DISTRIBUTION_REPOSITORY_USER	Your user name on the remote distribution repository (one where you would save your Tribefire artifacts, for example your company's remote repository). If you don't have access to such repository, ignore this variable.
   MYPROJECT_DISTRIBUTION_REPOSITORY_PASSWORD	Password to the remote distribution repository
   MYPROJECT_DISTRIBUTION_REPOSITORY_NAME	Name of the remote distribution repository where you will save your Tribefire artifacts. If you don't have access to such repository, you'll need to modify the settings.xml template to point to a local folder instead (explained below). In any case, you need to add this repository in Control Center/CortexConfiguration once Tribefire is installed, so that Tribefire knows where to save your artifacts.

   Note that the MYPROJECT part of the variable is a placeholder used to describe the project/company you work for, for example: ACME_LOCAL_REPOSITORY or PROJECTX_TRIBEFIRE_REPOSITORY_USER. Variable names do not matter as long as you are consistently using them in settings.xml.

   4. Make sure you have the correct configuration in your .m2/settings.xml file:

      If you have no access to a distribution repository, you need to replace it in the setting.xml file with a local remote repository. You can use the snippet below:

      <repository>
      		<id>localRemoteRepository</id>
      		<layout>default</layout>
      		<url>LOCAL_FOLDER_PATH</url>
      		<snapshots>
      			<enabled>false</enabled>
      		</snapshots>
      		<releases>
      			<enabled>true</enabled>
      			<updatePolicy>always</updatePolicy>
      		</releases>
      	</repository>
      

      You can download the settings.xml template here.

      Make sure to provide the correct values for localRepository, localRemoteRepository, username, and password.

2. Download the Jinni package. For information on where do download Tribefire components from, see below.

   Follow the links below to download latest tribefire core components, selected cartridges and related tools.

   Jinni

   Jinni is a CLI tool provided by Braintribe, enabling you to install Tribefire on a local Tomcat host. You can download the Jinni Package here (authentication required).

   The list below provides Maven setup dependencies for each asset. You can directly copy these into the --setupDependency part of your Jinni command, as in --setupDependency groupId:artifactId.

   Available Assets

   Asset	Download Link	Jinni --setupDependency
   Tribefire client dependencies	tribefire-client-default-deps	Dependencies required to communicate with tribefire-services through the Java API.
   tribefire Modeler	tribefire-modeler	tribefire.cortex.modeler:tribefire-modeler#2.0
   Enablement Cartridges Setups	tribefire-demo-cartridge tribefire-simple-cartridge	tribefire.extension.demo:tribefire-demo-setup#2.0 tribefire.extension.simple:simple-cartridge-setup#2.0
   Enablement Cartridges Source code	Enablement Maven Artifacts	Download the zip-file with the latest version
   Product Cartridges	tribefire-ldap-cartridge tribefire-shiro-cartridge swagger-model-import-cartridge	tribefire.extension.ldap:ldap-setup#2.0 tribefire.extension.shiro:shiro-setup#2.0 tribefire.extension.swagger:swagger-model-import-setup#2.0
   Aggregators	tribefire-standard-aggregator	tribefire.cortex.assets:tribefire-standard-aggregator#2.0
   Plugins	jdbcplugins	Check on individual plugins

3. Unzip the downloaded archive to a location of your choice (e.g. /development/jinni).
4. Add jinni's bin folder (e.g. /development/jinni/bin) to the PATH variable of your operating system.

Preparing a Local Environment

We recommend you create a single tf-setups directory where you will keep all your assets. The structure we propose allows you to easily identify and separate different setups. Furthermore, the information in the this setup can be used by Jinni to deduce information from the current working directory instead of getting it explicitly from CLI parameters.

You only create the tf-setups folder. The other folders are created automatically by Jinni.

• tf-setups
  • some-group.project-x-asset#1.0
    • package
    • installation
      • conf
      • storage
      • plugins
      • runtime
  • some-group.project-y-asset#1.0
    • package
    • installation
      • conf
      • storage
      • plugins
      • runtime

Creating a New Platform Asset Project

In this example, you will create a project called my-project with a major-minor version 1.0 which is in the group tutorial.

To create a new platform asset project:

1. Open the terminal and execute the following command:

   jinni create-project qualifiedName=tutorial:my-project#1.0 dependencies=tribefire.cortex.assets:tribefire-standard-aggregator#2.0
   

   The result of this operation is a newly created asset artifact tutorial:my-project#1.0.1-pc with the AssetAggregator nature having the ranged dependency to the tribefire.cortex.assets:tribefire-standard-aggregator#[2.0,2.1). This artifact is installed into the local Maven repository which is configured via Maven settings. The local Maven repository is sufficient to resolve this new project during a setup, but note that the project is not yet deployed to a shared repository that should be considered as the actual persistence.

2. Navigate to the tf-setups directory and run the following command:

   jinni setup-local-tomcat-platform project=tutorial:my-project#1.0
   

   Running this command results in an executable tribefire installation for on your local port 8080. The qualifiedName of the project is used to create the following directory structure:

   • tf-setups
     • tutorial.my-project#1.0
       • package
       • installation
         • conf
         • storage
         • plugins
         • runtime
           • host
             • bin
               • catalina.bat
               • catalina.sh

3. Navigate to tf-setups/tutorial.my-project#1.0/installation/runtime/host/bin and start tribefire by running the catalina start command. Once it starts, you can open the tribefire services landing page at http://localhost:8080.

Configuring a Platform Asset Repository

You can configure tribefire to work with:

• a local filesystem-based repository (for example file://host/path) without authentication

Note than if you are on a different operating system, the url to a local file looks differently. For example, on iOS, the url to a local file starts with file:///path/to/file.

• a remote HTTP based repository, usually with some form of authentication

Both repositories must be Maven-based. It is best if the <localRemoteRepository> you specified in your settings.xml does not point to the .m2 directory. For more information about setting up Maven, see Quick Installation.

Maven Repository for Deploy Transfer

To configure a platform assets repository:

1. If you haven't already, start tribefire and open Control Center.
2. Navigate to the System -> General -> Cortex Configuration entry point or click the Cortex Configuration icon on the main page of Control Center.
3. Assign a new instance of ArtifactRepository to the artifactRepository property. Make sure to provide the username, password, and url to your Maven-compatible repository.
   • if your url points to your file system, for example: file:/ABSOLUTE-PATH-TO/tf-setups/repository, tribefire will use the provided location as the local repository. In this case, make absolutely sure that the value of the <localRemoteRepository> in your settings.xml is the same as the path you provide in this step.
   • if your url points to a URL, for example: https://repository.yourCompanyName.com/repo/, tribefire will use the provided location as the remote repository
4. Click Apply and commit your changes.

For more information on how to use platform assets, see Working with Platform Assets.

Maven Repository for Install Transfer

For maven install operations the local repository is used. It is configured the standard Maven way: https://maven.apache.org/settings.html

Managing Users

It might be necessary to create new user accounts so that your collaboration is more effective.

To manage users:

1. In the right upper corner of Control Center, click on the cogwheel and select Switch to -> Authentication and Authorization. This opens an access where you can manage user accounts.
2. Create users and assign them appropriate roles, for example a tutorial-user user with the tf-admin role.

   For the information on default user roles, see Security Considerations.

What's Next?

For more information on how to handle local artifacts, see Working with Platform Assets.