Explorer

Explorer is a Nuxeo addon that allows to introspect the Nuxeo Runtime Configuration of the live application, export it as a distribution, and import similar distributions for reference and documentation.

The Nuxeo Explorer reference instance is available at explorer.nuxeo.com. It displays reference distributions for all major Nuxeo releases and is referenced in this documentation page. The live Runtime introspection has been disabled on this server.

Installation

This addon requires no specific installation steps. It can be installed like any other package with the nuxeoctl command line:

$ nuxeoctl mp-install platform-explorer

Configuration

The explorer package comes with the following Configuration Templates:

• explorer-sitemode: this will set up an anonymous user and redirect to the Explorer home page when reaching the Nuxeo server.
  This will also disable the possibility of introspecting the live Runtime, by setting the nuxeo.conf environment property org.nuxeo.apidoc.site.mode to true.
  This template is typically useful for a documentation site, similar to explorer.nuxeo.com.

• explorer-virtualadmin: this will setup a virtual administrator for the application, creating an empty user database (if it was not already initialized and/or filled).
  The virtual username is apidocAdmin.
  The default password matches the username, and should be changed thanks to the nuxeo.conf environment property org.nuxeo.apidoc.apidocAdmin.password.

The following configuration properties are available:

• org.nuxeo.apidoc.javadoc.url defaults to https://community.nuxeo.com/api/, this will be taken into account to generate Javadoc links depending on the distribution version, for instance referencing the Nuxeo 10.10 Javadoc for a distribution with version 10.10.

• org.nuxeo.apidoc.apidocmanagers.group defaults to ApidocManagers: users in this group will be able to manage distributions, uploading, updating and exporting persisted distributions in the application. Note that members of this group cannot see the live runtime configuration: only a Nuxeo global administrator can do so.

• org.nuxeo.apidoc.apidocreaders.group defaults to Everyone: users in this group (by default, all users) will be able to view persisted distributions.

These can be customized by overriding the corresponding component configuration, for instance:

<?xml version="1.0"?>
<component name="org.mycompany.myproject.Explorer.contrib">
  <require>org.nuxeo.ecm.core.operation.OperationServiceComponent</require>
  <extension point="configuration" target="org.nuxeo.runtime.ConfigurationService">
    <property name="org.nuxeo.apidoc.apidocmanagers.group">MyProjectAdministrators</property>
  </extension>
</component>

The complete list of contributions can be seen on the explorer itself, on the Explorer package view.

Functional Overview

User Features

The explorer addon allows exporting Nuxeo distributions, snapshotting the "live" Nuxeo server on which the Explorer addon is running.
It provides import and export features, storing distributions as documents in the Nuxeo repository.

Here is a sample home page, taken on the Explorer public instance:

Newest available distributions are presented, as well as legacy LTS (Long Time Support) releases, and serve as documentation for main releases of the Nuxeo Platform.

Explorer distributions present the following items from a live Runtime:

• Bundle Groups are extracted from the Maven configuration of Nuxeo bundles, producing a hierarchy that allows grouping bundles inside sub-categories;

• Bundles are at the heart of the Runtime Framework pluggable system. Bundles are packaged as Java Jars and reference components that should be deployed on the server;

• Components are the pluggable parts allowing to declare services, extension points and contributions;

• Services provide interfaces for business-logics;

• Extension Points provide entry points for the many configurable elements in the application;

• Contributions are configurable elements held by the server;

• Operations are specific contributions to the Nuxeo Automation Framework: this extraction allows to display detailed documentation on these configuration elements;

• Packages are groups of bundles that are installed as Nuxeo plugins on the application.

On each distribution, tab-like navigation offers listings of all of these items, with filtering features:

Here are screenshot details of some sample pages, presenting:

• Documentation on an extension point, also listing its contributions:

• Documentation on a component, linking to its required component and to its contribution:

• Documentation on an operation:

• A summary of all bundles, components, services, extension points and contributions held by a given package:

These pages come with additional references to the online, to the Nuxeo Marketplace, as well as helpers to generate the code needed to override a contribution, or to declare specific operation available inside Nuxeo Studio Registries.

Links to distributions can be resolved thanks to their unique key, but can also be resolved using an aliasing system.
The distribution name, key, version and aliases can be updated on the distribution from the UI. The version only can also be used as an alternative alias.

Some special keywords are used as aliases:

• current is an alias to the live Runtime distribution: it can only be browsed by an administrator.

• adm is also an alias to the live Runtime distribution, but with a simpler-rendering (useful to embed frames inside of administrative pages).

• latest will resolve to the most recent distribution name "Nuxeo Platform", comparing versions. It can also be defined as an explicit alias on distributions, and the same version comparison system will be used when several distributions match.

• latestLTS and latestFT are set according to boolean metadata on a distribution. When checking the checkbox, existing distributions with the same boolean checked will be updated, so that only one distribution is flagged as being the latest.

Export links are also displayed in the UI, on the distribution page as well as on bundles and packages.

Administrator Features

Administrator users can access the management page by clicking on the Manage Distribution button from the home page:

Saving a Distribution

Administrators can snapshot the live Runtime. This will create documents in the repository representing that state.

Complete distributions can be saved, but filtering can also be applied:

Filtering is available on:

• bundles by filling a bundle name (multiple lines can be used for multiple bundle),
• packages by filling a package name (multiple lines can also be used for multiple packages),
• Java packages prefixes: the java package will filter operations depending on their Java implementation package name.

When selecting a bundle, the packages holding it will also be selected. Similarly, when selecting a package, included bundles will be selected. Operations can also be selected if their corresponding component is selected.

The Check As Prefixes checkbox can be used as a wildcard, to make selections on all bundles or packages that start with the given name(s), in order to make "bulk" selections.

The Include References checkbox can be used to include target extension points in the extraction. Their containing component and bundle will also be taken into account, stripped out of unrelated configurations. This option is interesting to extract and list all selected contributions to a given extension point, filtered out of all other contributions to the same extension point.

The same kind of filtering can be applied to the Json REST default API, as well as contributed exporters REST API. Corresponding export links are made available on the home page, the bundle page and the package page, by configuration,

Managing Distributions

Only administrators can snapshot the current live runtime, as the generated export could hold private or sensitive information.

But users who are members of a group named ApidocManagers can also import, export, delete and update distributions.

When saving or uploading a distribution, some metadata can be updated on the distribution. It is also possible to update the distribution later on, to change its name, define aliases, etc:

When set as hidden, the distribution can still be accessed with a direct link, but is not listed anymore on the home page.

From this administration page, a ZIP export can be downloaded for all persisted distributions: this is actually a standard Nuxeo XML export of the hierarchy of distribution-related documents. The same ZIP can be imported again on another Nuxeo server where the Explorer addon is also installed.

Technical Overview

The distribution snapshot is done by querying the following services:

• the ComponentManager service, in charge of the runtime deployment,
• the PackageManager service, in charge of packages installation,
• the AutomationService service, in charge of operations and chains registration.

All Nuxeo artifacts that are extracted follow a dedicated interface, and accept two implementations: one consisting of a simple POJO class to represent a "live" state, and another acting as a Nuxeo document adapter to represent a persisted state.

README files held by bundle jars are also extracted for additional documentation, as well as <documentation> tags extracted from components XML configurations.

Configurations that are introspected can sometimes hold sensitive information (like password or tokens). To avoid exposing such information, the content is filtered and can be configured in case some additional tags should be added. Here is a sample component to override the default values:

<component name="org.nuxeo.apidoc.snapshot.SnapshotManagerComponent.override">
  <require>org.nuxeo.apidoc.snapshot.SnapshotManagerComponent</require>
  <extension target="org.nuxeo.runtime.ConfigurationService" point="configuration">
    <property name="org.nuxeo.apidoc.secure.xml.keywords">
      password, Password, secret, apiKey, TMPDIR, TMP, TEMP, TEMPDIR
    </property>
    <property name="org.nuxeo.apidoc.secure.xml.keywords.whitelisted">
      passwordField, passwordHashAlgorithm
    </property>
  </extension>
</component>

The Explorer addon comes with two extension points for customizations:

• plugins can be contributed to extract more information than what the default implementation provides, display it, and export it. This can be useful to document any other new artifact, similarly to operations extraction, for instance, in a pluggable way.

• exporters can also be contributed to generate custom exports of various kinds. Some default contributions are provided with the default implementation, and can be taken as examples. This allows defining custom REST API to export the distribution information, defining custom filtering or using a custom format (Json or not).

Since installing the Explorer addon is not necessarily something that you would like to do on your application, it is also possible to automate its deployment on a development instance, add the Explorer addon on it, and perform an export, in a CI pipeline. Reference platform exports are pushed to the public Nuxeo Explorer instance automatically at each release by using such an automated pipeline.