Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Apache Felix Web Console

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:

    Felix Login

    The default credentials are as follows:
    User Name Password
    admin 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:
    password="Your_Password"
username="Your_Username"
    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 in to 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.

Configuration Description Associated Config File
authClientHost

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

 authClientHost.cfg
authTrustHeader

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

 authTrustHeader.config
authClientTrustHeader Defines the OAuth2 endpoint trust header. For more information on OAuth2 endpoint trust headers, see Cortex Authentication authClientTrustHeader.config
itemsRolePermissions* 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 itemsRolePermissions.config
Recommendations Page Size Managed Service 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. recommendationsPageSize.config
RelOS Executor Service Offers a shared Executor Service that can be used to submit tasks for concurrent processing.
RelOs Request Cache Utilizes a request scoped cache to share READ operation results within one request, notably zoom calls.
RelOS System Ready State 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. systemReadyState.config
roleHierarchy Defines the role hierarchy used in Cortex authorizations. For more information on roles and permissions, see Cortex Authorization. roleHierarchy.config
tokenExpiry Defines the authentication token's expiry time, in seconds. tokenExpiry.config
Note: Listed Properties

The table only lists the configurations applicable to Cortex. For more information on Felix configurations, see https://felix.apache.org/documentation/subprojects/apache-felix-web-cons...

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:

Bundle State Description
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:

Table 1.
Component State Description
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.