Design Kit installation

The Loginapp Design Kit is a standalone application designed to run locally. It does not require an actual Airlock IAM installation.

The Loginapp Design Kit runs on the following OS:

  • Mac OSX
  • Linux
  • Windows

Prerequisites...

... when using the Design Kit in restricted network environments

As of IAM 8.6, the Loginapp Design Kit uses the pnpm package manager (instead of npm).

During commands such as sdk init, sdk dev, and sdk build, the Design Kit downloads Node.js, pnpm, and project dependencies from external repositories. When the Design Kit is operated behind a corporate web proxy or with an internal npm registry, however, direct access to these public package repositories may not be available. You can only use internal repositories, such as repositories hosted in Artifactory.

In this case, use the following environment variables and configuration options to redirect downloads from external to internal repositories. Perform these commands and steps before starting the actual installation of the Design Kit.

Trusted internal CA certificate

If the internal Artifactory server uses a TLS certificate issued by your company CA, Node.js must be configured to trust that CA. Perform the following steps:

  1. Obtain a PEM file containing the required root or intermediate CA certificate from your organization's IT department.
  2. Run the following command:
    • For macOS and Linux using Bash:
    •  
      Terminal box
      export NODE_EXTRA_CA_CERTS=<local-path-to-cert.pem-file>
    • For Windows using PowerShell:
    •  
      Terminal box
      $env:NODE_EXTRA_CA_CERTS = '<local-path-to-cert.pem-file>'

Node.js download

Node.js is provided on the external repository https://nodejs.org/dist/.

  • On Windows, Node.js can be downloaded manually from the external repository when installing the Design Kit. See Installation on Windows (native) below.
  • On macOS and Linux, the Design Kit must download Node.js from an internal mirror instead of directly from https://nodejs.org/dist/. See the following instructions.

Instructions for macOS and Linux

  1. Mirror the Node.js distribution locally. The internal mirror must expose the same directory and file structure as the official Node.js distribution repository https://nodejs.org/dist/.
    • When using Artifactory, configure the mirrored distribution as a generic remote repository, not as an npm repository.
  3. Run the following command in Bash:
  4.  
    Terminal box
    export SDK_NODE_BASE_URL=https://<url-to-local-node-distribution>
  5. The Design Kit now uses the specified local location when downloading the required Node.js version.

pnpm download with Corepack

During sdk init, the Design Kit uses Corepack to download the required pnpm version from an npm registry (corepack prepare pnpm@<version>). Corepack does not use .npmrc configuration files and must be configured exclusively through environment variables.

For macOS and Linux using Bash:

 
Terminal box
export COREPACK_INTEGRITY_KEYS=0
export COREPACK_ENABLE_DOWNLOAD_PROMPT=0
export COREPACK_NPM_REGISTRY=https://<url-of-local-npm-registry>
export COREPACK_NPM_PASSWORD=<password>
export COREPACK_NPM_USERNAME=<username>

For Windows using PowerShell:

 
Terminal box
$env:COREPACK_INTEGRITY_KEYS = '0'
$env:COREPACK_ENABLE_DOWNLOAD_PROMPT = '0'
$env:COREPACK_NPM_REGISTRY = 'https://<url-of-local-npm-registry>'
$env:COREPACK_NPM_USERNAME = '<username>'
$env:COREPACK_NPM_PASSWORD = '<token>'

Project dependencies via pnpm

The sdk dev and sdk build commands install the project dependencies using:

pnpm install --frozen-lockfile

pnpm retrieves these dependencies from an npm registry. By default, this is https://registry.npmjs.org.

When an internal npm registry is required, you must configure it separately. There are two supported configuration options: with environmental variables and with the .npmrc file. Both options are explained below.

Configure the registry using an environment variable

This option is suitable when the registry does not require token-based authentication.

Run the following command:

  • For macOS and Linux using Bash:
  •  
    Terminal box
    export NPM_CONFIG_REGISTRY=https://<url-of-local-npm-registry>
  • For Windows using PowerShell:
  •  
    Terminal box
    $env:NPM_CONFIG_REGISTRY = 'https://<url-of-local-npm-registry>'

Configure the registry using .npmrc

Alternatively, you can configure the internal registry in the user-level .npmrc file.

  • On macOS and Linux, the file is located at: ~/.npmrc
  • On Windows, the file is located at: %USERPROFILE%\.npmrc
    For example: C:\Users\<user>\.npmrc

Use the following configuration on all platforms:

 
Terminal box
registry=https://<url-of-local-npm-registry>/
//<host-and-path-of-local-npm-registry>/:_authToken=<token>

The _authToken entry is only required if the internal registry requires authentication.

 
Info

When using Artifactory, you can copy the above configuration lines (including the auth token) directly from Artifactory's “Set Me Up” section.

 
Notice

Do not modify the Design Kit's .internal/project_root/.npmrc file. This file is managed by the Design Kit and may be replaced during a Design Kit update. Registry-specific user configuration must be placed in the user-level .npmrc instead.

Installation on Mac OSX and Linux

Prerequisites:

  • bash (version 3.2 or newer)
  • tar (with zlib or gzip)
  • zip
 
Notice

The Loginapp Design Kit has a dependency on NodeJS. To avoid downloading NodeJS multiple times, the downloaded file is stored in a location shared by all customizations. A path, which can be relative, can be set in the SDK_NODE_BASE_FOLDER environment variable to define the storage location. If no location is set, it will be downloaded to <sdk base folder>/.internal/node-<version>.

Download and installation

  1. Download the Loginapp Design Kit from the release download page that matches your current Airlock IAM version: https://techzone.ergon.ch/downloads/airlock-iam
  2. Unpack the downloaded zip-file (example for version 8.2):
  3.  
    Terminal box
    unzip airlock-iam-loginapp-design-kit-8.2.zip
cd airlock-iam-loginapp-design-kit-8.2
  4. The installed directory contains 2 files and a hidden folder. The hidden folder should not be modified.
    • README.md – with a link to the latest documentation
       
    • sdk – a CLI to use the Loginapp Design Kit

Installation on Windows (native)

Prerequisites:

  • Command prompt or PowerShell
  • Windows zip program or an alternative (e.g. 7-Zip)

Download and installation

  1. Download the Loginapp Design Kit from the release download page that matches your current Airlock IAM version: https://techzone.ergon.ch/downloads/airlock-iam
  2. Unpack the downloaded zip file on your workstation.
  3. Open the command prompt and navigate to the extraction folder.
  4. Run the sdk.batfor the first time and note the initial message:
  5.  
    Terminal box
    C:\Users\username\Downloads\sdk>sdk.bat 
NodeJS is not present. Download the zip distribution for Windows x64 from https://nodejs.org/dist/v20.11.1/ and extract it to a folder called "node" within the sdk folder.
  6. Download the required Node.js zip file from the displayed URL. Then create the required node folder inside the SDK folder and extract Node.js into it.
  7. Re-run the sdk.bat – the following information is printed:
  8.  
    Terminal box
    C:\Users\username\Downloads\sdk>sdk.bat 
Usage: sdk.bat COMMAND [COMMAND-OPTIONS] 
E.g. sdk.bat init C:/Users/myUser/myCustomization 
 
The Loginapp Design Kit allows developers to style and customize Loginapp UI pages 
 
Commands: 
  init     Creates the source directory for your customizations 
  dev      Starts the development mode opening a browser on port 8888 with live reload on changes to any files in the source directory. Use CTRL+C to stop the process 
  build    Creates a ZIP file containing all customizations in the source directory at build\airlock-iam-loginapp-rest-ui-customizations.zip 
  version  Prints the version of the Loginapp Design Kit 
 
Option for init, dev and build: 
  Path to the directory that contains the customizations 
 
Environment variables: 
  NPM_CONFIG_REGISTRY    NPM registry mirror (default: https://registry.npmjs.org) 
 
See the README.md for additional help
  9. Proceed by initializing a new Loginapp Design Kit project. Run sdk.bat init <path_to_project_folder>.
    For example:
  10.  
    Terminal box
    C:\Users\username\Downloads\sdk>sdk.bat init C:/Users/myUser/myCustomization 
 
> iam-loginapp-ui@1.0.0 sdk-init-customization-dir 
> node initialize-customization-dir.js C:/Users/myUser/myCustomization 
 
Initialized Loginapp Design Kit source directory: C:/Users/myUser/myCustomization
  11. When running sdk.bat dev <path_to_project_folder> for the first time, the required browser application resources are downloaded and installed in your project folder.
    The downloading and installation process may take some time.
  12. After successful compilation, a web browser opens automatically and displays the development page of your new customization project.

Known limitations

The Loginapp Design Kit uses the underlying operating system's ability to monitor all files to detect changes. The Loginapp Design Kit uses this mechanism to detect when the page needs to be refreshed automatically. How many files can be monitored depends on the configuration of the number of inotify watches configured in the operating system.

This works well on standalone computers but running multiple instances of the Loginapp Design Kit on a server system may require an increase of inotify watches permitted by the operating system.

Further information and links

Internal links: