Testing and Deploying the UI

The Maven project for the UI contains a package.json configuration file, which specifies the available commands for building and testing the UI.

yarn build

Performs a one-time production-ready build of the UI. Outputs to the build directory.

yarn test

Compiles and executes UI unit tests and continuously watches for source changes to trigger re-testing. Unit tests are located alongside the modules they are testing.

Run this command in a separate terminal window when developing to continuously run unit tests against the code.

yarn profile

Performs a one-time build of the UI, in production mode, with profiling enabled.

Generates a report in the build directory named report.html detailing the structure of the bundles and chunks that are created as part of a production build.

yarn start

Starts the UI in development mode, with automatic rebuilds and reloads enabled.

The start script launches a dedicated Webpack development server to serve the UI during development. For more information, see "To Test UI Pages in a Development Server".

The package.json file also lists the dependencies the UI uses, and the required versions. Dependencies are locked to specific versions, for example, "lodash": "4.1.0" specifies an explicit version without using ^ or ~ characters.

Tip

While customizing the UI, you can set the advanced server property, org.forgerock.openam.core.resource.lookup.cache.enabled, to false to allow AM immediately to pick up changes to the files as you customize them. This includes the XML callback files for authentication modules used by the UI.

Before using AM in production, however, set the property back to true.

To Test UI Pages in a Development Server

You can run the UI project on a dedicated development server for testing customizations. The UI in the development server connects to a separate instance of AM running on a different port, but using the same base domain. Any HTTP requests the UI makes out to AM are proxied to port 8080, by default.

You can override the default setting for the port AM is running on by using the OPENAM_PORT environment variable.

By separating the UI from the core AM server, the UI behaves as it would in production, except with the addition of development tooling, such as automatic browser refreshes when UI code is changed.

To run the UI on a development server:

  1. Configure and start an AM instance. For example, https://openam.example.com:8443/openam.

  2. Start a UI development server by using the yarn start command.

    The development server starts on this first available port counting up from port 8080, which is usually port 8081. Ensure you can access the development server using the same domain as the AM instance, for example, http://xui.example.com:8081.

  3. In a web browser, navigate to the full URL of your AM instance, but use the port number of the UI development server.

    For example, navigate to http://openam.example.com:8081/openam/XUI/#login.

    Changes made to the UI project are rebuilt and redeployed to the development server automatically, and the browser refreshed to show the changes, or any errors that have occurred.

    Note

    The UI development server assumes the AM instaces has a deployment URI of /openam. The deployment URI and port numbers can be edited in the config/webpack/development.js file in the UI project.

To Rebuild and Deploy the UI

After making changes to the UI, such as editing the JavaScript or HTML templates, perform the following steps:

  1. Rebuild the project using the yarn build.

  2. (Optional) Test the UI pages before deploying them to an instance. For more information, see "To Test UI Pages in a Development Server".

  3. Deploy the output in the build directory to the /path/to/tomcat/webapps/openam/XUI/ directory in your AM instances.

    There is no need to restart the AM instance. Subsequent visits to the UI pages will use the rebuilt files.

Read a different version of :