Skip to main content

Installing IDHub

Prerequisite​

Actionable Item

Decide where you would like to install IDHub.

  • IDHub can be installed and run on any Cloud or local Cluster.
  • For Cloud, IDHub recommends the following
    • Google Kubernetes Engine (GKE)
    • Amazon EKS
    • Azure Kubernetes Service (AKS)
  • For self-hosted cluster, you may use MicroK8s (see prerequisites) or Kind

Establish and Configure Private Kubernetes Cluster

  • You need to establish and configure your private Kubernetes Cluster which meets the minimum system requirements. Click here to learn more.

Configure DNS record with External IP address (FQDN)

  • You must configure DNS records with external IP with your DNS provider, to get your FQDN.
  • The FQDN will be the URL of IDHub application.
  • Please click here to get a detailed understanding of what is FQDN and how to configure.

Admin Access to Cluster

  • You need to identify users that have admin access to your cluster.
    • Anybody who has admin access to that cluster would be able to access the sensitive information.

Kubectl

Helm

  • Install Helm for managing charts and deploying applications.
    • Please refer to Helm Installation Guide for more details
    • IDHub is tested with the latest Helm version. However, it should also work with other Helm 3.x.x versions.

jq (Required for Scripts)

Install IDHub​

Actionable Item

Before installing IDHub make sure that you meet the pre-requisites and the minimum system requirements

The following sections elaborates the steps for installing IDHub in your Cluster.

Step 1: Clone IDHub App Repo​

Run the following command in your terminal to Clone IDHub App Repo

git clone https://bitbucket.org/sath-inc/app.git && cd app

Step 2: CA certificate (Optional)​

A Certificate Authority (CA) certificate is a digital certificate issued by a Certificate Authority that an organization controls or trusts. CA certificates are crucial for establishing secure communications in a network by verifying the identity of certificates issued under it. In the context of IDHub, a CA certificate allows you to extend your organization's trust chain, ensuring that only authorized entities can communicate securely with your IDHub instance.

You can either use a public CA certificate or generate your own custom CA certificate. The following section elaborates how you can publish your custom CA certificate and configure IDHub to use it.

  1. Generate a private key for your CA:
openssl genrsa -out custom-ca.key 4096
  1. Create a self-signed CA certificate:
openssl req -x509 -new -nodes -key custom-ca.key -sha256 -days 3650 -out custom-ca.crt \
     -subj "/C=US/ST=YourState/L=YourCity/O=YourOrganization/OU=IT/CN=your-ca-domain"
info

Replace /C=US/ST=YourState/L=YourCity/O=YourOrganization/OU=IT/CN=your-ca-domain with your organization's details.

  1. Configure IDHub to Use Custom CA Certificate

Configure IDHub to use the custom CA certificate by, adding the custom CA in the following path

scripts/certs/trusted

Step 3: Install Required Data Stores​

The next step is to install the required data stores, which include:

  • MongoDB
  • PostgreSQL
  • Kafka
  • Elasticsearch
  • MinIO (Recommended, but any S3-compatible storage system can be used)

Installation Command​

Run the following shell script to install the data stores:

./scripts/idhub/install/installDataStores.sh <DATASTORE_NAMESPACE_PREFIX> <--single-node|--multi-node|--managed-cloud>

Namespace Prefix Requirement​

  • <DATASTORE_NAMESPACE_PREFIX>: Prefix for naming datastore namespaces.
    • Allowed Characters: Alphanumeric (letters and numbers only).
    • Length Requirement: Exactly 3 characters.
    • Disallowed Characters: No special characters (e.g., @, #, -, _, etc.).
    • Examples of Valid Values: abc, sds, sd1.

Deployment Modes​

The installation script supports the following deployment modes:

  • --single-node: Applicable for MicroK8s. Installs all data stores in a single-node setup.
  • --multi-node: Applicable for MicroK8s. Installs data stores in a multi-node setup.
  • --managed-cloud: Assumes the use of managed cloud services where applicable (e.g., GKE, AKS, EKS, etc.).
Important Notes
  • The script uses a namespace prefix as an argument and runs the installation scripts for each datastore.
  • Run this script only once.
  • This shell script can be executed on any Linux OS within your cluster.
  • The installation script has been tested on GKE, MicroK8s and Kind and should also be compatible with Amazon EKS and Azure Kubernetes Service (AKS).
  • There is one shared datastore for multiple IDHub installations, meaning a single deployment of each datastore (Elasticsearch, MongoDB, PostgreSQL, Kafka, and S3-compatible storage) serves all IDHub instances.

Step 4: Initialize and Configure Datastores for IDHub Instance​

Run the following script to intialize and configure the datastores for a specified IDHub instance within a namespace. It verifies the readiness of each datastore and generates the necessary configurations.

./scripts/idhub/install/initDataStores.sh <DATASTORE_NAMESPACE_PREFIX> <IDHUB_INSTANCE> [-y]
info

  • <DATASTORE_NAMESPACE_PREFIX>: Prefix for naming datastore namespaces.

    • Allowed Characters: Alphanumeric (letters and numbers only).
    • Length Requirement: Exactly 3 characters.
    • Disallowed Characters: No special characters (e.g., @, #, -, _, etc.).
      • Examples of Valid Values: abc, sds, sd1.

  • <IDHUB_INSTANCE>: The IDHub instance to configure the datastore for.

    • Allowed Characters: Lowercase letters (a-z), Numbers (0-9)
    • Length Requirement: Must adhere to K8s namespace character limit
    • Disallowed Characters: No Uppercase letters, No Special characters (e.g., _, @, /, .)
      • Examples of Valid Values: abccorp, xyzcompany2

  • -y: Optional flag to skip confirmation prompts.

Step 5: Load the Datastore Configuration​

After configuring the IDHub instance and datastores, run the following command to apply the datastore configuration YAML to your Kubernetes namespace.

kubectl create namespace <IDHUB_INSTANCE>
kubectl -n <IDHUB_INSTANCE> apply -f ./build/k8s/<IDHUB_INSTANCE>_config.yaml
info
  • <IDHUB_INSTANCE>: The IDHub instance to configure the datastore for.
    • Allowed Characters: Lowercase letters (a-z), Numbers (0-9)
    • Length Requirement: Must adhere to K8s namespace character limit
    • Disallowed Characters: No Uppercase letters, No Special characters (e.g., _, @, /, .)
      • Examples of Valid Values: abccorp, xyzcompany2
  • Replace <IDHUB_INSTANCE> with the namespace corresponding to your IDHub instance where the datastore configurations should be applied.

Step 6: Installation Command​

To deploy IDHub using Helm, run the following command:

helm repo add sath https://repo.sath.com/repository/sath/
helm repo update
helm upgrade --install idhub sath/idhub --version 24.4.1 \
  --set global.IDHUB_INSTANCE=<IDHUB_INSTANCE> \
  --set global.IDHUB_FQDN=<IDHUB_FQDN> \
  --set ingress.className=<INGRESS_CLASS_NAME> \
  -n <NAMESPACE> --create-namespace
Parameters

IDHUB_INSTANCE​

  • Description: The name of your IDHub instance.
  • Allowed Characters: Lowercase letters (a-z), Numbers (0-9)
  • Length Requirement: Must adhere to Kubernetes namespace character limits.
  • Disallowed Characters: No uppercase letters, No special characters (e.g., _, @, /, .)
  • Examples of Valid Values: abccorp, xyzcompany2

IDHUB_FQDN​

  • Description: The fully qualified domain name (FQDN) for your IDHub instance.
  • Note: Please click here to get a detailed understanding of what an FQDN is and how to configure it.

NAMESPACE​

  • Description: The Kubernetes namespace where you want to deploy the IDHub application.

INGRESS_CLASS_NAME​

  • Usage: --set ingress.className=public if MicroK8s Ingress is used. Else leave it blank.

Post install verification​

Run the following command on your K8 cluster, to verify the successful installation of IDHub.

kubectl get -n <IDHUB_INSTANCE> pods
<IDHUB_INSTANCE>
  • <IDHUB_INSTANCE> is the name of your IDHub instance.
    • Allowed Characters: Lowercase letters (a-z), Numbers (0-9)
    • Length Requirement: Must adhere to K8s namespace character limit
    • Disallowed Characters: No Uppercase letters, No Special characters (e.g., _, @, /, .)
      • Examples of Valid Values: abccorp, xyzcompany2

The status for all the pods must be in running state, which means that IDHub has been installed successfully on your k8 cluster.

Uninstall IDHub​

Uninstall IDHub Instance​

Run the following command on your K8 cluster, to uninstall the IDHub instance.

helm uninstall idhub -n <IDHUB_INSTANCE>
<IDHUB_INSTANCE>
  • <IDHUB_INSTANCE> is the name of your IDHub instance.
    • Allowed Characters: Lowercase letters (a-z), Numbers (0-9)
    • Length Requirement: Must adhere to K8s namespace character limit
    • Disallowed Characters: No Uppercase letters, No Special characters (e.g., _, @, /, .)
      • Examples of Valid Values: abccorp, xyzcompany2

Uninstall Data Store​

Run the following command on your K8 cluster, to uninstall the Data stores

Kubectl delete <DATASTORE_NAMESPACE_PREFIX>-<datastore>
<datastore>, <DATASTORE_NAMESPACE_PREFIX>
  • <datastore> are Elasticsearch, MongoDB, PostgreSQL, Kafka, and MinIO for which you will have to run the above command separately for each one of them.
  • <DATASTORE_NAMESPACE_PREFIX> is the prefix that you have used to install the datastores

Login To IDHub​

In order to Log in to IDHub, you will need to create a tenant. To do that, below steps are needed to be performed.

Navigate to https://[FQDN]/admin

info
  • Replace [FQDN] with your IDHub Application URL.
  • Please Click Here to get a detailed understanding of what is FQDN and how to configure.

Procure Tenant Management Admin Password​

In the tenant management login page, you will asked to enter the tenant management admin password. Run the following kubectl command to get the tenant management password:

kubectl get secret tenant-admin-user-password -o jsonpath="{.data.password}" -n <IDHUB_INSTANCE> | base64 --decode
<IDHUB_INSTANCE>
  • <IDHUB_INSTANCE> is the name of your IDHub instance.
    • Allowed Characters: Lowercase letters (a-z), Numbers (0-9)
    • Length Requirement: Must adhere to K8s namespace character limit
    • Disallowed Characters: No Uppercase letters, No Special characters (e.g., _, @, /, .)
      • Examples of Valid Values: abccorp, xyzcompany2

IDHub Tenant Management Page​

After login, you will be shown the Tenant Management portal as you can see below.

Please click on the Create Tenant button in order to create your first tenant.

Register Account in IDHub​

Fill out the Register form.

info
  • The username and password entered here will be used to login to your IDHub Tenant. This should be written down and remembered.

License Activation and Validation​

If you have already purchased an IDHub Subscription, you will get the license key in your email which you can enter to activate the license.

Purchase IDHub License

Click Here to purchase your IDHub Subscription.

Terms and Conditions​

Final Step is click on the checkbox and accept the IDHub Software Customer Agreement, Acceptable Use Policy and Privacy Policy.

Review Summary, Start Installation and Login​

Finally, review the summary of your account and start the installation. You will get a page, as you can see in the screenshot below. Click on the Install button to start the installation.

After installation is complete, you would be automatically redirected to your IDHub tenant login page, where you can enter the username and password (that you have entered in the register form) to login to your IDHub tenant.

tip

The Tenant Management portal shows the list of all tenants that have been created by you. (See Screenshot below) Under actions you can click on the Login button, which will redirect you to the Login URL for that specific tenant.