Sage2-Roll

##Rocks Roll for UIC/EVL's Sage2 software Provides the needed dependencies to run the Sage2 server as well as the server software itself.

Description from a paper on Sage2 (taken from the Sage2 website):

Current web-based collaboration systems, such as Google Hangouts, WebEx, and Skype, primarily enable single users to work with remote collaborators through video conferencing and desktop mirroring. The original SAGE software, developed in 2004 and adopted at over one hundred international sites, was designed to enable groups to work in front of large shared displays in order to solve problems that required juxtaposing large volumes of information in ultra highresolution. We have developed SAGE2, as a complete redesign and implementation of SAGE, using cloud-based and web browser technologies in order to enhance data intensive colocated and remote collaboration.

##Building and Installing

Building

In the main folder of the roll:

Run bootstrap.sh with root permissions to get the needed dependencies to build the roll:

#./bootstrap.sh

To get some source tar files that were too big for Github run:

# make download

This will download the source tar files from the Rocks Cluster's Google Drive and place them in their appropriate locations in the src directory of the roll.

Build the roll using:

# make roll 2>&1 | tee make.log 

If successful, this will build a .iso file called ''Sage2-*.disk1.iso''.

Installation

To install on a node, execute:

# rocks add roll *.iso
# rocks enable roll Sage2
# (cd /export/rocks/install; rocks create distro)
# rocks run roll Sage2 | bash

Then reinstall on the node you want to have the sage server on:

# rocks set host boot compute-X-Y action=install
# rocks run host compute-X-Y reboot

What is installed:

• /opt/Sage2: Sage2 server
• ~/Documents/SAGE2_MEDIA: Images, Videos, Pdfs...etc that are uploaded to the sage2 wall by users.
• /opt/ffmpeg: depencency needed by sage2 to handle video files
• /opt/gcc: version 4.8.2 of the gcc compiler, needed by NodeJS as the version of gcc included in Centos 6 is too old
• /opt/x264, /opt/lame, /opt/libtheora, /opt/libvorbis, /opt/libwebp: Dependencies for ffmpeg
• /opt/tiff: Dependency for Sage2
• /opt/ImageMagick: Dependency of Sage2
• /opt/Image-ExifTool: Dependency of Sage2 for reading exif data of images
• /opt/node: version 4.4.7 of NodeJS, the javascript application framework Sage2 is written in.

##Basic User's Guide

More in depth instructions (not specific to Rocks) can be found at the Sage2 website.

Post Installation

• Inside the main /opt/Sage2 folder, go to the keys directory and edit the servers variable of the GO-linux script with the ip address of the node that will be running the Sage2 server.

• Then run the GO-linux script with:

•   # ./GO-linux  
  

• This will generate the self signed certificates needed for https connections (note, it is always better to use properly signed certificates but this will funciton if you are just trying to get Sage2 to work).

• Now go back to the main Sage2 directory and run the command:

•   # npm run in
  

• This will install all the needed NodeJS dependencies for Sage2

Making a Sage2 Config File

From the Sage2 bitbucket Wiki:

{
host:                            // hostname or ip address of the web server
name:                            // OPTIONAL: name used in some UI (free string, defaults to hostname above)
port:                            // HTTP port that all clients, except web ui, are served on (default: 80)
secure_port:                     // HTTPS port that all clients are served on (default: 443)
rproxy_port:                     // OPTIONAL: port of the HTTP reverse proxy (only required for reverse proxy setups)
rproxy_secure_port:              // OPTIONAL: port of the HTTPS reverse proxy (only required for reverse proxy setups)
url:                             // OPTIONAL: URL shown on display, instead of using hostname (allows for short URL)
background: {
    color:                       // CSS color for the background (hex, rgba(), etc.)
    image: {                     // OPTIONAL: 
        url:                     // relative path from the 'public' directory to an image used for the background
        style:                   // either "fit", "stretch", or "tile"
    }
    watermark: {                 // OPTIONAL: 
        svg:                     // relative path from the 'public' directory to a monochrome SVG image used for the watermark
        color:                   // CSS color for the watermark (rgba() recommended)
    }
    clip:                        // OPTIONAL: boolean, whether or not to clip the display at the exact resolution (default: true)
}
register_site:                   // OPTIONAL: boolean, whether or to register to EVL site (for stats). (default: true)
ui: {
    clock:                       // 12 or 24 (specifies whether to use a 12 or 24 hour clock)
    show_url:                    // boolean, whether or not to show the host url on the display clients
    show_version:                // boolean, whether or not to show the SAGE2 version number on the display clients
    menubar: {                   // OPTIONAL: 
        backgroundColor:         // OPTIONAL: CSS color for the background of the menubar (default: "rgba(0, 0, 0, 0.5)")
        textColor:               // OPTIONAL: CSS color for the text of the menubar (default: "rgba(255, 255, 255, 1.0)")
        remoteConnectedColor:    // OPTIONAL: CSS color for remote sites that are connected (default: "rgba(55, 153, 130, 1.0)")
        remoteDisconnectedColor: // OPTIONAL: CSS color for remote sites that are not connected (default: "rgba(173, 42, 42, 1.0)")
    }
    auto_hide_ui:                // OPTIONAL: boolean, whether or not to autohide wall UI decoration (default: false)
    auto_hide_delay:             // OPTIONAL: integer, number of seconds after which to hide the wall UI (default: 30)
    auto_scale_ui:               // OPTIONAL: boolean, whether or not to automatically scale the wall UI based on resolution and screen dimensions (default: false)
    calculate_viewing_distance:  // OPTIONAL: boolean, calculates the optimal viewing_distance for auto_scale_ui (default: false)
    titleBarHeight:              // OPTIONAL: integer, specify window titlebar height in pixels (default: 2.5% of minimum dimension of total wall)
    titleTextSize:               // OPTIONAL: integer, specify text size of ui titles in pixels (default: 1.5% of minimum dimension of total wall)
    pointerSize:                 // OPTIONAL: integer, specify pointer size in pixels (default: 8% of minimum dimension of total wall)
    noDropShadow:                // OPTIONAL: boolean, whether or not to disable drop shadows on wall UI decoration (default: false)
    minWindowWidth:              // OPTIONAL: integer, minimum width for application windows in pixels (default: 8% of minimum dimension of total wall)
    minWindowHeight:             // OPTIONAL: integer, maximum width for application windows in pixels (default: 120% of maximum dimension of total wall)
    maxWindowWidth:              // OPTIONAL: integer, minimum height for application windows in pixels (default: 8% of minimum dimension of total wall)
    maxWindowHeight:             // OPTIONAL: integer, maximum height for application windows in pixels (default: 120% of maximum dimension of total wall)
    startup_sound:               // OPTIONAL: string, filename to a valid sound file played at startup (wav, mp3, ogg, ... depending on your browser).
}
resolution: {
    width:                       // width in pixels of a display client (browser window width)
    height:                      // height in pixels of a display client (browser window height)
},
dimensions: {
    tile_width:                  // OPTIONAL: width of a single display tile in meters, pixel area
    tile_height:                 // OPTIONAL: height of a single display tile in meters, pixel area
    tile_borders:                // OPTIONAL: mullions in meters, object {left: xxx, right: , top: , bottom: }
    tile_overlap:                // OPTIONAL: overlapping area for edge blending, integer in pixels {horizontal: xxx, vertical: xxx}
    viewing_distance:            // OPTIONAL: preferred or common viewing distance in meters to calculate UI sizes
},
layout: {
    rows:                        // number of rows of display clients (browser windows) that make up the display wall
    columns:                     // number of columns of display clients (browser windows) that make up the display wall
},
displays: [                      // array of displays
    {
        row:                     // the row where this display tiles in the display wall (row origin starts with zero at left)
        column:                  // the column where this display tiles in the display wall (column origin starts with zero at the top)
    },
    ...                          // list length should equal rows*columns
],
alternate_hosts: [               // array of alternate hostnames for machine (i.e. private network IP, localhost, etc.)
    ...
],
remote_sites: [                  // array of remote SAGE2 sites to be able to share content with
    {
        name:                    // (string) name to be displayed on display wall
        host:                    // (string) specify the remote machine to connect with (in conjunction with port)
        port:                    // (number) specify the remote machine to connect with (in conjunction with host)
        secure:                  // (bool)   specify if the URL is a secure connection or not (https vs http)
        password:                // (string) clear text password to connect to the remote site
        session:                 // (string) MD5 hash of the password for the remote site (alternative to password)
    },
    ...                          // list as many remote sites as desired
],
dependencies: {
    ImageMagick:                 // full path to ImageMagick (use "/" as path delimiter, required for Windows only)
    FFMpeg:                      // full path to FFMpeg (use "/" as path delimiter, required for Windows only)
}
}

• In addition you can use the included default-cfg.json and just change the name, layout, resolution, and displays to fit your actual display wall config to get setup quickly.
• For instance if you had a setup of 4 1080p displays arranged in a 2x2 matrix:
  • The resolution section would have a height of 1080 and a width of 1920.
  • The layout would have 2 rows and 2 columns.
  • Lastly you would have four entries in the displays section each with a different row and/or column. For our example you have display row 0 and column 0, row 0 and column 1, row 1 and column 0, and row 1 column 1.

Starting the Sage2 Server

• In the main Sage2 folder, run:

•   # node server.js
  

  This will run the sage2 server process, however it will use the default config file that assumes your display wall contains only a single 1080p monitor, which must be changed if your display wall's configuration differs from this. To change this add the -f flag followed by the path of your custom config file.

• From your front end launch google chrome on each display node by launching a google chrome window (the preferred browser by Sage2's developers) for each monitor in your Sage2 wall:

•   	# runuser -l WALL_USERNAME -c 'ssh -t NODE_HOST_NAME "export DISPLAY=CURRENT_DISPLAY && google-chrome --user-data-dir=~/.config/google-chrome/TILE_CONFIG_PROFILE --kiosk --app=https://SAGE2_SERVER_IP:SAGE2_PORT/display.html?clientID=TILE_ID "'&
  

• You may see a warning about in chrome that the following website is unsecure due to a self-signed https certificate, just click advance and procced to the ip of your sage2 server. You might also want to consider using a properly signed certificate later as well so new users don't have to do this.

• WALL_USERNAME is the username you use to login to each compute node (in mine for instance its sageuser) while NODE_HOST_NAME is the hostname of the compute node (such as compute-0-0) you are logging into.

• CURRENT_DISPLAY is the output of $DISPLAY (assuming each display is it's own x window, which in my experience had alot less issues than with xinerama enabled) which is the monitor that you want to launch one part of your sage2 server on. This also ties in with the TILE_ID as that represents which part of the wall is displayed. For instance if you had a 4 monitor display wall client id 0 might be the top right part of the wall while id 3 is the lower right portion, it depends on your Sage2 config file.

• TILE_CONFIG_PROFILE should be different for each monitor you are launching the sage2 server on as otherwise chrome will complain about having to share the same profile for multiple instances of chrome of the same username.

• The server can be exited by typing exit on the Sage2 sever console.

Interacting with the Sage2 Wall

• In the web browser of your choice (again google-chrome is recommended) go to:

•   # https://SAGE2_SERVER_IP:SAGE2_PORT
  

• If you get the same security warning in your browser as described above, follow the same instructions and proceed to the ip address of your sage2 server.

• Once you are at the main page of the sage2 server, it presents you with a simplified version of what is currently being displayed on the actual display wall with buttons going from left to right on the bottom of the browser window:

  • SAGE2 Pointer takes control of your keyboard and mouse (has to be allowed in your browser settings) so your cursor movments are on the wall itself, this can be exited by hitting the escape key.
  • Screen Sharing (currently for google chrome only with an extension) allows you to broadcast the contents of a window or the whole screen to the display wall from your own computer.
  • App launcher will open a window that shows all the possible apps that come with Sage2 (there is an api that allows you to develop your own as well) and allows limited interaction on this page while the full interaction is on the wall itself while in sage2 pointer mode.
  • Media browser shows a file explorer like window that allows you to launch pdfs, images, video files and more to be displayed on your display wall. In addition, it allows you to drag and drop new files from your desktop to be uploaded to the wall.
  • Arrangment allows you to take whatever is on the display wall currently and either clear it, make it tiled, or save the arrangement for later if it gets changed.
  • The settings button allows you to customize the name that shows up when your cursor goes onto the display wall as well as the color. It also lets you choose the streaming quality if you want to share your screen.
  • Information gives some details on the wall's configuration, the version of sage2, a link to the documentation, and some admin controls.
  • Quick Note and Doodle allows you to place sticky notes on the wall and draw items respectively.

• After activating the SAGE2 Pointer, you can right click to show the radial menu which allows you to do many of the same tasks as the main server webpage but in a format that is better suited to display wall interaction.

• Once you launch an app on the sage wall, right clicking it while using the sage2 pointer will bring up any additional functionality that is available for that app. For instance if a video is playing in the player app, right clicking it will let you pause/play, scrub through, and stop the video currently playing.

##Acknowledgements

• Sage2: This software includes SAGE2(tm) middleware developed by the Electronic Visualization Laboratory at the University of Illinois at Chicago, and the Laboratory for Advanced Visualization and Applications at the University of Hawai'i at Manoa.