Recent Searches

No recent searches

    Popular Articles

      Articles
      View all
        Topics
        View all
          Tickets
          View all
            no results

            Sorry! nothing found for

            Illuminate Integration Gateway Automatic Installation Instructions

            Modified on Thu, 22 Aug at 5:37 AM



            •  Once you click “Submit” button a tar will be available to download
                     

            • Pre-Configured Script (Optional):

              Note: Skip this step if you are using "Default Configuration Type" and goto "Setup Process" step directly.

            • Prerequisites:

            • Valid Illuminate login credentials.

            • Database connection details.

            • Instance for IIG setup.

            • Generating a tar file:

              • Enter the valid details for the database connection.


            Note: This is an example of the menu provided by selecting Pre-Configured Script

            •  If you want to add more database connections click “Confirm & Add More” otherwise click “Save”.

            • Once you click “Save” button a custom tar will be available to download. We need to use this tar file for installing IIG using pre-configured option.

            Note: Directions can also be referenced from the Installation Instructions button to the left of the download button.


            2. Setup Process

            • Once you upload the tar file onto the server, untar the tar file, and go to that iig-automation-clienthosted directory.

            1. tar -xvf iig-clienthosted.tar

2. cd iig-automation-clienthosted


            • We need to run the install-prereqs. sh script which installs the required prereqs to run the IIG automation scripts.
            1. bash install-prereqs.sh (or) ./install-prereqs.sh


            Note: If scripts are not able to run due to the insufficient permissions, give the executable permissions to the scripts.

            1. chmod +x <script_name>   #Example: chmod +x configure.py



            • In that step, it will ask you for OS type ( ex:-Ubuntu, Centos etc.). Enter appropriate value.

            • Once prereqs are installed the IIG scripts are saved under /opt/iig/ directory.

            1. cd /opt/iig

            • Now run configure.py file which is main script to setup the IIG.

            1. ./configure.py

            • The configure.py script will ask the steps mentioned below

            Step 1

            Choose 'Y' if you whitelisted the NAT IPs mentioned in the prerequisites; otherwise, the script will exit at this point as this is mandatory.


            Step 2
            Select the specific environment IIG connect. Please choose the environment number based on your requirement(Example: 3).
            Step 3

            Choose 'Y' If the ports are opened mentioned in the prerequisites, this will check whether the dataport hosting server can communicate with the illuminate. 


            Step 4
            Enter your illuminate login details(username and password)
            Step 5
            Choose the host configuration(Example: 2)
            Step 6
            Select whichever option selected in the Illuminate UI(Either Default or pre-configured). 
            Step 7
            In this step, we need to setup ssl configuration, if you have your own school's SSL certs and domains then choose N and continue.

            Step 7A-[Optional] 
            Click 'Y’ If you want to create custom SSL certificate for this particular setup we will use LetsEncrypt service to create a new SSL certs for your custom DNS


            Step 7B-[Optional]
            Enter your custom DNS which is going to generate Lets Encrypts certs for and this is going to connect with N2N’s IIG containers

            Step 8

            Enter the institutions top level domain and fully qualified domain(FQDN) as shown below, once the DNS entered, the script will verify the DNS resolution. 

            Note: If the DNS is not resolved the scirpt will exit with the valid error message

            Step 9
            • Enter the SSL certs location on the server. once entered, the script will check the ssl validation
            Note: If the SSL validation fails, the script will exit with valid error message
            1. /opt/certs/fullchain.pem   - ssl chain cert

2. /opt/certs/privkey.pem     - private key


            Step 10
            • In this step provide database hostname and port and the script will check the connection whether the dataport hosting server is able to reach to the database or not.
            Note: Make sure the dataport hosting server is able to reach to the database otherwise the script will exit at this point

            Step 10A-[Optional]
            • Enter N for this option. This step is under process, and we will notify you in future Updates

            Step 10B-[Optional]

            • This option is for system configuration, which involves setting up soft and hard limits, memory settings, and IPv4 forwarding settings. You can choose Y or N; choosing Y will apply the settings; otherwise, the system settings are default.


            DB Connection Details


            Note: This step will be skipped if you select "Pre-configured Script" and goto "Installation process" step directly.


            These are the following parameters that are needed to establish the database connection: 


            S.NO

            Parameter Name

            Description

            1

            database type

            Type of the databases(Ex:Oracle, Mysql, Sybase..etc)

            2

            connection name

            Name your DB connection

            3

            description

            Short description

            4

            hostname

            Database hostname

            5

            port

            Database port

            6

            username

            Database username

            7

            password

            Database password

            8

            SID

            Database SID

            9

            Service Name

            Database Service Name

            Note: The above mentioned fields are mandatory. If any parameter is not required click enter(null value) and continue

            • Select the numeric option based on your database type.

            • Provide the mandatory details for IIG connection as provided in the given screenshot.


            Note: The file with your DB details are stored in this file /opt/iig/install/roles/test/defaults/main.yml so we can always verify the details entered.



            3. Installation Process

            • Go to /opt/iig and run installation script.
            • Run the script as root user
            1.  ./install.sh
            Note: This will install both Nginx and dataport containers on the server/instance.
            • Please choose the Illuminate application environment(QA or PROD)


            • The console output of the installation process.

            • Once the install process completes, we can verify the containers are running on the server and iig dns is connected to respective Illuminate account under “Connections” tab.

            • Finally, status api checks will show the following results.
            1. curl -X GET https://{your dns}/idp/status


            Info | Appendix-1 (IMPORTANT)

            Adding Additional Database Providers To The Existing IIG Connection



            To add one more database provider for the existing setup, run configure-db.py to enter the database details then run the save-multiple-database-connections.yaml script with chosen environment


            Note:  This is possible only if you install IIG using above automation process


            /opt/iig/install/configure-db.py

cd /opt/iig/install

ansible-playbook save-multiple-database-connections.yaml -e stage_env=qa or prod



            Integration Gateway setup for PROD on the same QA host/server

            If the client wants to set up a PROD integration gateway on the QA host, they need to follow these steps

            • Create a new docker network



            docker network create n2ndataport_prod_default


            • Connect Nginx container to newly created dataport network



            docker network connect n2ndataport_prod_default nginx
            • Create prod integration Gateway Docker container



            docker run --network=n2ndataport_prod_default --net-alias dataportProd --name dataportProd -it -d quay.io/n2ndevops/illuminatedataport:4.10


            • Uncomment lines from 16-23 in default.conf file

            • Test Nginx configurations

            nginx -t
            • Reload Nginx configurations



            service nginx reload
            • Test the connection using curl. It should “return a response status as not a valid request”. Note that you need to configure the command below to match organizational nomenclature

            curl -X GET https://{server_name(or)host_name}/idp2
            • Now jump to "Establishing a connection between Illuminate, Integration Gateway, and the SIS Database"


            .

            Optional step to autostart the containers after a server reboot

            If a server is rebooted, restarted, or start/restart, the docker engine must be restarted. To accomplish that automatically follow the steps below


            1. chkconfig docker on 
            2(i). docker update --restart=unless-stopped $(docker ps -q) Note: This command starts all the containers within the docker engine of the server (OR) (ii) docker update --restart=unless-stopped containerID/ContainerName Note: This command will start only the specified container



            .

            SSL Certs In Dataport/IIG

            If a client wants to update SSL certs in Nginx, they can go through these instructions for more details

            What is an SSL certificate?

            An SSL (Secure Sockets Layer) certificate is a digital certificate that authenticates the identity of a website and encrypts information sent to the server using SSL technology. Encryption is the process of scrambling data into an undecipherable format that can only be returned to a readable format with the proper decryption key.

            What are Certificate Chains?

            A certificate chain (or Chain of Trust) is made up of a list of certificates that start from a server’s certificate and terminate with the root certificate.

            What is SSL Certificate Chain Order?

            The SSL certificate chain order consists of root certificates, intermediate certificates, and a server’s certificate. Root CAs are a trusted source of certificates. Intermediate CAs are bridges that link the server’s certificate to the root CA.

            There are three parts to the chain certificates

            • Server Certificate: The server certificate is issued to the specific domain the user needs coverage for.

            • Intermediate Certificate: Intermediate certificates act as middle-men between the protected root certificates and the server certificates issued out to the public. There will always be at least one intermediate certificate in a chain, but there can be more than one.

            • Root Certificate: A root certificate is a digital certificate that belongs to the issuing Certificate Authority. It comes pre-downloaded in most browsers and is stored in what is called a “trust store.” The root certificates are closely guarded by CAs.

            For an SSL certificate to be authenticated by the web browsers, it must be authentic and issued by a trusted certificate authority embedded in the browser’s trusted store. If your SSL certificate isn’t issued by a trusted certificate authority, i.e., if it isn’t issued by a Root CA, then the connecting device or web browser will continue to check if the issuing CA was issued by a root CA. It will keep going back down the SSL certificate chain order to find the root CA. If it finds a root CA, a secure connection will be established. If it doesn’t find a root CA, then the connection will be dropped, and your web browser will display an error message that reads “invalid certificate” or “certificate not trusted.”

            How To Update SSL Certs In Dataport

            • Ensure you have a private key

            • Create a full certificate bundle for NGINX using one of the methods below, depending on how your SSL provider delivered the certificates to you.

            How To form a bundle .crt file


            • Open up a notepad or any text editor.

            • Copy-paste the Public cert (public should always be on the top of the file)

            • Copy-paste the Intermediate cert

            • Copy-paste the Root cert

            • Now save the file with the desired name(dataport-test-school-edu.crt) within an extension of the .crt

            • You will have to create a .crt(self-signed is not accepted) file and a private key.


            (OR)

            Example GoDaddy:


            cat signed_ssl.crt gd_bundle.crt > dataport-test-school-edu.crt Note: Above gd_bundle assumes both intermediate and root

            Other SSL providers with a single intermediate certificate:


            cat signed_ssl.crt intermediate1.crt root.crt > dataport-test-school-edu.crt

            Other SSL providers with multiple intermediate certificates:


            cat signed_ssl.crt intermediate1.crt intermediate2.crt root.crt > dataport-test-school-edu.crt


            Additional step if the private key is password protected:


            .

            If your private key is password-protected, we will need to make a copy without that password to use on the NGINX instance. If you run these commands and are not prompted for a passphrase, your SSL key did not have a passphrase. If you are prompted for a passphrase, enter it when prompted.


            • NGINX will not properly restart if the private key is password protected.

            • Hence, run the below command to turn the password-protected to a file.



            openssl rsa -in private.key -out dataport-test-school-edu.key



            Now you have the bundled cert and private key ready, do the below steps to update these files in the Nginx container:

            Step 1:

            • Upload the new cert and the key files to the server

            • Copy the new files to the NGINX Docker container to the certs folder.

            sudo docker cp dataport-test.school.edu.key nginx:/certs/dataport-test-school-edu.key 
            sudo docker cp dataport-test.school.edu.crt nginx:/certs/dataport-test-school-edu.crt


            Step 2:

            • Navigate to the below location

            docker exec -it nginx bash vi etc/nginx/conf.d/default.conf


            • You will need to update the following items in the file and save them.

              • Modify the ssl_certificate on line 4 (if you are changing the name of the cert than previous)

              • Modify the ssl_certificate_key on line 5 (if you are changing the name of the cert than previous) 

            .
            server {
              listen 443 ssl;
              server_name dataport-test.school.edu;
              ssl_certificate /certs/dataport-test-school-edu.crt;
              ssl_certificate_key /certs/dataport-test-school-edu.key;
              underscores_in_headers on;
              add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
              add_header X-Frame-Options DENY;
              location /idp {
                proxy_redirect off;
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Host $server_name;
                proxy_pass http://dataport:8080/idp;
              }
             
              # if you want to use same host for two environments(TEST. QA and PROD) uncomment this location block and give appropriate container name
             
              #location /idp2{
              #    proxy_redirect off;
              #    proxy_set_header Host $host;
              #    proxy_set_header X-Real-IP $remote_addr;
              #    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              #    proxy_set_header X-Forwarded-Host $server_name;
              #    proxy_pass http://dataport:8080/idp;
              #}
            }
            server {
              listen 80 default_server;
              listen [::]:80 default_server;
              server_name dataport-test.school.edu;
              return 301 https://$host$request_uri;
            }


            • Save the changes in the default.conf file

            wq! (ESC)

            Step 3: 

            • Test NGINX

            nginx -t


            If NGINX does not come back as successful, then do not proceed to the restart of NGINX. A successful output looks like this.

            .

            nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
            nginx: configuration file /etc/nginx/nginx.conf test is successful


            Step 4:

            • Restart NGINX



            service nginx reload


            A successful restart of NGINX looks like this


            [user@dataport-test ~]$ sudo docker exec -it nginx service nginx reload
            [ ok ] Reloading nginx: nginx.
            [user@dataport-test ~]$


            • Exit from the container



            exit


            Step 5: Verify that the NGINX container is running


            sudo docker ps
            • The output should show two containers



            [user@dataport-test ~]$ sudo docker ps CONTAINER ID        IMAGE                                     COMMAND                  CREATED             STATUS              PORTS               NAMES 907b970bfd51        quay.io/nginx                             "/docker-entrypoint.…"   2 months ago        Up 6 days                               nginx a4adc7911498        quay.io/n2ndevops/illuminatedataport:4.4  "catalina.sh run"        4 weeks ago         Up 3 weeks (healthy)    0.0.0.0:8081->8080/tcp   dataport [user@dataport-test ~]$





            Dataport Upgrade - Appendix - 5

            Integration Gateway upgrade using manual steps

            • Login to the VM instance as root

            • To pull N2N’s Integration Gateway image from the N2N private repository (quay.io), please enter Docker login credentials that are obtained from Illuminate. 

            1) Authorization to Access Integration Gateway Docker Images


            Run the below command on the dataport server using the credentials above
            docker login quay.io
            enter the username (grab the username from Illuminate as in the screenshot)
            enter the password (grab the password from Illuminate as in the screenshot)

            2) Find and stop the dataport container

            • Use the following command to show the containers running on the docker



            docker ps



            The container name can be seen by typing in `docker ps` as below. The column name NAMES will let you know the container name.


            3) Save the previous version of dataport
            • This command should be used to take the backup. If your dataport container has an alternate name, put that in place of ‘dataport’.

            docker rename dataport dataport.bk
            • Do this step to validate/compare any custom changes that might have been done to applicationResources.properties, once the new dataport is installed.

            .

            >docker exec -it dataport.bk bash

            >vi webapps/idp/WEB-INF/classes/applicationResources.properties

            >exit


            4) Pull and Run N2N's Integration Gateway image.



            Your network name in the below command could be different.

            • You can get your network name by inspect command as below (the entry will be in the 'Networks' array - see the image below)

              • `docker inspect nginx` ( nginx is the container name)

            Example: Image





            docker pull quay.io/n2ndevops/illuminatedataport:4.10 
            /* To Run this dataport image */
             /*Note: The network name n2ndataport_default should be grabbed some the above note */ 
            docker run --network=n2ndataport_default --net-alias dataport --name dataport -it -d quay.io/n2ndevops/illuminatedataport:4.9.1
            Auto Restart the containers
            • This command helps to auto-restart upon server reboot unless manually stopped.

            docker update --restart=unless-stopped dataport
            • This command then stops the running dataport container. If your dataport container has an alternate name, put that in place of ‘dataport’.

            docker stop dataport.bk (dataport is the container name)



            .

            When you inspect the docker network the new dataport image and nginx should be in the same “Containers” array as shown below image. If you don’t see them in the same network. Check the note above the run command

            • docker inspect n2ndataport_default




            • Test the connection using curl. It should “return a response status as not a valid request.” Note that you need to configure the command below to match organizational nomenclature


            curl -X GET https://{server_name(or)host_name}/idp
            OptionalStep: Remove the renamed running container. Dataport is the container name

            docker rm dataport.bk
            5) Add Database Credentials.

            • Now jump to "Establishing a connection between Illuminate, Integration Gateway, and the SIS Database."





            Was this article helpful?

            That’s Great!

            Thank you for your feedback

            Sorry! We couldn't be helpful

            Thank you for your feedback

            Let us know how can we improve this article!

            Select at least one of the reasons
            CAPTCHA verification is required.

            Feedback sent

            We appreciate your effort and will try to fix the article

            Preview
            0 of 0