Using the Design Kit CLI

Prerequisites

  • The Loginapp Design Kit is installed.

Preparing a directory to store customizations

To initialize the Loginapp Design Kit, the path to a custom folder must be provided. This folder will contain all the files that can be used when customizing:

 
Terminal box
CUSTOM_DIRECTORY=/path/to/my/custom/directory
./sdk init -d $CUSTOM_DIRECTORY

We strongly recommend keeping customized files separate from the Loginapp Design Kit installation directory (.internal/). The separation allows for the maintenance of multiple projects (customers, instances, etc.), easier referencing of default values and painless updates. In addition, it is much simpler to put separate customizations under version control.

 
Info

For the remainder of this documentation, we use $CUSTOM_DIRECTORY as a variable that points to the directory containing the customizations. This is not a requirement to work with the Loginapp Design Kit.

Using the development mode

To get immediate visual feedback while customizing, the Loginapp Design Kit provides a development mode.

To run the development mode, use:

 
Terminal box
./sdk dev -d $CUSTOM_DIRECTORY

After running the command, a browser will open showing a static view of the web application, which makes the changes immediately visible without having an actual Airlock IAM instance running. The dev mode can be terminated using CTRL+C in the shell.

 
Notice

The ./sdk dev command may generate security warnings. These warnings only apply to the local instance of the Loginapp Design Kit and do not affect customizations deployed to production. It is, therefore, safe to ignore these warnings.

Creating a customizations build

  1. Once customizing is completed, create a build for production use as follows:
  2.  
    Terminal box
    ./sdk build -d $CUSTOM_DIRECTORY
  3. A zip file is created at $CUSTOM_DIRECTORY/build/airlock-iam-loginapp-rest-ui-customizations.zip

Deploying the customizations build for production

  1. Modify the instance.properties file as follows to specify the filename and location of the zip file containing the customizations:
  2.  
    Terminal box
    iam.loginapp.rest.ui.customizations = instances/${instance.name}/airlock-iam-loginapp-rest-ui-customizations.zip
  3.  
    Notice

    This step is needed only once.

  4. Deploy the zip file by moving it to the Airlock IAM instance directory instances/${instance.name}/airlock-iam-login-ui-customizations.zip
    • Replace ${instance.name} with the name of the instance (e.g., auth).
  6. Restart Airlock IAM for the changes to take effect.
  7. Your customizations made with the Loginapp Design Kit CLI tool are now active. They will be visible in the web application.

File structure overview

Customization is done entirely in the directory $CUSTOM_DIRECTORY while running the development mode.

The most important directories and files are listed below:

src/sass/custom

SASS files to style the UI

src/assets/custom/img

Custom images that are referenced from the SASS files

src/assets/custom/i18n

Translation files to customize texts

src/assets/custom/js

JavaScript files for more advanced customizations

src/sdk/config

Configuration to alter the behavior of the Loginapp Design Kit itself