JRodos Installation Guide

Version 2.1 for JRodos February 2017 onwards

Ukrainian Centre for Environmental and Water Projects

Karlsruhe Institute of Technology, Institut für Kern- und Energietechnik

February 2017

2

Contents

LIST OF ACRONYMS................................... ..................................................................3

WHERE CAN I FIND DOCUMENTATION OR GET MORE INFORMAT ION? ...............4

WHERE AND HOW CAN I RUN JRODOS?.................... ...............................................4 System components, single and distributed installations, supported Operating Systems.....................................4 Minimum requirements for single installations........................................................................................................4 Minimum requirements for distributed installations. ..............................................................................................5

JRodos Data Base Server, separate...........................................................................................................................5 Client and Server for standard applications ..............................................................................................................5

Server.............................................................................................................................5 Client .............................................................................................................................5

Client and Server with LASAT and large grid .........................................................................................................5 Server.............................................................................................................................5 Client .............................................................................................................................6

What is needed to run JRodos (aka prerequisites)?.................................................................................................6

JRODOS INSTALLATION SUMMARY ........................ ..................................................7

POSTGRESQL + POSTGIS ...........................................................................................8 Fresh PostgreSQL-PostGIS installation. Windows users. .......................................................................................9

PostgreSQL...............................................................................................................................................................9 PostGIS Manual Installation...................................................................................................................................14 PostGIS installation via the StackBuilder...............................................................................................................18

Fresh PostgreSQL-PostGIS installation. UNIX users. ...........................................................................................21 PostgreSQL.............................................................................................................................................................21 PostGIS...................................................................................................................................................................22

DOWNLOAD AND UNPACKING OF JRODOS RELEASE PACKAGE... ....................26

JRODOS SERVER CONFIGURATION ........................ ................................................27

CONFIGURING JRODOS SERVER ON A *NIX MACHINE WITHOUT PREINSTALLED GRAPHICAL PACKAGE .................................. ............................................................30

INSTALLING JRODOS SERVER AS A WINDOWS SERVICE/LINUX DAEMON .......32 1. Installing service/daemon .....................................................................................................................................32 2. Managing on Windows..........................................................................................................................................32 3. Managing on Linux ...............................................................................................................................................32

THE FIRST JRODOS RUN...........................................................................................33 1. Starting the JRodos Server...................................................................................................................................33 2. Starting the JRodos Client....................................................................................................................................33 Shutting down JRodos ..............................................................................................................................................34

DOCUMENT HISTORY.................................................................................................35

3

List of Acronyms *NIX UNIX-like operating system

aka also known as

HTML Hypertext Mark-up Language

Java Object oriented programming language

Linux Open Source UNIX-like operating system

OS Operating System

SQL Structured Query Language

<JRodosServer> The folder, where server installation is made

<JRodosClient> The folder, where Client installation is made

4

Where can I find documentation or get more informat ion? NOTE: This document as well as the Users’ Guide, the Customization Guide and other JRodos related guides is located in <JRodosClient>/documents/ and <JRodosServer>/documents/. The text versions in both folders are identical. Please, use the pages accessible via https://resy5.iket.kit.edu/ for getting additional information on the project as well as for participating in the development. Issues and requests can be filed through the Bugzilla engine accessible via https://resy5.iket.kit.edu/; please see also the chapter on "Filing a bug and closing a bug in Bugzilla" in the JRodos User Guide. NOTE: You have to register at these sites; this will also help in finding additional information on the product., and in contributing to the development of the product.

Where and how can I run JRodos?

System components, single and distributed installations, supported Operating Systems

JRodos can be installed as a single installation on one PC/Workstation, or as a distributed installation with the Server and the Client residing on separate machines. In the document, hardware requirements are provided for the single installation as well as separately for the Server part and Client for a distributed installation. In addition, the data base can be installed at a separate PC/Workstation. Only one instance of JRodos Server is allowed to be run on a specific machine. On the contrast, several JRodos Clients can be started and logged in with different JRodos users to the same JRodos Server. Parallel Clients can be started from the same physical machine. The system is known to run on Windows 2000 up to Windows 8.1, generic Linux machines not older than year 2005 (Gentoo, Oracle Linux, Ubuntu, OpenSuse, Fedora etc.). From the JRodos July 2014 release onwards, the 64bit Server part has become the supported version. The client part is 64bit by default, but can be reconfigured to use the local 32bit Java Runtime Environment (JRE). This is a pre-condition for any operating system Linux or Windows.

Related to the hardware, Intel processors are preferred as their performance for mathematical operations are optimal.

Minimum requirements for single installations Such a configuration is usable for straightforward applications, fast testing of components, or the demonstration of particular functionalities independent of the performance of the system. Some use cases (e.g. LASAT) might require other hardware.

5

Processor quad core RAM 4 GB Hard drive 200 GB OS Linux or Windows (64 Bit)

Minimum requirements for distributed installations Mixed case for OS is supported, e.g. DB on 64bit Linux, Server on 64bit Linux and Client on 32bit Windows.

JRodos Data Base Server, separate Processor quad core RAM 4 GB Hard drive 2 TB, preferably 15K rpm, preferably RAID1 array to mirror

information OS Linux or Windows (64 Bit)

Client and Server for standard applications

As standard application, the emergency model chain with the standard models (without LASAT) and the standard grid (named BfS grid with about 8000 points) is assumed.

Server Processor quad core + n cores; n is the number of clients with

simultaneous connections RAM 4 GB + 2*n GB, n is the number of clients with simultaneous

connections Hard drive 1 TB, preferably 15K rpm, preferably RAID1 array to mirror

information OS Linux or Windows (64 Bit)

Client Processor 2 core; quad core is preferred RAM 4 GB Hard drive 500 GB Video Card Modern Video Card (e.g. Nvidia GT 740) OS Linux or Windows (64 Bit)

Client and Server with LASAT and large grid

The large grid with more than 100000 points and the particle model LASAT require specific hardware. As LASAT requires many resources, a multi-processor system is recommended and one processor should be dedicated to one LASAT instance.

Server

Processor quad core + 4*n cores; n is the number of clients with simultaneous connections

RAM 32*n GB, n is the number of clients with simultaneous connections Hard drive 2 TB, preferably 15K rpm, preferably RAID1 array to mirror

information

6

OS Linux or Windows (64 Bit)

Client

Processor 2 core; quad core is preferred RAM 4 GB Hard drive 500 GB Video Card Modern Video Card (e.g. Nvidia GT 740) OS Linux or Windows (64 Bit)

What is needed to run JRodos (aka prerequisites)? The JRodos system uses the Sun Java Runtime Engine (Sun JRE) 6 update 19 or later for data management and representation and the PostgreSQL database engine version 9.x with corresponding PostGIS extension for data storage (technically, the system supports versions 8.2 and up + PostGIS 1.4 and up). A preconfigured JRE for Windows and Linux users is distributed with the JRodos system and does not require a special installation procedure.

7

JRodos installation summary Freshly installing JRodos on a PC not equipped with a PostgreSQL and/or PostGIS engine requires the following six steps:

1. Install PostgreSQL.

2. Install PostGIS.

3. Unpack the archive with the JRodos Server installation. Let's call that installation folder <JRodosServer>.

4. Unpack the archive with JRodos Client installation. Let's call that installation folder <JRodosClient>.

5. Configure the JRodos Server.

6. Run the JRodos Server and Client.

NOTE: If there is already a running PostgreSQL engine on the computer you want to use for JRodos DB deployment, the corresponding PostgreSQL and/or PostGIS installation steps can be skipped.

NOTE: For data migration from existing PostgreSQL 8.* to new PostgreSQL 9.* please see the Administration guide.

8

PostgreSQL + PostGIS If you already have a running instance of PostgreSQL engine on the machine you want to use in DB deployment, you may skip the corresponding chapters on installation of PostgreSQL and/or PostGIS. In such cases proceed directly to the chapter “JRodos Server Configuration”.

NOTE: Since 2015 all JRodos releases supported the latest PostgreSQL 9.x version. Previous JRodos releases worked only with PostgreSQL 8.2+ version. For instructions on installing a 8.2+ version, please refer to document InstallPostgreSQL_8.x .

NOTE: You have to know the host, port and the password of the “postgres” DB user! On local installation host port are usually localhost and 5432. Please consult your system administrator in case you want to reuse a PostgreSQL instance.

Installation packages are available for download at http://www.enterprisedb.com/products/pgdownload.do Users of Windows and *NIX platforms may use the corresponding installer. Alternatively, installers are available per sftp from a special account on resy5 (folder resy5.iket.kit.edu:/general/jrodos/reqs/).

NOTE: For details about the account please contact the KIT JRodos team.

NOTE: Linux 64bit users should use 64bit PostgreSQL and PostGIS installers! Windows 64bit users can also use 32bit binaries.

9

Fresh PostgreSQL-PostGIS installation. Windows users.

PostgreSQL 1.1. Download the latest Windows installer from

http://www.enterprisedb.com/products/pgdownload.do

1.2. Launch the downloaded binary.

� Next

10

� Next

� Next Use the following password for the postgres superuser: model_postgres Enter a complex password if the Windows complains t his one is too simple.

� Next Stick to the default port number.

11

� Next Select the English, United States locale.

� Next

12

� Next

� Next

13

From now you can choose between two options, depending on how you are willing to install the PostGIS software: manually or via the StackBuilder . OR For manual installation of PostGIS Using the StackBuilder to install PostGIS.

Leave the check box blank. Put the check into it.

NOTE: Advanced users and system administrators may configure the installed PostgreSQL to be used from remote machines. For this two files in the DB Data folder should be changed: pg_hba.conf and postgresql.conf . You will need to restart PostgreSQL server to apply changes. Please consult PostgreSQL documentation.

14

PostGIS Manual Installation

2.1. Run the latest PostGIS 2.x release for PostgreSQL 9.x. For previous version please refer to InstallPostgreSQL_8.x guide.

� I Agree Choose the PostGIS component.

� Next

15

The folder has to be the same as the one, where PostgreSQL has been installed. The default folder path is shown in the picture:

� Next 2.2. The superuser name, password and port number have to be the same, as used during PostgreSQL installation. The default name, password and port number according to this guide are postgres , model_postgres and 5432 respectively.

� Next

16

� Install

If the following dialog boxes appear, choose Yes:

17

(Да = Yes / Нет = No)

(Да = Yes / Нет = No)

(Да = Yes / Нет = No)

� Close

18

PostGIS installation via the StackBuilder. Choose the PostgreSQL 9.* on port 5432 option. Configure proxy servers if needed.

� Next In the depicted tree find the following component and put a check in the corresponding box:

Categories � Spatial Extensions � PostGIS 2.x Bundle for PostgreSQL 9.x v2.x.x.

� Next

19

� Next Wait for the component to be downloaded from the Internet.

20

� Next

The following steps are the same as during PostGIS Manual Installation. In the end you will see a window, informing you, that the PostGIS has been successfully installed under the StackBuilder.

21

Fresh PostgreSQL-PostGIS installation. UNIX users.

PostgreSQL 1.1. Download the installer for Linux from

http://www.enterprisedb.com/products/pgdownload.do

NOTE: Since 2015 all JRodos releases supported the latest PostgreSQL 9.x version. Previous JRodos releases worked only with PostgreSQL 8.2+ version. For instructions on installing a 8.2+ version, please refer to InstallPostgreSQL_8.x document..

1.2. Under root user run the downloaded binary file. Follow the instructions, listed in

the Installing the PostgreSQL under Windows section. The installation folders’ paths will be different; the rest of the windows will look essentially the same. The default directory is opt/PostgreSQL/9.x.

NOTE: When prompted choose en_US.utf8 as the Locale.

At Unix servers without already installed X Server libraries the PostgreSQL and PostGIS setup programs will be executed in the command line. Make your decisions on the analogy with the dialog windows of the visual installers.

NOTE: The installer needs the Kerberos5 library to be installed in the system. This is generally true for the latest *NIX distributives (openSuSe 10.0+, Ubuntu 8.x). Check if you have a file /usr/lib/libkrb5.so.3 . If not, please install this library with a corresponding system installation tool (Synaptec, YAST, emerge etc.). NOTE: Advanced users and system administrators may configure the installed PostgreSQL to be used from remote machines. For this two files in the DB Data folder should be changed: pg_hba.conf and postgresql.conf . You will need to restart PostgreSQL server to apply changes. Please consult PostgreSQL documentation.

22

PostGIS At Unix servers without already installed X Server libraries the PostgreSQL and PostGIS setup programs will be executed in the command line. Make your decisions on the analogy with the dialog windows of the visual installers. PostGIS can be installed manually or via the StackBuilder . To install PostGIS manually run edb_postgis_2_x_pg9x.bin under the root user. First steps (server and application selection, downloading) in PostGIS installation via the StackBuilder are the same as for Windows users. But during actual PostGIS installation screens differ from Windows version. libpng12 is required for PostGIS.

� Next Leave checkbox unchecked.

23

� Next Installer auto-detects PostgreSQL server installation. Enter the same password as used during PostgreSQL installation. The default password according to this guide is model_postgres .

� Next

24

If the following dialog boxes appear, choose Yes:

� Next

25

� Finish

26

Download and unpacking of JRodos Release package (a) Download the latest JRodos Release package per sftp from a special account

on resy5 from folder resy5.iket.kit.edu:/release/.

NOTE: For details about the account please contact the KIT JRodos team.

(b) The installation of the JRodos program consists of two parts: JRodos Server and JRodos Client. Extract each of them to the machine you want to use.

In the case where both Server and Client shall be used within one PC, both parts can be extracted into the same folder.

NOTE: Please do not forget about the access rights: unpack to the folder fully accessible to all potential users.

(c) Special considerations

Windows users

(1st) Utilizing the WinZip or the Windows Zip Folders software at Windows machines may incorrectly unpack the archives. The free 7zip or the commercial WinRar are recommended.

(2nd) JRodos components should not be unpacked into <Program Files> folder, as only a Windows Administrator is allowed to perform changes in this folder. Both Client and Server part has a subfolder Log/ where logs are saved, thus the files are constantly changed.

(3rd)From our experience it is neither a good idea to unpack both JRodos components into the root partition where Windows OS is installed, i.e. to have C:\JRodosServer\ and C:\JRodosClient. JRodos then works ok, but a calculation becomes 3-4 times slower than usual.

Most probably Windows spends additional resources to analyze the activity in these folders. The slow behavior is gone when an additional first level folder is introduced, e.g. C:\JRodos\JRodosServer and C:\JRodos\JRodosClient

Unix users

Make sure the files <JRodosServer>/*.sh and <JRodosClient>/*.sh have executable rights.

NOTE: JRodos uses a specially preconfigured Java Runtime Engine version 7. That means that a Java installation is not required .

27

JRodos Server configuration Step "Configure JRodos Server" is for defining and setting up the default JRodos Data Base. The step is only required on a completely fresh JRo dos installation, or if the default JRodos Data Base shall be installed on inte ntion. If you replace an existing installation and want to keep the information in the JRodos program and user data bases from the previou s installation, then

− SKIP the Server configuration step

Instead, from the previous installation, COPY file "server.config" from <Server>\Manager\ to the same position in the new installation. For a description of this file please see the JRodos Customization Guide.

− IN ADDITION, you may have to re-install files with customized items that became

overwritten by the fresh installation

For more information, please see the JRodos Administration, Chapter "Taking care of customized items on updates or new releases".

In addition, it may be necessity to make some specific corrections; such actions would be then described in the release notes.

If you do carry out the Server configuration step, then:

1. Make sure that all JRodos related components are shut down and the PostgreSQL server is up and running.

2. On a machine where JRodos Server component is deployed, run <JRodosServer>/ConfigureJRodosServer.*

The "JRodos Server Configurator" menu is described on next page.

28

(a) Identify the Server PC in field (1), either by a fully qualified name or by IP address. You can test the correctness of the entered information by pressing the check button (2). IMPORTANT! In case of several networks use the one in which JRodos shall be used.

(b) Enter PostgreSQL server connection details in fields (3). You can check the correctness of the entered info by pressing button (4).

(c) Put the path to store the heavy results on the filesystem (5). Do not check "Store in DB" if you plan to use many calculations and/or expect to be able to access the results from a 3rd party GIS software!

Since year 2015 JRodos store the heavy calculation results on a filesystem, not in the Database. This prevents heavy DB traffic and allows additional functionalities.

NOTE: For migration step from the existing "pure DB storage" approach to the mixed "DB + filesystem" see JRodos Administration guide

(d) Enter a password for the JRodos DB user into fields (6).

(e) Select is full restore of JRodos DBs should be executed (7).

• To fully restore, select “Complete restore”. This option should be used when JRodos is installed for the first time, or to clean all JRodos databases.

1 2

3

6

4

5

7

29

Then, press “Apply”. If any errors are reported please double check steps 1-4. On successful execution close the dialog with "Close".

30

Configuring JRodos Server on a *NIX machine without preinstalled graphical package

Before executing the Server configuration make sure that all JRodos related components are shut down and the PostgreSQL server is up and running. On a machine where JRodos Server component is deployed, run <JRodosServer>/ConfigureJRodosServer.sh -noui.

NOTE: –noui argument has to be the first one in the command line after binary file name ConfigureJrodosServer.sh. If you want JRodos server configuration dialog to be in English, specify the –en argument among command line arguments besides –noui , for example :<JRodosServer>/ConfigureJRodosServer.sh -noui -en

1. The configuration console version will start. The program will attempt to read the default configuration parameters from file <JRodosServer>/Manager/configuration.properties. The default parameters values according to this guide are:

Parameter name in configuration.properties file

What the parameter stands for

The default parameter value

server.url JRodos Server host 127.0.0.1 (localhost) postgresql.host PostgreSQL server host 127.0.0.1 (localhost) postgresql.port PostgreSQL server port 5432 postgresql.superuser PostgreSQL superuser postgres postgresql.password Password to the

PostgreSQL DB superuser account

model_postgres

jrodos.password JRodos DB user password jrodos complete.restore Is the “Complete restore”

option on? false

postgresql.template PostGIS 1.x template template_postgis sqlite.db To store the results in the

DB or not false

sqlite.path Path to keep the model result files

<thisJRodosServer>/Engine/SQLite

NOTE: Edit the configuration.properties file before starting the configuration script if your settings differ from the defaults listed in the table above.

2. The configuration program will consecutively per form the following steps:

a) Validates the server.url parameter value. If it’s not present in configuration.properties file, the file cannot be opened or it doesn’t correspond to a reachable net address, the configurator will offer you to type the fully qualified name or the IP address of JRodos Server host. IMPORTANT! In case of several networks utilize the one in which JRodos shall be used.

b) The program will carry out a verification of the PostgreSQL server connection details. If one or more values among the host address , the port number and

31

the PostgreSQL DB superuser password are absent in configuration.properties file, or the configurator cannot establish a connection to the PostgreSQL server according to these details, the program will prompt you to enter all 3 parameters from console (the password to the PostgreSQL DB superuser account twice ).

c) Configurator will check if the JRodos DB user password is specified in configuration.properties file. If there's no user password in the file you will be prompted to enter the password from console (twice ).

d) If the corresponding value hasn’t been found in the file you will be asked to specify whether to enable “Complete restore” option. This option should be used when JRodos is installed for the first time or to clean all JRodos databases. Type true or false , the input is case insensitive.

e) For PostgeSQL 8.x installation if the corresponding value hasn’t been found in the file you will be asked to specify PostGIS template name.

NOTE: Enter QUIT if you experience difficulties entering the necessary parameters values during steps (а) –(e) or want to exit the configuration program due to some other reasons.

NOTE: If secure work with JRodos and PostgreSQL server is an issue erase the postgresql.password and jrodos.password entries in the configuration.properties file.

3. Wait for the program to apply JRodos server conf iguration parameters after completing steps (a) – (e).

In the end you will see a message, informing you of all the tasks having been performed successfully.

32

Installing JRodos Server as a Windows service/Linux daemon

1. Installing service/daemon Perform the following steps:

1. Configure JRodos Server and check its operability.

2. Download the stable version of yajsw from http://sourceforge.net/projects/yajsw/files/latest/download and unzip. Let’s call unzipped directory <yajsw>.

3. Open file <JRodosServer>/JRS.conf and replace <JRodos path> by the value of <JRodosServer> (full path to the folder, where server is installed) in two places (wrapper.java.command and wrapper.working.dir). Then, copy JRS.conf into <yajsw>/conf directory.

4. Go to the <yajsw> folder using console under administrator access and type command: java -jar wrapper.jar -i conf/JRS.conf

5. The installation is complete, the JRodos Server service/daemon is ready to use.

To start JRodos Server service/daemon: java -jar wrapper.jar -t conf/JRS.conf

To stop JRodos Server service/daemon: java -jar wrapper.jar -p conf/JRS.conf

Or use a standard OS tools (see below).

If you need to remove the JRodos Server service/daemon, use the command:

java -jar wrapper.jar -r conf/JRS.conf

2. Managing on Windows Open console with administrator access and use next commands:

• To start JRodos Server service: sc start JRS • To stop service: sc stop JRS • To uninstall service: sc delete JRS • To see the full list of possible commands just type: sc

Or it can be managed by launching "Services" from the Windows Control Panel → Administrative Tools or typing "Services.msc" in console with administrator access. Choose needed service and select an option (start/stop/restart) on context menu.

3. Managing on Linux Open terminal with root access and use next commands:

• To start JRodos Server daemon: service JRS start • To stop daemon: service JRS stop • To uninstall daemon use yajsw (see above).

33

• Do not forget to enable service during start up.

- To enable services across runlevels in Debian, Ubuntu, and other Debian based Linux distributions use a script: update-rc.d JRS defaults

- Red Hat, Fedora, and Red Hat based Linux distributions such as CentOS

make use of the script chkconfig First add the service using chkconfig script. Then turn on the service at the desired run levels: chkconfig JRS --add chkconfig JRS on --level 2,3,5 This will enable the JRodos Server to automatically start in the run levels 2, 3 and 5. Run the command chkconfig --list JRS to check this.

•

The first JRodos run

1. Starting the JRodos Server For starting JRodos firstly you must start the JRodos-Server by executing - on the machine where the JRodos Server is deployed - <JRodosServer>/JRodosServer, depending on the OS used.

The start process is completed when the message "Server is running" appears in the JRodosServer window. Note: On first start, this may take some time (up to several minutes, depending on the computer).

NOTE: For each JRodosServer run a corresponding log is saved in <JRodosServer> /Manager/Log/ folder as a separate file with the name corresponding to the start time stamp.

2. Starting the JRodos Client When the Server is running, you have to start the JRodosClient by executing - on the machine where the JRodos Server is deployed - <JRodosClient>/JRodos.cmd, depending on the OS used.

NOTE: For each JRodosClient run a corresponding log is saved in <JRodosClient>/Client/Log/ folder as a separate file with the name corresponding to the start time stamp.

The JRodos login window appears, asking for the user name and password, and an IP-address or a name for the computer where the JRodos Server is running.

A predefined login/password is admin/admin (in lower case characters), which gives you administrative access to JRodos.

34

For the server location, use the machine name for the JRodos Server, which you indicated in the Server Configuration dialog. Note : A pre-defined server location is localhost for use if JRodos is not implemented as a distributed system.

Note to the Server specification : If no name is present in the drop-down list for the Server location in the Combo-Box, or an invalid address, please enter a valid address in the respective field. After successful validation the entered address is stored and appears next time in the Combo-Box.

Shutting down JRodos

For a complete shutdown / restart of the JRodos system you have to exit both the JRodosClient (first) and the JRodosServer (last).

35

Document History Document Title: JRodos Installation Guide Version and status: Version 2.1 (draft) Issued by: UCEWP History: Version 2.0 (draft) JRodos February 2017 Version 1.7 (draft) Version 1.6 (draft) Version 1.5 (draft) Version 1.4 (draft)

Version 1.3 (draft) Version 1.2 (draft) Version 1.1 (draft) Version 1.0 (draft)

Date of Issue: 06 April 2017 File Name: JRodos_Installation_v200.doc