Cozimo Server Integration Guide

Introduction

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

Version

Guide for version 1.0.

Installation

Requirements

Erlang R12B-5

You can download it here: otp_src_R12B-5.tar.gz.

Untar and build with the instructions found in the README file in otp_src_R12B-5 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 Cozimo 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.

Installation

Unzip installation:
```
unzip iceserver-id-version.id.zip
```
Go into directory created by unzip:
```
cd ./iceserver-id-version.id
```
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.
Install Cozimo Collaboration Server:
```
sudo python ./install.py install
```
This will copy the Cozimo 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 Cozimo Collaboration Server with the /etc/iceserver/runICEServer script and stop it with /etc/iceserver/stopICEServer.

By default the Cozimo 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 Cozimo Server and its version.

The default installation directory is /etc/iceserver. Run

python ./install.py --help

to see all the options to the installer.

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

HTTP server port

The default HTTP port is 8080. If you want to run the Cozimo 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 Cozimo Collaboration Server on port 80.

If you want to run the Cozimo Collaboration Server on a machine that is already running another web server you can not use the same port (if you do you the Cozimo 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 Cozimo Collaboration Server and all the other URLs to your web server.

Session storage

File storage

By default the Cozimo 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 Cozimo HTML pages. The Cozimo 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 Cozimo 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 Cozimo Collaboration Server does not allow arbitrary URLs, only URLs from configured servers are allowed. The servers are configured through the servers property in the cozimo 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 Cozimo 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 Cozimo 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 Cozimo Collaboration Server.

Alternatively you can hide the CMS URL by configuring them in the Cozimo Collaboration Server instead of session property of the Cozimo item. You can configure the URL with get_data_url property in the cozimo 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 Cozimo, and configure the Cozimo 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 Cozimo item. To follow the get_data_url setup it could be:

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

Security

It is suggested in the Cozimo 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 Cozimo Collaboration Server does not support secure HTTP connections (HTTPS). However, you can run the Cozimo Collaboration Server behind a proxy server that supports secure connections, like nginx.

Server setup and cross-origin resource sharing

A full system requires two web servers: one to serve web pages with the Cozimo Client from some content management system (using an Apache web server for instance) and the Cozimo Server. The web page with the Cozimo Client will need to communicate with the Cozimo 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 Cozimo 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 Cozimo 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 Cozimo Server (update the Cozimo Client serverPath accordingly). This will give give both servers the same origin and the browser will be able to communicate properly with the Cozimo Server from the Cozimo Client page.

Proxy Server requirements

There are 2 proxy server requirements:

the proxy server allows HTTP response times longer than 120 seconds.
The Cozimo Client uses a technique called long polling to communicate with the Cozimo Server. This means that Cozimo 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 Cozimo Server to /. The Cozimo Server expects URL paths that start with /. In the above example the proxy server will get requests for http://example.com/collab/path, the Cozimo Server expects to receive /path.

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 Cozimo 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 Cozimo 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).