SeaDAS-OCSSW Client Server Configuration

Introduction

The SeaDAS processing components (OCSSW) can be installed only on Linux or macOS (Intel) systems. For this reason, it has been difficult for Windows users to use the OCSSW programs in an efficient way. SeaDAS 8.1.0 and future releases use a client/server model, which enables the physical decoupling of the SeaDAS GUI application and the OCSSW package. (Note SeaDAS 8.0.0 was a Beta version and did not support client/server model. SeaDAS 7.5 also supports client/server model)

Since the SeaDAS client and the OCSSW server reside on two separate machines, they need a way to share files. They can either transmit the files over the network or use a shared folder. For virtual machines, we can use a shared folder and eliminate the transmission of files over the network.

OCSSW Server Installation

The OCSSW server provides access to OCSSW programs through web services. The web services are packaged as an independent JAR (Java ARchive) file and can be deployed on a machine (real or virtual) capable of running OCSSW programs. With this new capability, we have additional options that enable SeaDAS to access to OCSSW programs:

Install Docker Desktop for Windows and run SeaDAS Science Processors via the Docker image.
Install a Linux virtual machine (e.g. VirtualBox) on the same Windows machine that has the SeaDAS GUI installed
Install the Windows Subsystem for Linux (WSL - available for Windows 10) on the same machine
Install the web services package on any Unix or MacOS machine that provides network access to other computers

In this manual, we explain how to configure the OCSSW server and the SeaDAS client for each scenario.

Section 1: Installing an OCSSW Server

Click for instructions:

Follow these instructions to install Docker Desktop.
Please make sure that you have created a valid .netrc file in your home directory ($HOME) and also copy it into the $HOME/seadasClientServerShared/ directory..
Under your $HOME directory, create the "ocssw" and "seadasClientServerShared" directories if they don't already exist. (NOTE: You can create these directories anywhere that you have full permission to operate. You have to provide the full path later)

For example,

> cd

> mkdir ocssw

> mkdir seadasClientServerShared

Make sure Docker Desktop is running before running the following command in Windows Power Shell's command line:


docker run -v $HOME/ocssw:/root/ocssw -v $HOME/seadasClientServerShared:/root/seadasClientServerShared -p 6400:6400 -p 6402:6402 -p 6403:6403 -t seadas/ocssw-run:2.0

Skip to Section 4: SeaDAS Client Configuration.

For this option, we are using Oracle's VirtualBox software. (Other VM software may work, but we have only tested VirtualBox using an Ubuntu 20.04 server configuration)

Install Oracle VirtualBox from https://www.virtualbox.org/
Install the Ubuntu 20.04 server on the VM. This involves creating a Linux Ubuntu guest virtual machine. For SeaDAS 8.x, we used Ubuntu 20.04 LTS. (Check out this helpful video.)

Set up VirtualBox Guest Additions on GUI-less VM server

$ sudo mount /dev/cdrom /media/cdrom  
$ cd /media/cdrom  
$ sudo apt-get install -y dkms build-essential linux-headers-generic linux-headers-$(uname -r)  
$ sudo su  
$ ./VBoxLinuxAdditions.run  
$ reboot  
$ lsmod | grep -io vboxguest  
$ sudo usermod -aG vboxsf

Create a shared folder
- Create a folder on the Host computer (Windows) that you would like to share, for example: C:\Users\${username}\seadasClientServerShared
- Boot the Guest operating system in VirtualBox.
- Create a folder on the Guest computer (Ubuntu) that you would like to share, for example: ~/seadasClientServerShared
- Select Devices → Shared Folders...
- Choose the 'Add' button.
- Select C:\Users\${username}\seadasClientServerShared in the "Folder Path" and name it, for example, "seadasClientServerShared", in the "Folder Name"
- Optionally select the 'Make permanent' option
Prepare the shared folder
With a shared folder named "seadasClientServerShared", as above, the folder can be mounted as the directory ~/seadasClientServerShared with the command:
$ sudo mount -t vboxsf -o uid=$UID,gid=$(id -g) ocssw_shared ~/seadasClientServerShared
If you experience any problem with setting up a shared folder, please visit Ubuntu Help pages for shared folder setup.

Visit the Microsoft website and follow instructions to Install WSL and a supported Linux distribution (Ubuntu was used during testing).

The client and server share the whole disk.

Obtain a suitable networked Linux server

The client and server DO NOT have a shared disk.

Section 2: Configure the Virtual or Real Machine

Set up Java:

$ sudo add-apt-repository ppa:webupd8team/java  
$ sudo apt update 
$ sudo apt install oracle-java##-installer  
$ sudo apt install oracle-java##-set-default

Replace ## with the version number. (e.g. 12 ...tested with 8, 10 and 12, should work with later releases as well)

Install python (3.6 or higher):
```
$ sudo apt install python
    
```
Install git:
```
$ sudo apt install git
    
```

Section 3: Deploy the OCSSW Web Services Package

The OCSSW Web Services Package consists of two files than need to be downloaded to the server machine. For our example we will put them in the home directory.

.jar file -
- The jar file is a self-contained webserver and multiple web services that access various OCSSW programs.
config,/var> file - VM | WSL | RM The configuration file provides crucial information for establishing communication between the OCSSW server and the SeaDAS client.

We have not had success with openJDK for this server JAR, so you will need to install the official Oracle Java package - step #1 under "Configure the Virtual or Real Machine" above.

OCSSW Configuration File

In each environment, ocsswserver.config will differ slightly. Click to see an example.

Not Applicable

    ocsswrest.version=1.0
    baseUriPortNumber=6400
    ocsswroot=${user.home}/ocssw
    serverWorkingDirectory=${user.home}/seadasClientServerShared
    clientServerSharedDir=true
    keepIntermediateFilesOnServer=false
    processInputStreamPortNumber=6402
    processErrorStreamPortNumber=6403

    ocsswrest.version=1.0
    baseUriPortNumber=6400
    ocsswroot=${user.home}/ocssw
    serverWorkingDirectory=/mnt/c/Users/${username}/seadasClientServerShared
    clientServerSharedDir=true
    keepIntermediateFilesOnServer=false
    processInputStreamPortNumber=6402
    processErrorStreamPortNumber=6403

${username} is your Windows username, not WSL username (unless you set them to the same value).

    ocsswrest.version=1.0
    baseUriPortNumber=6400
    ocsswroot=${user.home}/ocssw
    serverWorkingDirectory=${user.home}/seadasClientServerShared
    clientServerSharedDir=false
    keepIntermediateFilesOnServer=false
    processInputStreamPortNumber=6402
    processErrorStreamPortNumber=6403

The config file properties related to port numbers and the folders are essential and should match the values in the client configuration file. Please see the "SeaDAS Client Configuration" section of this document for the corresponding client configuration properties and their values.

Starting and Stopping the OCSSW Server

To start the OCSSW server, execute the following command:


$ java -Xmx4G -jar seadas-ocsswserver.jar ocsswserver.config

To stop the OCSSW server, press Ctrl + C.

Section 4: SeaDAS Client Configuration

To configure the client to communicate with the server, the SeaDAS config file needs to be edited.

${user.dir}\.seadas9\etc\seadas.properties

Click an environment to see which lines to edit in the seadas.properties file:

   seadas.ocssw.location=docker
   seadas.ocssw.port=6400
   seadas.ocssw.sharedDir=C:\\Users\\${user.name}\\seadasClientServerShared
   seadas.client.id=${user.name}
   seadas.ocssw.keepFilesOnServer=false
   seadas.ocssw.processInputStreamPort=6402
   seadas.ocssw.processErrorStreamPort=6403

   seadas.ocssw.location=virtualMachine
   seadas.ocssw.port=6400
   seadas.ocssw.sharedDir=C:\\Users\\${user.name}\\seadasClientServerShared
   seadas.client.id=${user.name}
   seadas.ocssw.keepFilesOnServer=false
   seadas.ocssw.processInputStreamPort=6402
   seadas.ocssw.processErrorStreamPort=6403

   seadas.ocssw.location=virtualMachine
   seadas.ocssw.port=6400
   seadas.ocssw.sharedDir=C:\\Users\\${user.name}\\seadasClientServerShared
   seadas.client.id=${user.name}
   seadas.ocssw.keepFilesOnServer=false
   seadas.ocssw.processInputStreamPort=6402
   seadas.ocssw.processErrorStreamPort=6403

   seadas.ocssw.location=remote server IP addess
   seadas.ocssw.port=6400
   seadas.client.id=${user.name}
   seadas.ocssw.keepFilesOnServer=false
   seadas.ocssw.processInputStreamPort=6402
   seadas.ocssw.processErrorStreamPort=6403