Connection Manager

This project was bootstrapped with Create React App. See local README for further info.

• Connection Manager
  • Coding Approach
    • Versioning
    • Code Changes
  • Docker
    • Build a local image
    • Running a local image
    • API location
    • Production mode: Building an image and API location
      • Example
    • Versioning with the git commit hash and package.json version
    • Full build
  • Deploying Application
  • Authentication

Coding Approach

In order to keep coding quality and ensure the best development workflow, this project adopts some methodologies which should help tracking changes and preventing issues in production.

Versioning

The correct way to create release it to use the completely automated yarn version command.

It will bump the version in package.json and create a tag. The tag is useful to track and create releases.

If you want to learn more about yarn version, read here.

⚠️ NOTE Using yarn version will also update the version of the Helm Chart to match the version supplied.

Code Changes

We are adopting a PR based approach with commits squash merge. It helps to keep the history cleaner and to be feature oriented.

The general rule is to create a pull request and only when marked as approved then bumping the version.

It needs to be done following the versioning rules.

⚠️ Important notice

It is really important to properly version every change and that the version change is the last commit in the PR. If further changes are done, then bump the version again. This will ensure that the git tag (release) will be reference the right commit.

Docker

The app can be run in a container. That is the current way it gets deployed in production.

Build a local image

You can build this app as a docker container image containing a Node.js Express server that will serve the production build of the app 🚀

The image can be easily build with docker build as follows:

docker build -t connection-manager-ui:local .

Running a local image

You can run the app container as follows:

docker run -p 8080:8080 connection-manager-ui:local

API location

The app needs to access the API to handle all the operations it needs to perform on the backend.

By default the app will access the API at http://localhost:3001 which is useful while developing.

It will use the same protocol as the app is loaded from to avoid the Mixed Content error. Read more about here.

If the API is located on another URL, you can specify it by setting the value of either the React App variable REACT_APP_API_BASE_URL or the regular env var API_BASE_URL used by the bundled server.

The API will be accesed at either ${REACT_APP_API_BASE_URL}/api or ${API_BASE_URL}/api.

Note that the value must not end in '/'.

Using the REACT_APP_API_BASE_URL is useful when running locally, for example if the API is at localhost 3002, you can start the app with REACT_APP_API_BASE_URL=http://localhost:3002 npm start

Production mode: Building an image and API location

If using REACT_APP_API_BASE_URL, the value must be set at build runtime, and it will be part of the build.

This means that if you build a docker image with this value, that image will always try to access the API on the defined URL.

Setting the API location using this option impedes using the same image for different environments like dev or uat; using a regular env var is more flexible and the recommended way.

In order to build an image that can be used for different environments, you use the provided Dockerfile and set the value of the env var API_BASE_URL at runtime.

The bundled node server which serves the app production build, will also expose a /config endpoint that the app calls at boot time and which contains the value of the API_BASE_URL env var if set.

The API_BASE_URL var overrides the value of REACT_APP_API_BASE_URL.

Example

Let's say the app is published at https://ui.example.com; the sequence will be:

1. The browser load the app from https://ui.example.com. This will be served by the included node server in the container/pod.
2. The app will set the API location to the default value or the value of REACT_APP_API_BASE_URL if not null
3. The app will fetch https://ui.example.com/config. This will be served also by the included node server, and it will return the value of the env var API_BASE_URL
4. If the previous request returned a API_BASE_URL the app will use this as the API location.

Versioning with the git commit hash and package.json version

The Connection Manager React App can include the version and commit hash the build uses.

The env variables responsible to add these values to the bundle are:

1. REACT_APP_VERSION
2. REACT_APP_COMMIT

You can set them as follows:

docker build \
--build-arg REACT_APP_VERSION=`cat package.json | grep version | sed -E 's/.*version": "([0-9\.]*)".*/\1/'` \
--build-arg REACT_APP_COMMIT=`git rev-parse HEAD` \
-t connection-manager-ui \
.

Full build

docker build \
--build-arg REACT_APP_VERSION=`cat package.json | grep version | sed -E 's/.*version": "([0-9\.]*)".*/\1/'` \
--build-arg REACT_APP_COMMIT=`git rev-parse HEAD` \
-t connection-manager-ui \
.

Deploying Application

Once a new version the UI is ready to deploy simply tag the commit with a string beginning with "h". e.g. h1.3.20. This will create and deploy the helm chart for this app. The version number used will match the version defined in package.json.

Authentication

Authentication is enabled by default in a production build and it cannot be disabled.

In dev mode it can be selectively enabled or disabled depending on the preference. Simply open the browser console and run the commands

• To disable authentication auth(false)
• To enable authentication auth(true)

Using external authentication

Set the environment variables, before running the server (or Docker image):

• CHECK_SESSION_URL: URL to check if the session is still valid
• LOGIN_URL: - URL to redirect to when the session is not valid
• LOGOUT_URL: - URL at which to obtain a logout URL (Kratos browser logout)
• LOGIN_PROVIDER: - The name of the login provider. When specified, the app will redirect to the login provider URL.

These will override the in-app login form and redirect to the provided URL.

⚠️ NOTE It is suggested to clear local storage and cookies after enabling and disabling authentication. It will help starting a fresh session.