AbsaOSS / spline-ui

Table of Contents

• Spline UI
  • Gallery
  • Download
  • Usage
    • Running as a Docker container
    • Running a WAR-file
    • Running as embedded CDN resource
  • Building from sources
    • TL;DR
    • Building a Docker
    • Building UI-core (SPA) alone
  • Versioning strategy

Spline UI

The UI for Spline project

Spline UI app is implemented as a single-page application (SPA), available alone as well as packed as a Docker image or a WAR-file. Choose according to your deployment preferences.

Gallery

See gallery

Download

• Docker
• WAR-file

Usage

Spline UI needs to know where Spline Consumer API sits. Spline Consumer API endpoint is accessed from the user browser directly, so use appropriate IP or host name.

Running as a Docker container

docker container run \
      -e SPLINE_CONSUMER_URL=http://localhost:8080/consumer \
      -p 9090:8080 \
      absaoss/spline-web-ui:latest

Open Spline UI in a browser - http://localhost:9090

Running a WAR-file

Download a WAR-file using the link above, and deploy it into any J2EE-compatible Web Container, e.g. Tomcat, Jetty, JBoss etc.

A WAR-file provides several alternative ways how to set configuration parameters:

• JNDI

  (for example in a context.xml in the Tomcat server)

  <Environment name="spline/consumer/url" value="..." type="java.lang.String"/>

• JVM property

  $JAVA_OPTS -Dspline.consumer.url=...

• System environment variable

  export SPLINE_CONSUMER_URL=...

Running as embedded CDN resource

It is possible to use compiled UI sources placed at some CDN server. In that the application can be configured with query parameters like so:

<iframe
    src="https://cdn.jsdelivr.net/path-to-compiled-app-assets/index.html?_splineConsumerApiUrl=ENCODED_CONSUMER_API_PATH&_targetUrl=ENCODED_APP_PATH&_isEmbeddedMode=true">
</iframe>

All available config query parameters list:

Name	Description	Default	Required
_splineConsumerApiUrl	Spline Consumer API URI		true
_isEmbeddedMode	Embedded mode settings	false	false
_targetUrl	App will be redirected to that url right after initialization. The path should start with /	/	false

_splineConsumerApiUrl is a required query parameter.

How to build assets for your CDN

1. Install the LTS version of Node.js: https://nodejs.org/en/download/
2. Install the latest version of NPM: npm i -g npm@latest
3. Install dependencies:
   1. Go to the ui directory: cd <root>/ui
   2. Run npm ci
4. Build the project:
   1. Go to the ui directory: cd <root>/ui
   2. Run npm run build::CDN
5. CDN resources is everything inside <root>/ui/dist

Building from sources

TL;DR

mvn clean install

Building a Docker

cd deployment/web
mvn install -P docker -D dockerfile.repositoryUrl=my 

It will create my/spline-web-ui image and two tags: $version and latest

See Building Spline docker images for details.

Building UI-core (SPA) alone

Config

Config file should be placed in the directory:

• after build in the dist folder /dist/assets/config.json
• or before build /src/assets/config.json (this option applies for development)

The example of the config can be found here: /src/assets/config.example.json

The list of all configuration properties along with their default values are stored in the config.default.json. Properties provided in the config.json overwrite corresponding properties from the config.default.json.

Development server

Run npm start for a dev server. Navigate to http://localhost:4300/. The app will automatically reload if you change any of the source files.

Build

Run npm run build to build the project. The build artifacts will be stored in the dist/ directory. When build completes replace SPLINE_UI_DEPLOY_CONTEXT in the dist/app/index.html accordingly to your deployment schema, and verify/create dist/app/assets/config.json as described above.

Versioning strategy

Spline UI version number mimics Semantic Versioning structure, although it doesn't strictly follow it. The reason is that it's difficult to define what is a Public API¹ of the Spline UI in terms of Semantic Versioning.

But for the sake of consistency, Spline UI version uses a similar three-digit pattern with the pre-release and build labels, but slightly different meaning of the major and minor components.

• The major version component indicates the Spline REST major version it supports with guarantee. The Spline server with the major version that is higher than the UI major version can also be supported, depending on the reason why that major version was incremented at the first place. (Spline server exposes multiple different APIs, and a given major version might expose exactly the same Consumer API that the previous one did).

• The minor version component is incremented when new important features or significant internal changes are introduced.

• The patch version component is incremented on bugfixes and small enhancements.

---

Copyright 2020 ABSA Group Limited

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Footnotes

1. Semantic Versioning specification relies on the definition of the Public API that the given application exposes and the changes to which is communicated by incrementing the version numbers. ↩