GR:Gravity/Installation/Server/IBM i

From Remain Software
Jump to navigation Jump to search

First time Install or Upgrade the Gravity Server on your IBM i machine

This page describes the procedures for the installation or upgrade of the Gravity Server on the IBMi. In the installation procedures we frequently refer to the 'required' Gravity Server. As there can be 3 versions of the Gravity Server it is important that you select the correct version for your installation or upgrade. The 3 versions we have are:

  • Release
  • Milestone
  • Nightly

A release is the final version of the development effort of a Gravity server or client, for example Gravity Server 1.1.0.

A milestone builds on a base development version of a Gravity server/client (for example 1.0.0) with bug fixes and enhancements added. Each milestone builds on the previous milestone and in the end results in a new release (for example 1.1.0). Only the patch (last number) will change with each new milestone for example 1.0.1 -> 1.0.2.

A nightly can be considered as an unfinished milestone (a beta version of a Gravity server/client). It may not be 100% stable and should definitely NOT be used in production.

First Time Installation

First time installation of Gravity on the IBM i assumes you have already installed the TD/OMS change management product.

The installation contains the following steps:

  • Create user GRAVITYDB
  • Create schema GRAVITYDB
  • Run the TD/OMS command to prepare a Gravity environment (INZOMSSRV *GRAVITY)
  • Run the Windows 'Gravity Server for IBMi' installer (or do a manual install)
  • Configure the Gravity server for automatic startup

Create user GRAVITYDB

Log on with QSECOFR and create a user GRAVITYDB. Remember the password. 

CRTUSRPRF USRPRF(GRAVITYDB) PASSWORD(*USRPRF) USRCLS(*USER) INLMNU(*LIBL/MAIN) PWDEXPITV(*NOMAX) TEXT('Gravity Owner') MAXSTGLRG(*NOMAX) JOBD(QGPL/QDFTJOBD) LANGID(ENU) CCSID(37) CHRIDCTL(*JOBCCSID)

Make sure that the user GRAVITYDB has the *USE right to it's own user profile object, if not then the GRAVITYDB user will not be able to access the GRAVITYDB database due to a sign-on failure (server logging will show an error: General security error.:GRAVITYDB).

When Gravity is installed and run for the first time it will be configured to use the database name GRAVITYDB with the password GRAVITYDB. This setup assumes that the user GRAVITYDB actually was created using the password GRAVITYDB. If this is not the case and another password was provided then the password needs to be updated in the GRAVITY configuration file. To update the GRAVITDB password the property 'store.user.password=?password?' needs to be updated with the correct password. The property can be found in the file '_config_admin_config.properties' which is located in the directory '/QOpenSys/TD/Gravity/.data/store'. Note that a password entered in clear text will be automatically encrypted when Gravity is run. Check out the paragraph Updating the password of the GRAVITYDB user further down.

Create schema GRAVITYDB

Logon with the GRAVITYDB user to create a database owned by this user.

  • STRSQL
  • CREATE SCHEMA GRAVITYDB

Change user GRAVITYDB

Log on with QSECOFR and change the initial menu of user GRAVITYDB. 

CHGUSRPRF USRPRF(GRAVITYDB) INLMNU(*SIGNOFF)

Optionally download and Install Java

The minimal java requirement for Gravity is Java 11 or higher.

To ensure that your system has Java 11 run the following commands: 

GO LICPGM
10 Display installed licensed programs

Look for licensed program 5770JV1 with the description Java SE 11 64 bit

If there is no Java 11 installed then ask your IBMi administrator to download and install Java SE 11 support.

Setup the initial Gravity Server environment

Log on with QSECOFR for the Gravity server setup. Add TD/OMS to the library list and run the following command: 

INZOMSSRV SERVICE(*GRAVITY)

The default choice for the Gravity base directory is '/QopenSys/TD'. This will prepare the Gravity Server environment (Gravity Server startup scripts in /QOpenSys/TD/Gravity).

Using the Gravity OSGi Server for IBMi installer

If you are able to use the Gravity Server for IBMi installer then the installer will automate the steps required for a correct Gravity server installation (or upgrade). Make sure FTP client access on your IBMi is enabled and that your FTP User has sufficient authorization to run TD/OMS commands and access the directory /QSysOpen/TD/Gravity.

  • Download the required gravity_server_ibmi_setup-V.R.M.YYYYMMDDHHMM.exe from the website at this location.
  • Run this installer from your Windows workstation, for details on how to use the installer follow this link Gravity Server IBM i Installer

After completion of the installer it may take some minutes for the Gravity Server to complete its startup.

Using the Gravity server zip file

If you cannot use the installer for IBMi then you will need to use a Gravity OSGi server zip file.

  • Download the required gravitysaoserver-lin64-V.R.M.YYYY-MM-DD_HH-MM-SS.zip from the website at this location.
  • Stop the Gravity service with
ENDOMSSRV *GRAVITY
  • Place the zip file in /QOpenSys/TD/Gravity/
  • Start the Gravity service with
STROMSSRV *GRAVITY

After a successful installation the server zip file will have been renamed to include the date and time of the installation as its file extension.

Adding the Gravity service for auto startup

The best way to set up the Gravity service to auto-start is to include the lines below in your TD/OMS subsystem start-up program (source member OMQOMSTRU2 in QUSRSRC) 

  /* ------------------------------------------------------- */ 
  /* Start GRAVITY                                           */ 
  /* ------------------------------------------------------- */ 
  STROMSSRV  SERVICE(*GRAVITY) DB(GRAVITYDB)


Add the line again and compile it. You may need to delete the program first before it can be compiled again (owner). After compilation set the default authority with 

GRTAUTOMS OBJC(OMQOMSTRU2)

The next time the subsystem is started the Gravity server will also be started. If you want to test it you can run: 

ENDSBS OMSTCPSVR *IMMED
STRSBS OMSTCPSVR

Upgrading your Gravity server installation

There are 3 procedures that can be followed here, the first 2 procedures requires TD/OMS to be installed;

  • 1. Using the IBMi Windows installer
  • 2. With TD/OMS installed a manual upgrade
  • 3. Wihout TD/OMS installed a manual upgrade

1. Using the IBMi Windows installer

  • Download the required Windows installer as gravitysaoserver_setup-V.R.M.YYYYMMDDHHMM.exe from the website at this location.
  • Run this installer from your Windows workstation, for details on how to use the installer follow this link Gravity Server IBM i Installer

2. With TD/OMS installed, a manual upgrade

  • Download the required gravitysaoserver-lin64-V.R.M.YYYY-MM-DD_HH-MM-SS.zip from the website at this location.

Upgrade by performing the following steps:

  • Stop the Gravity service with ENDOMSSRV *GRAVITY
  • Copy and or replace the file(s) in /QOpenSys/TD/Gravity/
  • Start the Gravity service with STROMSSRV *GRAVITY

3. Without TD/OMS installed, a manual upgrade

  • Download the required gravitysaoserver-lin64-V.R.M.YYYY-MM-DD_HH-MM-SS.zip from the website at this location. and place it in an IFS directory, for example /Qopensys/TD/Gravity
  • Start the install/upgrade with the script gravityserver.qsh

To make sure your installation can perform the upgrade you need the following files in the installation root directory: gravityserver.qsh and update.qsh. If you do not have these files then they can be extracted from the downloaded zip file, use the qshell command 'jar -xvf ?name-of-zip?.zip update.qsh gravityserver.qsh'. Gravityserver.qsh will run the update.qsh and start Gravity. Make sure the user access properties on the zip file allow the user running the gravityserver.qsh script to read and move the zip file (i.e. you might need to change the permissions and owner of the zip file). When the zip file is placed in the installation root directory and gravityserver.qsh is run then the zip is renamed and unpacked, when unpacking is finished the zip is renamed once more (with a date and time at the end) and gravity will be started based on what was just unpacked. The gravityserver.log will contain information about the upgrade process.

Run any required post upgrade steps

Depending on what is in the release notes, an additional upgrade step might be required to get the Gravity server into a fully updated state. For more information on post upgrade steps goto Server Post Upgrade Steps

Problems after upgrading the Gravity Server

After a correct upgrade the Gravity Web client should be accessible after a few minutes. Test this by opening the main Gravity Web page using URL: 

http://?host:port?/gravity/wm

On the displayed page you should be able to login into Gravity using the administrator's user id and password. 

Also on the displayed page you can check the server version by hovering over ‘Powered by Remain Software Gravity’ (near the bottom of the page), this will show the Gravity database version and build time.

If the Gravity Server is not starting after an upgrade then it could be that ports previously in use by Gravity, are pending close. These ports are no longer used by Gravity but are still semi active. Restarting Gravity usually resolves this issue, perform the following steps:

  • Stop the Gravity service with ENDOMSSRV *GRAVITY
  • Wait 5 minutes
  • Start the Gravity service with STROMSSRV *GRAVITY

If you still cannot login to Gravity using a Web browser then you will need to contact Gravity support.

Updating the password of the GRAVITYDB user

Updating the Gravity template or final properties file will be necessary if the password of the GRAVITYDB user is not 'THE' default password or the password has changed. In this case the correct password needs to be set in either the Gravity template properties file or the final properties file. The property to be updated is 'store.user.password=...' If the server was already started then you need to edit the final properties file else the template properties file.

Run the following command to edit the final properties file: 

 EDTF STMF('/qopensys/TD/GravitySave/.data/store/_config_admin_config.properties.org')

Run the following command to edit the template properties file: 

 EDTF STMF('/qopensys/TD/Gravity/_config_admin_config.properties')

When the server starts for the first time, the properties file in the root of the server is copied to the .data/store directory (the final location). Also, any plain text password in the final properties file will be encrypted by the Gravity server. If a password was updated in the template properties file then after server startup either mask the property or remove it from the file.

Note: Long IBM i passwords are case sensitive!

Gravity Server in a DR environment

There are 2 aspects of Gravity that need attention when planning for a Gravity DR. First is the progam files side of Gravity and second is the data files side of Gravity. Both aspects can be handled in different ways depending on the situation at hand. The most easiest way to replicate a Gravity instance is to stop it (ENDOMSSRV *GRAVITY) and copy it to another location and to make sure you can start the DR Gravity instance with a 'STROMSSRV *GRAVITY' command. If it is not possible to stop the Gravity production instance then see the instructions below on how to replicate the different parts of Gravity.

Gravity Server program

The Gravity server program consists of all files and directories located in the root Gravity directory but not including the top level directory ‘.data’. These files can be safely replicated to a new location as no files are being locked with an update in mind. If you cannot replicate then you also have the option of providing a base Gravity server installation consisting of the Gravity server zip file and 2 scripts required to get the server running. The root Gravity server directory will then look something like this: 

update.qsh
gravityserver.qsh
gravitysaoserver-lin64-3.0.1.2017-09-18_12-47-08.zip

Having these three files is enough to get the Gravity server application started with the command ‘SRTOMSSRV *GRAVITY’. The file ‘gravitysaoserver-lin64-3.0.1.2017-09-18_12-47-08.zip’ is for example the zip file as available from the Remain site. It also possible to use the current production zip file as was used to install the latest Gravity server on your IBMi. The zip file is stored in the root Gravity directory and will look similar to the following file: ‘gravitysaoserver.zip.170919-110159’. This zip file is the same as the download zip file but on install (by Gravity scripting) it is renamed to contain the day of installation and the .zip extension is moved from the end of the file name. When the file is renamed to once more contain the .zip extension it can be used for a Gravity server installation, ‘gravitysaoserver.zip.170919-110159’ should then become ‘gravitysaoserver.170919-110159.zip’.

Gravity Server data

In the root Gravity server directory there is the ‘.data’ directory. This directory contains all the essential Gravity configuration and runtime data. If you run Gravity with the embedded H2 database then the database will also be located in this directory, but in most cases on the IBMi the IBMi DB2 database is used and is external to any Gravity directory. Replicating the ‘.data’ directory can only be safely done when the Gravity server is not running. The main reason for this is that replicating the ‘.data/solr’ directory of a running Gravity server can result in corrupted Solr lucene indexes in the target environment (these indexes contain Gravity search information). If you need to replicate/copy the ‘.data’ directory of an active Gravity server instance (live copy) then you can do this by excluding the solr sub directory. On the DR side you can re-populate the indexes with the Gravity OSGi console command grsolrri (see Wiki: Gravity; Rebuild Search Index). The Gravity OSGi console can be accessed through the Gravity web settings page (requires admin rights).

Below is a list of sub-directories contained in the .data directory: 

Directory		Required 	Live copy allowed
------------		------------	-----------------------
(.data/)cassandra	no		no
(.data/)logs		no		yes
(.data/)public*         no		yes
(.data/)resources	yes		yes
(.data/)solr		yes		no
(.data/)store		yes		yes
(.data/)work**		yes		yes
(.data/)xref***        	yes		no

*public contains cached versions of document attachments.

**live copy allowed only if not using the embedded H2 database.

If advised not to run the cassandra caching server due to resource limitations, then the caching server can be disabled with the Gravity configuration setting: 

caching.server.disable=true

***the xref contents do not necessarily have to be replicated, the xref locations will be automatically recreated but this can take some time depending on the number of locations configured.

Note. The store directory contains, amongst others, the all important Gravity configuration file: _config_admin_config.properties. The file contents are primarily static by nature but the entries server.contact.name and store.server.name can change if the same ip-address (i.e. numeric dotted address) is used to configure these properties. These 2 properties will be updated with the actual host ip-address detected during server startup. Again these 2 properties may change if an ip-address is used not if a (DNS) host name is used. If the DR store configuration is going to be updated with diverging port, ip-address or host name values then make sure the configuration is usable (port conflicts) when replicated back to the original installation.

The directories that have the indication Required: no, do not need to be copied at all. These directories will be recreated upon server startup.

Gravity Server License

On a failed over Gravity server, the license check will most likely fail and a new licenses will need to be installed. Licensing will fail if the host name and or the Gravtiy server installation directory changes. The Gravity server will still be functional with an invalidated base license but only the user 'admin' will be able to login. When requesting a new license use the Gravity admin RCP to lookup the system-id of the Gravity server, the system-id will be required when generating a new license.

Tuning Gravity DB2/400 Driver

When Gravity is running on the AS/400 we can tune the DB2 JDBC driver with the following java command line properties:

"-Dgravity.jt400.use.native.driver=<true>"

This property only has effect when running the server on OS/400. Make sure that the database is on the same system as the server when using "true" for this property, otherwise the results cannot be predicted.

"-Dgravity.jt400.query.optimize.goal=<value>"

Setting to specify that you want to change the DB2/400 optimization goal.

0 = Optimize query for first block of data (*ALLIO) when extended dynamic packages are used; Optimize query for entire result set (*FIRSTIO) when packages are not used.

1 = Optimize query for first block of data (*FIRSTIO)

2 = Optimize query for entire result set (*ALLIO)


The default is "0". Nothing will be set if this property is not specified.

"-Dgravity.jt400.qaqqini.lib=<value>"

Setting to specify from what library to use the qaqqini file. See the documentation for as400JDBCDatasource