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

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: