Skip to end of metadata
Go to start of metadata

A Windows Powershell script (supporting Windows 7 and above) can be downloaded and used to speed up and facilitate the setup of oBIT on the client machine. It collects enough information to download, extract and configure all oBIT components.

Download

Download the latest release of the installation script from https://github.com/aarpon/obit_installer/releases/latest.

Run

The installer script requires administrator rights. Start Windows PowerShell or Windows PowerShell ISE as an administrator and then type the following at the prompt.

PS C:\Windows\system32> C:\path\to\obit_installer\obit_installer.ps1

where C:\path\to\obit_installer is the path to the extracted obit_installer folder.

"PS C:\Windows\system32>" is the PowerShell prompt. Do not type this, only what follows.

Alternatively, the installer can read the configuration file (.json) generated by a previous installation to set the default options:

PS C:\Windows\system32> C:\path\to\obit_installer\obit_installer.ps1 -configFile C:\path\to\obit_settings.json

In this case, all questions (see below) will be asked, but the imported parameters will be used if nothing else is specified. The value of the imported parameter will be shown as follows:

Installation directory [C:\oBIT]:

Just press the enter key to accept the default. Please notice that some parameters will have defaults even if no file is specified.

An obit_setting_{hostname}.json file is saved at the end of an installation and can be reused for the next. Alternatively, a template can be obtained from here:

{
    "openbis_host_port":  "",
    "local_user":  "openbis",
    "installation_dir":  "C:\\oBIT",
    "annotation_tool_acq_type":  "Microscopy",
    "datastore_dropbox_path":  "/path/to/dropbox/folder",
    "platform_bits":  64,
    "user_folder":  "D:\\toOpenBIS",
    "datamover_service_name":  "Datamover",
    "java_path":  "C:\\oBIT\\jre",
    "datastore_host":  "openbis.example.com",
    "openbis_host":  "openbis.example.com",
    "accept_self_signed_certs":  "no",
    "datamover_data_folder":  "D:\\Datamover",
    "settings_file_version":  1,
    "datastore_user":  "openbis",
    "datastore_lastchanged_path":  "/path/to/lastchanged",
    "use_existing_java":  "N"
}

By default, Windows does not allow running unsigned scripts. To run obit_installer, execute the following as an administrator in PowerShell:

Set-ExecutionPolicy Unrestricted

After installation, restore the original execution policy as follows:

Set-ExecutionPolicy Restricted

Step-by-step setup instructions

In the following, some or all questions (depending on whether a settings file is used) are followed by a default value in square brackets, e.g.:

Do you want to setup oBIT on this machine? (y/n) [Y]

Just hit the return key to accept the default.

We will now go through one run of the script and discuss all options.

Execution mode

This obit_installer script can be used to download, install and configure all components of the openBIS Importer Toolset on the machine where the script is run, or it can be used to prepare the setup for a target machine that does not have internet connection. The target machine can optionally be of different architecture (e.g. 32 bit instead of 64).

The first question asked by the installer is the following:

Do you want to setup oBIT on this machine? (y/n) [Y]

If you answer Y, oBIT is set up on current machine. If not, all packages are downloaded into the selected installation directory (see below) to be used on another machine.

Setup preparation for a target machine

If you replied N to the previous question, you will be asked:

Is the target machine 32 or 64 bit? [64]: 

By default, the architecture of the target machine is picked to be the same as the one currently running the script, in this case 64 bit.

Installation directory

This is the directory where oBIT will be installed, or the directory where all components will be downloaded when preparing the setup for another machine.

Installation directory [C:\oBIT]: 

This defaults to C:\oBIT, but you can place it wherever you want.

Java runtime

If you have an existing Java 8 runtime installation, you can use that. Otherwise, the Amazon Corretto OpenJDK will be downloaded and installed in the selected installation directory.

Use existing Java installation (y/n) [N]:

This defaults to downloading a new JRE from Amazon AWS.

oBIT configuration

These are specific configuration parameters for your environment.

[1] Local folders and users

Annotation Tool user data folder

This is the folder where the users save or export their data to be registered to openBIS.

Annotation Tool user folder [D:\toOpenBIS]:

Datamover data folder

This is the folder monitored by Datamover (as a Windows service).

Datamover data folder [D:\Datamover]:

For performance and stability reasons, it is highly recommended to set the user folder and the Datamover folder on the same, local hard drive!

Local Datamover as a Windows service user

Datamover is run as a Windows Service on the machine by a specified user. It is recommended to choose a user on the machine that is dedicated to this task. If the user does not exist yet, it will be created.

Local user to run Datamover as a Windows service [openbis]:

[2] openBIS configuration (AS)

openBIS host

This is the openBIS application server host: the one users point their browser at to access openBIS.

openBIS host:

This is something like openbis-scu.ethz.ch.

openBIS host port

This is the port on which openBIS listens for connections. If the openBIS AS handles the connections (as is the case in a standard installation), the port would be 8443. If openBIS is served by a web server (e.g. apache), then there might be a port redirection from port 80 to 8443 and then this would be left undefined.

openBIS host port (optional):

If the port is left undefined, the openBIS URL will be something like:

https://openbis-scu.ethz.ch/openbis

If the port is defined, then the openBIS URL will be something like:

https://openbis-scu.ethz.ch:8443/openbis

[3] Datastore Server (DSS) configuration

Datastore server host

This is the datastore server that hosts the dropbox folder to which the Datamover as a Windows Service pushes the data to be registered.

Datastore server host [openbis-scu.ethz.ch]: 

By default, the datastore server is set to be equal to the openBIS (AS) server.

Remote datastore user

The obit_installer script configures Datamover to transfer data to the remote Datastore Server (DSS) via secure copy (scp). Here you have to choose the remote user that will be needed to login via public key authentication. See also below.

Remote user to login to the Datastore server [openbis]:

Please notice that local and remote users do not strictly need to be the same: The local user logs in as the remote user on the DSS.

Dropbox folder on the datastore server

This is the full path to the dropbox folder on the datastore server.

Full path to the data folder on the Datastore Server (parent to the data store and the dropbox folders):

On a standard installation, this would be something like /home/openbis/openbis/data and would contain the actual dropbox folders, such as incoming-microscopy, incoming-lsrfortessa, ...

Path to the 'lastchanged' executable

This is an optional replacement for the GNU find command. If you want to use it (recommended), there will be some preparation steps to be performed.

In the obit_datamover_jsl\bin installation folder you will find a 64-bit executable that you can use; alternatively, in obit_datamover_jsl\datamover\src folder you will find a lastchanged.c C source file. You can compile it on the Datastore server as follows:

$ gcc -O3 -Wall lastchanged.c -o lastchanged

Copy it somewhere (e.g., /usr/local/bin) and set the full path to it (e.g. /usr/local/bin/lastchanged):

Full path to the 'lastchanged' executable of Datamover on the Datastore server (optional): 

[4] Annotation Tool

Acquisition station

Here you have to pick one of the two supported classes of acquisition hardware that the Annotation Tool supports so far:

Select the acquisition station or type the Annotation Tool is going to manage:
    [1] Flow cytometry
    [2] Microscopy
Your choice: 

In case of Flow cytometry, one additional step is required:

Pick the machine:
    [1] BD LSR Fortessa
    [2] BD FACS Aria
    [3] BD Influx
    [4] Biorad S3e
    [5] Beckman Coulter MoFlo XDP

Acquisition friendly machine name

By default, the machine name will be set to the network hostname. Here you can provide a more informative (and friendly) name for the acquisition station (for instance: Spinning Disk 1):

Specify a friendly and informative acquisition station name (if omitted, the hostname will be used) [bs-acqs01]:

Accept self-signed certificates

If your server runs on a self-signed certificate, you will have to force the Annotation Tool to accept connecting to it.

Accept self-signed certificates? (y/n) [N]:

Checking/creating local user

If the selected local user exists, it will be used by oBIT. If it does not, you can create it now. You will be asked to provide a password (and retype it for confirmation). The user will be created.

Downloading packages

The packages for the selected platform will now be downloaded. If they are found in the installation directory already, they will be used instead. This will be the case if you are performing an installation of oBIT that you prepared on another machine (see Execution mode above).

Found file C:\oBIT\0.2.0.zip. No need to download.
Found file C:\oBIT\datamover-15.06.0-r34542.zip. No need to download.
Found file C:\oBIT\obit_annotation_tool_2.0.0_64bit.zip. No need to download.
Found file C:\oBIT\amazon-corretto-8.222.10.3-windows-x64-jre.zip. No need to download.

In contrast, if you are preparing an installation for a target platform, the installation will end after download.

As requested, we stop here. The downloaded files are in C:\oBIT.

Extracting packages

The packages are extracted.

Configuring packages

The installer uses the entered information to configure the downloaded and extracted oBIT components.

Installing Datamover as a Windows Service

Public key authentication

Datamover as a Windows Service moves data from the local Datamover data folder to the dropbox folder on the Datastore server via secure copy. For this, password-less public key authentication must be set up. The installer gives you the choice between using an existing key pair or to create a new one.

[U]se existing or [C]reate a new key pair? (U, C) [U]:

By default, you can Use an existing key pair. In this case, you will have to paste the content of your private key into the obit_datamover_jsl\datamover\bin\home\{dss_user}\.ssh\key file. If you haven't done it yet, you must also add the content of the public key file to the authorized_keys file of the DSS user on the Datastore server (something like /home/openbis/.ssh/authorized_keys).

Alternatively, you can Create a new key pair: the generated keys (key and key.pub) will be put in obit_datamover_jsl\datamover\bin\home\{dss_user}\.ssh. Now you or an administrator must add the content of the public key file key.pub to the authorized_keys file of the DSS user on the Datastore server (something like /home/openbis/.ssh/authorized_keys).

You can find more information: Install Datamover as a Windows service#SettingUpDatamover and here: https://help.ubuntu.com/community/SSH/OpenSSH/Keys

The installer will restrict access to the obit_datamover_jsl\datamover\bin\home\{dss_user} folder to the dss_user only to prevent exposing you private ssh key!

(Optional) Log in to the remote server via ssh

To make sure the connection works and the client stores the remote machine as a known host, it is recommended to log on to the remote machine at this stage.

Do you want to try logging-in to the openbis-scu.ethz.ch now? (y, n) [Y]: 

Please follow the instructions on screen carefully:

Please follow these instructions.

Please run 'cmd.exe' or 'powershell.exe' as the 'openbis' user and type the following:

cd C:\oBIT\obit_datamover_jsl\datamover
bin\win\ssh.exe openbis-scu.ethz.ch

This will log in remotely as 'openbis'.

If you get the following:

The authenticity of host 'openbis-scu.ethz.ch' (XXX.XXX.XX.XXX) can't be established.
RSA key fingerprint is ...
Are you sure you want to continue connecting (yes/no)?

Please reply 'yes'. You should get:

Warning: Permanently added 'openbis-scu.ethz.ch,XXX.XX.XX.XXX' (RSA) to the list of known hosts.

Type 'exit' at the prompt to leave the server.

Press ENTER when you are done: 

Your paths and server names might be different.

Installing and configuring the service

Name of the Datamover as a Windows service [Datamover]:

By default, the Datamoer as a Windows service will be installed as 'Datamover', but the name is configurable in case you want to have more than one service running in parallel. If a service with the given name is already installed, you will be asked if you want to remove it. If you don't, please be aware that its setting might not be compatible with those you just defined for the new installation.

After installation, you still have to perform one manual step. The installer will open services.msc for you. 

Select the Datamover service, select Properties, change to the 'Log On' tab, type the password of the local Datamover user and click OK. If this is the first time you install Datamover as a Windows Service, this will grant the user the rights to run Windows services. In any case, you must type the correct password.

Now you can start the service.

If you did not correctly set up public key authentication, or if some of the settings were wrong, the service might fail. Please look at the log file in ...\obit_datamover_jsl\datamover\log\datamover_log.txt for hints.

  • No labels