Deploy in production VM - KostasMparmparousis/uLookup GitHub Wiki

  1. Before you proceed with anything else, you need to check if the service functions as expected in localhost, for that specific institution, i.e you need to Build with Dependencies and Run with the following command:
java -jar uLookup.jar -i institution_name -m local            (either from terminal or an IDE)
  1. Then you need a production VM for that specific institution:
  • If one does not exist, standard procedure is we request one from ViMa.
  • If one does exist however, we can reuse the already existing one.
  1. You need to create and send a Certificate Signing Request(CSR) to the institution, which they will approve.The sequence differs depending on the Root CA that specific institution uses:
  • HARICA: Login using your account via Academic Login, select Server Certificates->Request new certificate and fill the upcoming forms. Then the certificate will automatically be sent to the Institution's admin. But, you need to keep the certificate's key! When the admin signs the certificate, you will be notified to login again and retrieve it. After the approval, the certificate need to be retrieved within a week.
  • TERENA: Create the CSR via the following command openssl req -new -key ulookup.key -out ulookup_cert.csr \ -subj "/C=GR/ST=Athens/O=GUnet/OU=GR/CN=ulookup.xxx.gr", and send the ulookup_cert.csr via email to the admin. Again, you have to save the certificate's key! Then the admin has to approve the request and send you back the signed certificate.

There is a possibility where you receive a list of signed certificates, and it's up to you to determine which one to use. In that case, you can use the following commands, in order to find out the correct certificate. This needs to be done, or else the service won't be able to start via Apache when deployed.

  • openssl x509 -noout -modulus -in ulookup_xxx_yyy.zzz | openssl md5
  • openssl rsa -noout -modulus -in ulookup.key | openssl md5

If the 2 values match, save the certificate with the name "ulookup_cert.pem". When its all said and done, you should have the 2 following files stored in a directory for that institution:

  • ulookup.key (certificate key)
  • ulookup_cert.pem (signed certificate)

(The following steps can be followed concurrently and with no particular order, especially if you put the VM's IP in your /etc/hosts.)

  • Given your VM's IP, ask the institution to include a record that matches the IP to ulookup.xxx.gr in the institution's DNS. Meanwhile and for testing purposes, you can temporarily match the IP to that name by adding a record in your /etc/hosts/.

  • Send the required files to the production VM and start the service. You can send every file via scp manually if you so wish, however that would not be very efficient. Below you can see the method I personally use, feel free to optimize it as you wish.

You will need to have the following 2 sub-directories (institution_name/, template/) with the structure demonstrated below, as well as the script sendTar.sh, all located in the same directory.

directoryName/institution_name/

├── certificates                              (ssl certificates)
│   ├── ulookup.key
│   ├── ulookup_cert.pem

├── configs                                   (apache configurations)
│   ├── (empty)

├── conn                                      (connection details)
│   ├── institution_name.properties
│   ├── institution_name_hrms.properties 
│   ├── institution_name_hrms2.properties
│   ├── institution_name_ds.properties

├── resources                                 (html-css resources)
│   ├── (empty)


├── tokens                                    (authentication Tokens)
│   ├── webAccessKey 
│   ├── apiAccessKey

directoryName/template/

├── certificates                              (ssl certificates)
│   ├── (empty)

├── configs                                   (apache configurations)
│   ├── 000-default.conf 
│   ├── 000-empty.conf 
│   ├── 000-empty-ssl.conf 
│   ├── default-ssl.conf 
│   ├── security.conf 
│   ├── ulookup-redir.conf 
│   ├── ulookup-ssl.conf 

├── conn                                      (connection details)
│   ├── (empty)


├── resources                                 (html-css resources)
│   ├── static (directory)


├── tokens                                    (authentication Tokens)
│   ├── (empty)


├── deployment.sh                             (deployment script)
├── ulookup.service                           (apache service)

Before proceeding, if the production VM already has a working ulookup service, it might be a good idea to stop it before continuing, after connecting to it via ssh:

rm -r uLookup-deployment*
systemctl stop apache2
systemctl stop ulookup

Continuing on, while inside the mentioned directory in your computer, you should run the script sendTar.sh using the institution's name as an argument:

./sendTar.sh institution_name

The script will send the compressed file uLookup-deployment.tar.gz with all the necessary files to the production VM. Finally, you can connect to it and simply execute the following commands with the service deploying itself.

mkdir uLookup-deployment && tar -xf uLookup-deployment.tar.gz -C uLookup-deployment

./uLookup-deployment/deployment.sh institution_name

You will most likely be warned if something goes wrong with the installation, however you can check if the installation has been deployed using systemctl status ulookup.