ReviewStudio

1. Introduction

1.1 Version

2.1 Requirements

2.2 Installation

3.1 HTTP server port

3.2 Session storage

3.3 Session API


5. Server Setup and Cross-Origin Resource Sharing

5.1 Proxy server requirements

5.2 Example nginx configuration



ReviewStudio Documentation

Server Integration Guide

1. Introduction

The ReviewStudio Collaboration Server handles the real-time communication for the ReviewStudio component.

1.1. Version

Guide for version 1.0.

Back to top

2. Installation

2.1. Requirements

Erlang R15B
You can download it here: otp_src_R15B.tar.gz.
Untar and build with the instructions found in the README file in otp_src_R15B or online installation guide.Before installing make sure that the openssl development package is installed, otherwise the required ssl and crypto Erlang modules will not be available and the ReviewStudio Collaboration Server will not run. On most Linux distributions the package is called openssl-devel but on Ubuntu it is called libssl-dev. On Red Hat Linux distributions you can use the yum software package manager:

sudo yum install openssl-devel

and on Ubuntu you can use apt-get:

sudo apt-get install libssl-dev

After installing Erlang make sure erl is in the PATH for you and root.

NOTE that using your Linux package manager will most likely install a different Erlang version and the installation will fail.

Python 2.5 or higher
Most likely installed. The installer requires Python 2.5.*, but 2.6 or 2.7 versions should work as well.
sudo permission
The default install directory is /etc/iceserver which requires root permission to write to. The installer will also try to update /etc/inittab (old init services starter) or add an upstart configuration file to /etc/init.

2.2. Installation

    1. Unzip installation:
      unzip iceserver-id-version.id.zip
    2. Go into directory created by unzip:
      cd ./iceserver-id-version.id
    3. Build components:
      python ./install.py build

      If you get a SyntaxError it means you are running Python 2.4, you need at least Python 2.5.

    4. Install ReviewStudio Collaboration Server:
      sudo python ./install.py install

      This will copy the ReviewStudio Collaboration Server files to the /etc/iceserver directory and update /etc/inittab or install an Upstart file /etc/init/iceserver.conf and start the server automatically.
      If your server does not support inittab or Upstart you can run the ReviewStudio Collaboration Server with the /etc/iceserver/runICEServer script and stop it with /etc/iceserver/stopICEServer.

 

By default the ReviewStudio Collaboration Server will run on port 8080, you can test it: http://localhost:8080/ or if port 8080 is inaccessible (because of firewall software and such) try on the installation machine:

wget http://localhost:8080/

The page should mention ReviewStudio Server and its version.

The default installation directory is /etc/iceserver. Run

python ./install.py --help

to see all the options to the installer.

Back to top

3. Configuration

The configuration is defined in /etc/iceserver/iceserver.config. It is an Erlang configuration file, see Erlang config for more info.

A quick Erlang config syntax tour:

                  %% Erlang comment, the rest of the line is ignored
"string"          %% a string
port              %% an atom, a constant, must be lower case
12345             %% an integer
[1, 2, 3, 4, 5]   %% a list of integers
{port, 8080}      %% a tuple, a tuple consisting of an atom and a value
                  %% is often called a property
[{prop1, "val1"},
 {prop2, ["val2.1", "val2.2"]},
 {prop2, "val2"}] %% a list of tuples, when all the tuples are of the
                  %% form {atom, value} it is often called a property
                  %% list. As you can see a value can be a list of
                  %% values as well, or even another property list

3.1. HTTP server port

The default HTTP port is 8080. If you want to run the ReviewStudio Collaboration Server on a different port, port 80 for instance, you have to change the port property of the inets httpd configuration. Search /etc/iceserver/iceserver.config for HTTP server port and change 8080 to the port number you want, for instance to port 80:

{port, 80},

To minimize firewall issues we suggest you run the ReviewStudio Collaboration Server on port 80.

If you want to run the ReviewStudio Collaboration Server on a machine that is already running another web server you can not use the same port (if you do you the ReviewStudio Collaboration Server will most likely not start, with some error mentioning eaddrinuse). To solve this you can run both servers on separate ports and use a proxy server like nginx to send some URLs to the ReviewStudio Collaboration Server and all the other URLs to your web server.

3.2. Session storage

File storage

By default the ReviewStudio Collaboration Server will store the collaboration session annotations to files on disk (in the /etc/iceserver/data directory).

CMS storage

You may prefer to store the annotations in your CMS. You can do this by specifying a URL from your CMS as session parameter in your item definitions of your ReviewStudio HTML pages. The ReviewStudio Collaboration Server will do an HTTP GET request to that URL to get the XML data and expect a HTTP 200 response with XML data in the body (possibly empty). When all the clients are done and leave the ReviewStudio HTML page, the session annotations will be HTTP POSTed to the same URL. The POST body will contain multiple values encoded as “multipart/form-data” HTTP data. The values are:

session
The session, should be the same as the URL.
changers
A comma separated list of the userids of users that changed something.
markup
The annotations, as XML.

The ReviewStudio Collaboration Server does not allow arbitrary URLs, only URLs from configured servers are allowed. The servers are configured through the servers property in the ReviewStudio section of the iceserver.config file. By default localhost is allowed:

{servers, ["localhost", "127.0.0.1"]},

If your CMS is http://yourhost.com/ then add:

{servers, ["yourhost.com", "localhost", "127.0.0.1"]},

The ReviewStudio Collaboration Server does exact matches, so if your CMS is on a subdomain (including wwww) it has to be specified exactly:

{servers, ["www.yourhost.com", "localhost", "127.0.0.1"]},

Note that the ReviewStudio Collaboration Server does not know about the authentication system of your CMS and does not send any cookies on the GET/POST requests. This means that the CMS must allow anonymous access to these session URLs. This is usually undesirable. One easy solution is for your CMS handler to check the incoming IP address is the IP address of your ReviewStudio Collaboration Server.

Alternatively you can hide the CMS URL by configuring them in the ReviewStudio Collaboration Server instead of session property of the ReviewStudio item. You can configure the URL with get_data_url property in the ReviewStudio section of the iceserver.config file. In the URL definition you can use the %(session)s pattern to refer to the session. For instance, say the item is identified in your CMS as http://www.yourhost.com/folder1/subfolder1/item1 and annotations is the sub path to the annotations of every item. Then you could specify folder1/subfolder1/item1 as the session for your item in ReviewStudio, and configure the ReviewStudio Collaboration Server as such:

{get_data_url, "http://www.yourhost.com/%(session)s/annotations"},

If you need a different URL to store the annotations you configure the post_data_url as well, for instance:

{get_data_url,  "http://www.yourhost.com/%(session)s/get_annotations"},
{post_data_url, "http://www.yourhost.com/%(session)s/post_annotations"},

Note that these URLs still will not get any authentication, so it is ‘security through obscurity’ and it is still advisable to do the IP address check.

CMS notification

If you do not want to store the session annotations in your CMS you can still be notified when changes are made to the annotations. You configuration the notification URL through the notify_url property, again you can use the %(session)s pattern to refer to the session of the ReviewStudio item. To follow the get_data_url setup it could be:

{notify_url, "http://www.yourhost.com/%(session)s/notify"},

3.3. Session API

GET /session/{session_name}

Retrieves the currently stored session xml data for {session_name}. Please note that the session data is only stored once all collaborators have left a session. Requires “Basic Authentication” header, see http://en.wikipedia.org/wiki/Basic_access_authentication. You can configure the server (user,password) in cozimo.config, under the cozimo section:

{cozimo,[
  {basic_auth, [{"username", "password"}, {"username2", "password2"}]
  , %% other erlang config parameters
}

Since the Basic Authentication header is sent as clear text it is highly recommended to proxy the ICE server traffic through an HTTPS encrypted connection (using NGINX configured with a certificate for instance).

POST /session/{session_name}

Store posted session xml data for {session_name}. Content-Type must be “application/json”. Please note that posting data while an interactive session is active it will overwrite the session xml data with the result of the interactive session. I.e. POST is mostly meant to create initial session data when you know the session can not be interactive (yet). Requires “Basic Authentication” header, see notes in GET /session/ section.

Back to top

4. Security

It is suggested in the ReviewStudio Integration Guide to add a signature to each item configuration. The server always tests the validity of the signature against your siteid and secret. These are built into the server code and can not be changed.

The ReviewStudio Collaboration Server does not support secure HTTP connections (HTTPS). However, you can run the ReviewStudio Collaboration Server behind a proxy server that supports secure connections, like nginx.

Back to top

5. Server setup and cross-origin resource sharing

A full system requires two web servers: one to serve web pages with the ReviewStudio Client from some content management system (using an Apache web server for instance) and the ReviewStudio Server. The web page with the ReviewStudio Client will need to communicate with the ReviewStudio Server, normally this is not allowed due to browsers’ Same origin policy (2 separate servers can not be same origin, see link for examples). The ReviewStudio Server implements Cross-origin resource sharing (CORS) specification that allows some modern browsers to communicate between two servers. However, IE does not support CORS (starting with IE10 it will), so to support IE a server setup is needed that makes it look like the web server and ReviewStudio Server are one and the same. You will need a proxy server to do this, ask your IT department what to use.

For example you can proxy http://example.com/* to your CMS web server and http://example.com/collab/* to the ReviewStudio Server (update the ReviewStudio Client serverPath accordingly). This will give give both servers the same origin and the browser will be able to communicate properly with the ReviewStudio Server from the ReviewStudio Client page.

5.1. Proxy Server requirements

There are 2 proxy server requirements:

  • the proxy server allows HTTP response times longer than 120 seconds.
    The ReviewStudio Client uses a technique called long polling to communicate with the ReviewStudio Server. This means that ReviewStudio Server does not immediately return a HTTP response to the client, instead it will wait until it has a message to return to the client (when another collaborator client adds an annotation for instance) or until a timeout happens (after 120 seconds).
  • the proxy server re-bases the URL path for the ReviewStudio Server to /. The ReviewStudio Server expects URL paths that start with /. In the above example the proxy server will get requests for http://example.com/collab/path, the ReviewStudio Server expects to receive /path.

5.2. Example nginx configuration

nginx is proxy server that we use a lot. This is an example ngin.conf configuration file:

events {
    worker_connections  1024;
}

http {
    server {
       # proxy the PHP scripts to Apache listening on 127.0.0.1:8070
       location / {
           proxy_pass   http://127.0.0.1:8070;
           proxy_redirect off;
           proxy_set_header Host            $host;
           proxy_set_header X-Real-IP       $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       }
       # proxy pages with a path starting with '/collab/' to the ReviewStudio Server
       location /collab/ {
           proxy_redirect off;
           proxy_pass http://127.0.0.1:8080/;
           proxy_buffering off;
           proxy_read_timeout 3600;
           proxy_set_header Host            $host;
           proxy_set_header X-Real-IP       $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       }
    }
}

The first location clause will proxy every request with a path that starts with / to your webserver on 8070 (this can be any port). The second location clause will route every request path starting with /collab/ to the ReviewStudio Server on port 8080 (this can also be any port see configuration section).
Although this configuration should work, it should be adjusted to your needs (see the nginx documentation).
Back to top