Server - Configuration

 Directory Structure

After the initial installation, the YarraServer folder has the following directory structure:

Path Purpose
fail/ Target folder for failed reconstruction tasks
finished/ Target folder for completed tasks (if data should be kept)
install/ Folder with supplementary files for the installation
log/ Folder for log files
modes/ Folder with definitions of reconstruction modes
modules/ Folder with binaries of core processing modules (shipped with Yarra)
modules_user/ Folder with binaries of custom-developed modules
queue/ Queue directory with incoming reconstruction tasks
webgui/ Folder for the web-based user interface
work/ Working directory for temporary files during processing

By default, these folders are local subfolders in the ~/yarra installation directory. However, if necessary because of a special server configuration, the paths of these directories can also be overwritten in the file YarraServer.ini (see next section). In this way, it is possible, for example, to read the reconstruction-mode files from a remote directory shared across multiple servers, which can make it easier to manage installations with multiple processing servers. Adapting the paths is also necessary when the local drives have been configured such that only limited disk space is available in the home folder for the user yarraserver. Note: To run the server, it is necessary that sufficient disk space is available in the fail, finished, queue, and work folders (disk space in the order of 1TB is recommended).

 

 Main Configuration File

The main settings of the YarraServer are defined in the file YarraServer.ini, which is located in the installation folder /yarra. This file can be edited with any texteditor, e.g. gedit or nano. After changing the settings in this file, it is necessary to reboot the server (see section Usage). Most settings in the file are optional. If they are not set, a default value will be used. To overwrite settings, remove the semicolon in front of the entries and write the desired value behind the equal sign.

The following box shows the default file with descriptions of the possible settings:

;### Configuration file for YarraServer ###
 
;# Note: Most entries in this file are optional and default values will be used.
;# Remove the semicolon in front of the entries to overwrite the defaults.
 
[Server]
;# Unique name for identifying the server 
Name=YarraServer
  
[Paths]
;# Uncomment the following lines to overwrite the default location
;# of the individual Yarra subfolders. Normally, this is not needed. 
 
;Log=/path/to/use
;Modes=/path/to/use
;Queue=/path/to/use
;Work=/path/to/use
;Fail=/path/to/use
;Storage=/path/to/use
;Modules=/path/to/use
 
;# Defines the Matlab binary including path, if installed on server
;MatlabBinary=/path/to/use/matlab
 
[Notification]
;# Defines if notification emails should be sent or not
;Enabled=true
 
;# Email addresses that always should receive an email if a task 
;# reports an error. Multiple addresses can be separated with comma.
;ErrorMail=
 
;# If emails should only be sent to addresses within a certain domain (because
;# of data protection), the domain should be listed here, e.g. @nyumc.org
;DomainRestriction=
 
;# Allows overwriting the sender address that YarraServer is using for notifications
;FromAddress=YarraServer <noreply@localhost>
 
[Options]
;# Set to true if tasks with "night" priority should only be processed during night time
;UseNightTasks=false
 
;# Defines the start of the night time (24-hour notation)
;NightStart=23:00:00
 
;# Defines the end of the night time (24-hour notation)
;NightEnd=05:00:00
 
;# Defines the minimum amount of diskspace (in GB) that needs to be available in the 
;# work, fail, and finished directories. If less diskspace is available, task processing
;# will be halted and an error notification mail will be sent
;DriveSpaceNeeded=20
 
;# Defines a notification threshold for the available diskspace (in GB). If less diskspace 
;# is available, a notification will be sent informing the administrators that processing 
;# will soon not be possible anymore. Reminders will be sent every 4 hours
;DriveSpaceNotificationThreshold=0
 
;# Defines a memory threshold in percentage of the physical available memory. If a 
;# reconstruction module uses more than the specified amount of the available memory, the
;# process will be terminated (to prevent that the server starts servere diskswapping,
;# which could make the server unresponsive). This setting can be overwritten for 
;# individual reconstruction modes
;MemKillThreshold=95
 
;# Maximum allowed runtime for reconstruction modules (in ms). If modules run longer than
;# the specified value, they will be terminated and an error notification is sent.
;ProcessTimeout=86400000
 

 Queue Configuration File

In addition to the main configuration file, the queue directory contains the file YarraServer.cfg, which also contains the name of the server. The purpose of this file is to provide the server information to the Yarra clients. By default, this file is write locked. To edit the file, it is necessary to first change the file permissions to (this should be done when logged in with the user yarraserver):

chmod 640 queue/YarraServer.cfg 
nano queue/YarraServer.cfg

The following shows the content of the file. The settings should matched with the file YarraServer.ini, as described above.

[YarraServer]
Name=YarraServer

After editing the file, the permission should be set back to read-only by typing:

chmod 440 queue/YarraServer.cfg
 

 Installing the Server as Daemon

It is possible to run the server either as normal command-shell application or as Linux daemon (system service). The latter is highly recommended when using the server routinely. When running YarraServer as daemon, it will be started automatically when the server is booted. In addition, it will be automatically restarted in the case that the software should crash for some reason. Running YarraServer as daemon is also necessary when using the Yarra WebGUI.

The configuration of the daemon has changed from previous Yarra versions, as Ubuntu switched from Upstart to systemd for managing daemons (starting with version 16.04).

To install the YarraServer as daemon, open a terminal with administrator rights (admin account). Edit the file yarra.service, which is located in the /yarra/install subfolder. By default, this file should read:

[Unit]
Description=Yarra Server
Documentation=http://yarraframework.com
After=smbd.service
Requires=smbd.service

[Service]
Type=simple
EnvironmentFile=/home/yarraserver/yarra/environment
User=yarraserver
WorkingDirectory=/home/yarraserver/yarra
ExecStart=/home/yarraserver/yarra/YarraServer --force

Restart=on-failure
RestartSec=3

KillSignal=SIGURG
TimeoutStopSec=43800

[Install]
WantedBy=multi-user.target

Depending on the location of your YarraServer installation, it is necessary to adjust the path of the “EnvironmentFile=” file and its content (this file specifies where the Qt binaries are located). It might also be necessary to adapt the “User=” setting if a different user name for running YarraServer is used.

Copy the yarra.service file to the directory /etc/systemd/system (this can only be done using administrator rights):

sudo cp yarra.service /etc/systemd/system

Then, activate the Yarra daemon by typing:

sudo systemctl enable yarra

If the daemon fails to start, you can display the error log using the following command:
journalctl -u yarra

 

Finally, edit file /etc/sudoers by typing:

sudo nano /etc/sudoers

and adding the following lines at the end of the file (this already includes the entries for the WebGUI):

yarraserver ALL = (root) NOPASSWD: /bin/systemctl start yarra, /bin/systemctl stop yarra
yarraserver ALL = (root) NOPASSWD: /bin/systemctl start yarrawebgui, /bin/systemctl stop yarrawebgui, /bin/systemctl restart yarrawebgui

Now, the configuration of the YarraServer is (almost) completed. It is recommended to continue with the installation of the WebGUI.