Installation or Updating Process

Before you begin

First unzip the provided installation package file to an empty directory.

It is recommended that prior to installation a review of the provided 'README.txt' text file is undertaken to understand any new updated product features or installation details.

If you are performing an update and do not want to save your existing docker images for backout (due to a failure or cancellation of the update process), you can use the "-R" switch to disable the 'recovery' mode. To view all avaliable options use: ./zao_install.sh -h

Next, to install or update ZAO V2.1.1, follow the steps given below:

Note: If you are performing an update to your existing installation, some of the messages below maybe different).

Procedure

Enter the following command from the installation package unzip target location: $ ./zao_install.sh
The output similar to the following appears:
```
Using package installation folder : tmp/__work/
Installing zaoui:2.1.1.0

HCL ZAO V2.1.1.0 GA installation process
starting.
-----------------------------------------------
Verifying ZAO installation dependencies are available.
Host system is running Ubuntu 20.04.1 ( matching Ubuntu
20 ) which is a supported ZAO V2.1.1.0 host operating
system.
Storage driver backing file-system found ( extfs ) matches 
one of the overlay2 supported versions.
Stopping any currently active ZAO docker containers.
No active ZAO zaoui:2.1.1.0 containers found to stop.
No active ZAO beta UI containers found to stop.
No active zaoimport:02.01.01.00-OA60954-ZS120 containers found to stop.
No active ZAO zao-api-sample API sample containers to stop.
No active ZAO hclsoftware/zao-api-service API service containers to stop. 
No active busybox containers found to stop. 

Please wait. Importing docker container images from 
installation package.
```
If you have the ZAO V2.1 ‘beta’ or a previous version installed, then the above messages may also contain:
```
Note - ZAO V2.1 Beta is already installed on this system. 
Switching to 'Update' mode.
HCL ZAO V2.1.1.0 Update process starting. 
Verifying update dependencies are available.
```
The installation script checks that all required dependencies are installed and available on the host system before starting to install the ZAO V2.1.1 files.
If any mandatory dependencies are missing then an error message is displayed, and the package shown needs to be installed before re-running the installation script again. It is recommended that you perform an unzip of the installation package again after correcting the missing dependency.
The following progress messages are displayed:
```
Loaded image: zaoimport:02.01.01.00-OA60954-ZS120
Loaded image: busybox:latest
Loaded image: zaoui:2.1.1.0
```
Note: Update processing may show 'deleted' and 'untagged' messages. This is normal. Also, the APAR reported on the zaoimport image may be different to that displayed above.
```
Do you wish to install the ZAO API container and associated sample? (y/N default=y) : 
```
At this point you need to decide if you are going to want the ZAO API service container and the demo sample to be installed. The API service container provides an API interface to the ZAO repository database with some provided ‘canned’ reports and the ability to submit your own customized SQL queries against a previously imported (via the ZAO UI web interface) repository database.
The sample demo container provides a sample application (with source code) to demonstrate the reporting available through the use of the API service container.
The API demo sample container image can be deleted later if not required. Documentation for the sample can be found in the APISample/ installation folder’s ‘README.1st’ file.
A default ‘Swagger UI’ (documentation link: https://github.com/swagger-api/swagger- ui#documentation) is also available with this container.
Management of the API service is performed through the ZAO V2.1 UI “Admin Tools” web interface.
See the Administration and User Guide for more details on using the swagger UI.
If you wish to install the API service container, press Enter. If you do not wish to install this container, then enter ‘N’(case sensitive) and press Enter.
If you choose to install or update the API service container, similar messages to those below are displayed:
```
Please wait. Importing ZAO API docker image.
Loaded image: hclsoftware/zao-api-service:latest
Please wait. Importing ZAO API demo sample docker image.
Loaded image: zao-api-sample:s390x
Load of the docker API image tmp/__work/api-service.tar.bz2 successful.
rc=0 .
zao-api-sample_s390x can be deleted if desired when the sample is no 
longer required.
Please Note! API Demo sample documentation and source code is available 
in the APISample folder. 
```

Docker Database Volumes

For a new installation the required volumes are created and populated with the needed database and supporting files. The following message appears:

Defining required docker volumes.

If you are updating a previous ZAO V2.1.0.x or ‘beta’ product the follwoing prompt is displayed:

Some/All ZAO Docker volumes are already present.
Replying 'Y' to the following prompt will result in all your 
current ZAO data and configuration settings being deleted 
permanently. Please answer carefully!

Do you wish to re-create the ZAO Docker volumes? (Y/n default=n)

Reply to the prompt (case sensitive) as required, based on your need to keep any previously created database files from the ‘beta’ product.

If you are performing an update and took the default reply, the following messages are displayed:

Skipping creation of ZAO Docker volumes.
Skipping docker DB volume update due to docker volumes
already present.
Please wait, updating ZAO report preprocessing files as 
required. 
f4fbd8f51af9db7ccdb531f05ca25c4a3e16ebd7e857ec1cef1b012c5 
779cb0d
Please wait...stopping busybox work docker container.
copytovol
copytovol

Otherwise, if you requested all docker volumes be re-created, or you are performing an initial install, then all the required docker volumes are created.

Some or all of the following messages are displayed:

zao_database
zao_uploads
zao_logs
zao_tls
Populating docker volumes with required folder structure
and data files.Please wait. 
68d6dde4aae832c3e2b7fb7b63ea13bd98d783d82b0f1907d9ca4ce4a5d2bb5d 
Please wait, updating ZAO report preprocessing files as 
required. 
cf338d1aa1f386e1c449dabab42e08732f745922baf71037c9915ea7eae352a4 
Please wait...stopping busybox work docker container. 
copyreports
copyreports

New installs display the following messages. They are informational only.

Installing ZAO V2.1.1.0 GA . Trial license key is not required or 
supported.
ExtractLicKey: Removing tmp/__work package input folder 
ExtractLicKey: Removing tmp package input folder

HTTPS Support

If you are performing a new installation or you re-created all your docker volumes, then the below messages are displayed next.
For those who have the ‘beta’ or 2.1.0.x installed with HTTPS activated, please skip forward to 'HTTPS Support for Updates' topic.
```
HTTPS - if you have the required SSL/TLS certificate/key (*.pem)
files for https access and wish to use them, please press enter
to the following question, else enter 'N' to skip.
Please consult the provided installation guide for more 
information if required.
Will website access require use of https?  (y/N default=y)
```
At this point, decide if you wish to access the ZAO UI web interface using HTTPS or HTTP. If you do not require the activation of HTTPS support, then please enter “N” (case sensitive) to the displayed prompt and skip forward to the following “Host Name for Web UI” topic.
To use HTTPS, press ‘Enter’ at the displayed prompt.
Now, you are prompted to provide the folder location of the required TLS/SSL certificate and key “pem” files.
```
Please provide the directory path of where your ssl/tls
certificate and key 'pem' files are located: 
```
Note: If you do not have access to the required “cert.pem” and “key.pem” files for configuration of TLS/SSL (for HTTPS access) but want to use HTTPS, then please contact your system or network administrator to get copies of these two (certificate and key) files. If you have different format TLS/SSL files (eg DER files such as .crt .cer, .der ) these can be converted to " .pem" files using linux terminal commands similar to the following :
```
openssl x509 -inform der -in certificate.cer -out cert.pem 
openssl x509 -inform der -in key.cer -out key.pem
```
The installation process expects to find two files for HTTPS activation at the provided folder location. A ‘cert.pem’ file and another named ‘key.pem’ file; each being respectively the certificate and key files.
If you do not have access to these files at this time, you can press enter at this prompt and the https setup process is bypassed. You can then skip forward to the following “Host Name for Web UI” topic.
When you have the “cert.pem” and “key.pem” files at a specific folder location, you can enter the folder location of the files to the prompt.
After which the installation process copies your SSL/TLS ‘cert.pem’ and ‘key.pem’ files to the required docker volume and then prepare to activate HTTPS support. Messages similar to the following are displayed :
```
Copy of HTTPS 'pem' files to required ZAO docker volume completed 
successfully.
copyssl
copyssl 
2b2ea705a65766d8dd2c509fb71846f0ba5677c529123fe14913eb18a45c35ac 
```
You can now skip to the “Required TLS Version Support” topic to continue the installation.

HTTPS Support For Updates

For existing ZAO V2.1.0.x installations upgrading with HTTPS support already activated, the following prompt is displayed:
```
 Do you wish to update the HTTPS/SSL '*.pem' files already present?(y/N default=y)            
```
If you wish to continue using the existing TLS/SSL certificate files, then reply ‘N’ (case sensitive).

If you need to update the TLS/SSL certificate files previously used, reply ‘y’ (case sensitive) to the prompt.

If you replied ‘y’, the below prompt message is then displayed:
```
Please provide the directory path of where your ssl/tls 
certificate and key 'pem' files are located:
```
Enter the relevant folder location details where the required *.pem files are located, and press Enter.
The below success message is displayed indicating a successful copy of the *.pem files has been performed.
```
Copy of HTTPS 'pem' files to required ZAO docker volume completed 
successfully.
copyssl 
copyssl 
68dfadf1bcfe167474014b7a5019d11e012fa9bd976cdb71e4431736e7933fe2
```

Required TLS Version Support

Next the following messages are displayed:
```
Please select the desired MINIMUM TLS version ZAO V2.1.1 will be 
required to support for network connections.
1.	TLS v 1.0 (not recommended)
2.	TLS v 1.1 (not recommended)
3.	TLS v 1.2 (default)
TLS version - Please select from the above options ( default=3 )
```
Please select the desired MINIMUM TLS version clients connecting to the ZAO UI web-interface requires. Using a TLS version that is not recommended can expose the ZAO UI to known vulnerable encryption attacks.

It is highly recommended to accept the default option here unless there are legacy clients needing to connect to the ZAO UI web-interface that cannot support a TLS V1.2 connection.

Once the selection is entered, a message similar to the following is displayed:
```
Please wait.....saving TLS configuration settings.
```

Host Name for UI Web Interface

The following prompt message is displayed:
```
Hostname - Please provide the installation systems hostname 
( default=your.host.name )
```
If the displayed default is not what you want to use, then enter the correct fully qualified host-name. If the default displayed is correct, you can just press Enter to this prompt and continue.

Host Port Number to use for Connections

Depending upon the connection protocol (HTTPS or HTTP), a prompt message is displayed as displayed here:
```
Connection Port Number - Please enter the desired port 
number to use for http(s) Web UI connection
(default=xxxx)
```
If the default port displayed in the message is acceptable, then press Enter. If you wish to use a different port number, enter the port number at the prompt and press Enter.
Next, the ZAO UI container is started. Messages similar to the following appear as the startup procedure is processing.
```
Using hostname:your.host.name with port:xxxx for starting ZAO 
V2.1.0.1 Web UI
Starting ZAO V2.1.0.1 UI using https on host your.host.name
at port xxxx              
```
Those performing an initial installation can skip to the “Installation Final Steps” topic to continue.

Beta and V2.1.0 Data Migration

If you have the ‘beta’ product installed and decide to keep your data, the following messages sappear when the installation process detects any ZAO product database migration tasks are required.

Please wait.... checking for migration 'beta' level ZAO DBs to GA level 
requirement.
2a3ec0bafa192734eea9d3974ae7dcba858860b0157157db3f5b96a366e20e3e Please 
wait....stopping migration process container
Migration of 'beta' level ZAO DBs to GA level completed successfully.

If you are updating a previous V.2.0.x product and decide to keep your existing data, the following messages appear to check if any internal or user account DBs requie updating.

Please wait.... checking for any internal DB migration to V2.1.0.1 level
requirements.
8ebedd0f21709661b309e9903f9e081cf07027d73c9fd4b3eac42484fa7ef0d1 
b8b23103789c718eff310a4d90877173f912790d50d8234c925e9cf10b8999cf 
9983e7177af0361a41f92d384618e08d57cfaca75549e69e0f93cdb7efadc0c7 
Completion of ZAO V2.1.1.0 User DB migration returned rc=0
Please wait....stopping User DB migration process container (ID:9983e7177af0)
Migration of ZAO User DB to V2.1.1.0 level completed successfully.

For those performing an initial installation, the messages displayed above may be different, this is normal and expected.

Installation Final Steps

If you do not see the following message and the prompt, then no ZAO V2.1 ‘beta’ docker images were found on the system and you can skip to the “Installation Completed” topic.
```
Please wait.... locating any installed ZAO 'beta' docker images for
removal
Found docker image 962912ed0016 for nodekoa?? Do you want to remove 
this docker image (y/n default=y) 
```
Otherwise, the preceding prompt is displayed, asking if you would like to remove the 'beta' container image found. Note that the number string displayed may be different.

If you do not wish to keep the ‘beta’ ZAO image, you can reply with ‘y’ (case sensitive) or just press Enter, else enter ‘n’ (case sensitive) to keep the image. If more than one image is found, the message repeats until all the beta images found have been reported.

Installation Completed

At this point, if everything is entered and completed successfully, the ZAO UI web interface container starts, and a string of letters and numbers are displayed along with completion messages as follows:
If you have upgraded from a previous release to the V2.1.1.0 version, you will notice the messages displayed are slightly different to those displayed here:
```
Starting ZAO V2.1.1.0 UI using http(s) on host your.host.com at port
yourport 
e055d40475ebfb1ed95063eb4e7216ad3109a996ac89bae875fb58b239f01737

=======================================================================

Installation of ZAO V2.1.1.0 GA is now complete. Return code = 0
                      
If not already done, please ensure connections are permitted to 
your.host.com at port  <your-port>
Then please connect to the ZAO V2.1.1.0 UI website at 
https://your.host.com:your-port using your favorite internet browser. 
Remember to add/enable a browser exception if you have used a 'self-signed' SSL/TLS certificate.

A sample/skeleton ZAO V2.1.1.0 startup script is available at 
/home/ZAOV2R102/dev/start_ZAOUI.sh 
A sample/skeleton ZAO V2.1.1.0 stop script is available at 
/home/ZAOV2R102/dev/stop_ZAOUI.sh
                
Please consult the provided Installation Guide PDF for your initial admin 
login credentials and the post-installation steps required. 
```
A locally available ZAO UI container start-up and stop scripts are generated and saved as ‘start_ZAOUI.sh’ and ‘stop_ZAOUI.sh’ in the current folder location. You can use these scripts to start or stop the ZAO UI container as required. Please note that only a single ZAOUI container can be run using the provided ‘start_ZAOUI.sh’ script at a time.

You can now proceed to the “First time log on to ZAO V2.1.1 UI” topic to complete the required post-installation steps.