Configuring Cortex Using Apache Felix Web Console

The Apache Felix Web Console is a tool for managing the Cortex OSGi framework. The Apache Felix Web Console comes bundled with Cortex out of the box, and is started when the Cortex runtime starts.

Using Felix, you can inspect your OSGi framework, start/stop bundles, view logging details, and modify run-time configuration settings.

Logging in to Apache Felix

1. Navigate to http://[server]:[port]/system/console/configMgr.

   If Cortex is running locally at port 8080, the URL is http://localhost:8080/cortex/system/console/configMgr.

2. Enter the User Name and Password in the Authentication dialog box:

   

   The default credentials are as follows:

   • Username: admin
   • Password: admin

Configuring Felix Security Credentials

To configure the username and password for the Apache Felix Web Console:

1. In your etc/ep/cortex/resources/config/permissions directory, create a file named org.apache.felix.webconsole.internal.servlet.OsgiManager.config

2. With a text editor, open org.apache.felix.webconsole.internal.servlet.OsgiManager.config and insert the following properties:

   username="Your_Username"
   password="Your_Password"
   

   Where Your_Username and Your_Password are your Apache Felix Web Console log in credentials.

3. Click Save.

Your new credentials take effect immediately.

Editing Cortex Felix Configuration Files

The Apache Felix Web Console edits the configurations files available in your Cortex configuration directory. If the property configuration file does not exist in this directory, it will not be editable through Felix. For more information on property configuration files, see Cortex Configuration Files.

To modify a configuration file through Felix:

1. Log into Apache Felix.

2. In the menu bar, select OSGi and then click Configuration.

3. Click the property, modify it as required, and click Save to write the update value(s) to the associated property file.

   

Listed Properties

The configurations listed below are applicable to Cortex only. For more information on Felix Web Console configurations.

authClientHost

Associated config file: authClientHost.cfg

Defines the URI for the Cortex authentication endpoint. For more information on authentication endpoints, see Cortex Authentication.

authTrustHeader

Associated config file: authTrustHeader.config

Defines the authentication endpoint trust header. For more information on endpoint trust headers, see Cortex Authentication.

authClientTrustHeader

Associated config file: authClientTrustHeader.config

Defines the OAuth2 endpoint trust header. For more information on OAuth2 endpoint trust headers, see Cortex Authentication.

itemsRolePermissions*

Associated config file: itemsRolePermissions.config

Defines the role permissions for a given resource. In this case, the example shown in the items resource. For more information on roles and permissions, see Cortex Authorization.

Recommended Page Size Managed Service

Associated config file: recommendationsPageSize.config

Defines the pagination page-size setting for recommendations. Since a large number of items may be available for recommendations, this page-size setting can limit the number of items retrieved per request.

RelOS Executor Service

Associated config file: relosExecutorService.config

Defines thread pool size and thread idle timeout in seconds for the RelOS Executor Service. By default, the thread pool size is 500 and the thread idle timeout is 120 seconds.

RelOS OperationResultCache

Associated config file: relosOperationResultCache.config

Defines maximum number of results in cache for the RelOs OperationResult Cache and the eviction timeout in seconds. By default, the maximum number of results in cache is 2000 and the eviction timeout is 60 seconds.

RelOS Request Cache

Utilizes a request scoped cache to share READ operation results within one request, notably zoom calls.

RelOS System Ready State

Associated config file: systemReadyState.config

Defines the number of resource bundles required to register their veto before Cortex is in a ready state. Before a quorum is reached, Cortex returns a 503 Service Unavailable HTTP status for any request.

roleHierarchy

Associated config file: roleHierarchy.config

Defines the role hierarchy used in Cortex authorizations. For more information on roles and permissions, see Cortex Authorization.

tokenExpiry

Associated config file: tokenExpiry.config

Defines the authentication token’s expiry time, in seconds.

Debugging Cortex Using the Apache Felix Console

The Apache Felix Web Console provides developers with information on installed bundles. This can be used to debug bundle startup problems when creating and extending Cortex resources.

Three sections of the console are particularly useful:

• Bundles
• Components
• Registered Helix Handlers

Bundles

The Felix Web Console Bundles page can be used to address whether or not you’ve registered your bundles correctly with the Cortex Runtime. You can find the Bundles page at http:[server]:[port]/cortex/system/console/bundles. If Cortex is running locally at port 8080, the URL is http://localhost:8080/cortex/system/console/bundles.

You can install and start (hot deploy) new bundles and stop running bundles from the Bundles page.

Before using the Bundles page, ensure that the bundle is found by the Cortex Runtime/OSGi. If it is not found, it will not appear in the list.

Bundle Statuses

The Apache Felix Web Console lists bundles in four states:

• Installed: The OSGi runtime is aware of the bundle, but the bundle’s dependencies have not been resolved
• Resolved: The bundle’s dependencies have been resolved, but the bundle has not yet started
• Active: The bundle’s dependencies have been resolved, and it is running in the OSGi runtime
• Fragment: The bundle has been loaded into the OSGi runtime as an OSGi fragment. Its host bundles may or may not have been loaded correctly

Installing and Starting Bundles From the Felix Web Console

The Bundle page’s the Install/Update tool allows you to hot deploy a new bundle without restarting the Cortex Runtime.

To deploy a new bundle, on the Apache Felix Console’s Bundles page:

1. Click Install/Update.

2. Select the .jar file for the bundle you wish to start (typically in the cortex/resource-api/ or cortex/resources/ subdirectories in the target directory of the resource).

3. Check the Refresh Packages check box to initiate bundle rewiring.

   

Installing and Starting Bundles From the Command Line

You can use the following command to deploy bundles:

mvn clean install -Pfelix-deploy

Debugging Bundles

The Bundles page of the Apache Felix Web Console lists all bundles as well as a state. Properly loaded bundles are listed in the Active or Fragment states. If your bundle is not in either of these states, it did not start up correctly.

To investigate a bundle’s status further, click the bundle’s row in the table. This shows a detailed status for the bundle. In particular, the Import-Package section lists which bundles cannot be resolved and may assist in understanding why a package didn’t register correctly.

Components

In the Apache Felix Web Console, a Component refers to an OSGi service. The Components page of the Apache Felix Console shows all components (OSGi services) in the system, as well as their status.

You can find the Components page at http:[server]:[port]/cortex/system/console/components. If Cortex is running locally at port 8080, the URL is http://localhost:8080/cortex/system/console/components.

Components have a different lifecyle from bundles. A bundle can be active even though it’s associated components are not. In a healthy system all components should be in the Active or Satisfied states. If a component isn’t in these states, one of its dependencies may not have started correctly.

Component States

The Apache Felix Web Console lists components in four states:

• Active: The component’s dependencies have been resolved, and it is running in the OSGi runtime
• Disabled: The component’s has been manually disabled in the Apache Felix Console
• Satisfied: The component’s dependencies have been resolved, but it has not yet been called by the OSGi runtime
• Unsatisfied: The component’s dependencies have not been resolved, and the component is not running

Registered Helix Handlers

The Registered Helix Handlers page of the Apache Felix Console shows the ResourceIdentifiers registered with the Helix runtime.

This page lists all registered ResourceIdentifiers, any operations that are associated with the identifier, the identifier’s associated scope, and its the associated Bundle. It also shows which HTTP operation the prototype is registered against.

If you are unable to access your new resource after deployment, check this page, and ensure that the identifier and bundle are listed.