++++++++++++++++++++++++++
Railroad Integration Guide
++++++++++++++++++++++++++
------------------------------------------------
How to integrate a Railroad server with your CMS
------------------------------------------------

:Author: Guido Goldstein
:Email: gst@infrae.com
:License: BSD, see LICENSE.txt


1. Requirements
===============

1.1 Server side
---------------

On the server side a running Railroad server is required; the setup is
described in the install document.


1.2 Client (CMS) side
---------------------

1.2.1 Silva integration
_______________________


The follwing software in addition to Zope and Silva is needed to
implement the client side of Railroad:

1. the pydavclient package
2. libxml2 with Python bindings (for 1.)
3. SilvaRailroad extension
4. Railroad extension

The extensions should be installed in the ``Products`` directory
of your Zope.

libxml2 and it's Python bindings must be installed for the Python
version your Zope is using!

The `pydavclient` package can be installed through its ``setup.py``
script, which will install a package ``dav`` in the ``site-packages``
directory of the used Python version. Administrator rights might be
needed for this step!

After a restart of Zope the SilvaRailroad extension should show up in
the services/service_extensions screen. Install the SilvaRailroad
extension by pressing the install button.

After the SilvaRailroad extension has been installed, change back to
the services screen and look for ``service_railroad``.

The service_railroad screen needs some data to work with a Railroad
server:

**1. Repositroy URL**
   URL to the top of the repository on the Railroad server.
   The URL has to be complete including scheme, host, port and
   absolute path to the top of the repository.

   (i.e. http://nova.infrae:82/rrr/repo/).

**2. Services URL**
   URL to the top of the services on the Railroad server. Also a complete
   URL.

   (i.e. http://nova.infrae:82/rrr/service/).

**3. Server name**
   Name of the Railroad server (set by the Railroad server administrator).

   (i.e. railroad_data)

**4.  Client name**
   Name of this CMS instance (acting as a client) as known to the Railroad server.

   (i.e. SilvaNova)


After you've configured the Zope/Silva RailroadService you can change to
the Silva edit screens. Now there should be a ``Silva Railroad Proxy``
entry in the drop-down list for new objects.

**Note:**

  If the ``Silva Railroad Proxy`` entry doesn't appear, check the
  addable configuration (``properties`` tab, ``configure addables``
  button) and check the ``Silva Railroad Proxy`` checkbox.


Now you should be able to add ``Silva Railroad Proxy`` objects to your
site.


1.2.2 Plone integration
_______________________

Install the Railroad and PloneRailroad Products into your site's
Product directory. By starting the zope Server with fg option you can
handle some mistakes.

You then should be able to go to 'plone setup' --> 'Add/Remove Products'; 

  http://nova.infrae:82/plone_site/prefs_install_products_form

There you can enable/install the PloneRailroad Product

After you have done so, in the left margin a link to 'Railroad
configuration' will appear. The URL to this configuration looks like
this in my case:

  http://nova.infrae:82/plone_site/portal_railroad/

In this configuration screen you can add a 'plonerailroadservice'. 
This service is a key element in integrating the Railroad server with
the CMS (in this case Plone).

The service takes five parameters:

  * A title: just a choose a sensible one for example : RailRoad

  * client_name: this will be the identifying name for this CMS, being the
    client to the RR server. rrtest

  * Repo_url: this is the URL to top of the RR repository (looking at you data,
    http://nova.infrae:82/rrr/repo'

  * Repository_name: the identifying name of the RR repository you will connect
    to, as configured on the RR server : railroad_data

  * Services_url: the URL to the top of the RR services:
    http://nova.infrae:82//rrr/service


2. Form based upload
====================

The form based upload is used to send a file to the Railroad server
via a POST request. The upload is not going through the CMS. To
achieve this, a form which points to the upload URL of the repository
is needed.

This is a core service which is found under
`prefix`/service/formupload/ on the Railroad server.


2.1 Required fields
-------------------

The following form fields must be present -- and filled in correctly
-- for a successful upload:

**1. field_file**
   The field for the uploaded file. This is filled in by the browser when
   the user chooses a file to upload.

**2. ok_url**
   The url to redirect to when everything went fine.
   This has to be set by the CMS to an URL to which the upload process will
   redirect the user in case the upload succeeded.
   Two paramters will be appended to this URL: ``url`` and ``errormsg``. The
   latter holds a textual message to be displayed to the user, the ``url``
   parameter holds the full URL of the created resource.

**3. error_url**
   The url to redirect to when an error occured.
   This has to be set by the CMS to an URL to which the upload process will
   redirect the user in case the upload failed.
   One parameter will be appended to this URL:``errormsg``. It holds a textual
   message to be displayed to the user.

**4. link_url**
   Set when this upload is ment to be an update, else empty. It holds
   the full URL of the Railroad resource the CMS object refers to. If
   the basename and the mime-type of this URL are matching the
   basename and mime-type of field_file, the upload is considered to
   be an update. Otherwise the upload will be rejected.

2.2 Use with authorization
--------------------------

If authorization is enabled, the following form fields are required in
addition to the above mentioned fields:

**1. object_id**
   The id of the CMS side object referring to the resource -- or will
   be referring to in case this is a first time upload. This means
   that the CMS side object has to exist when the upload is initiated!

**2. client_id**
   The id of the client CMS which owns the referring object and the
   uploading user is registered with. Usually this field contains the
   name of the client as given by the Railroad administrator during
   registration of the client.

**3. user**
   The name of the user as known to the CMS.

**4. passwd**
   The password of the user as known to the CMS. This **is** a
   security hole when HTTPS is not used!



3. WebDAV upload
================

Later...


4. Authorization
================

4.1 How does the authorization work
-----------------------------------

The authorization in Railroad is based on a call-back mechanism which
uses the authorization scheme of the client CMS owning a particular
resource. This technique avoids the hassles of implementing a
authorization scheme for Railroad itself (which would be difficult
because of the wide variety of CMSes around).

4.1.1 Registration
__________________

Every CMS has to be registered before it can use a Railroad
repository.

This is the data that needs to be collected:

**1. Client Id**
   The identification (aka name) for the CMS.

**2. Admin EMail**
   The email address of the administrator of the CMS.

**3. Authorization URL**
   The URL `called` by the Railroad system to trigger the
   authorization process in the CMS.

**4. Authorization domain**
   The domain for which the `Basic Auth` header should be set.

This data is stored in the database and used heavily during the
authorization process -- which means on every request to a resource on the
Railroad server!

More in this in the installation document chapter 3.


4.1.2 Ownership
_______________

The Railroad authorization code keeps track of the ownership of a
resource, which is defined in to levels: the first level ownership is
the owning CMS, the second level ownership is a user on that CMS.

The Railroad authorization code keeps track of the CMS from which a
resource was initially uploaded. This CMS is called the `owning CMS`.

The second level of ownership is a user on the owning CMS. The `owning
user` is the user who did the initial upload of the resource.


4.2 The callback mechanism
--------------------------

The `call` to the authorization URL is a ``GET`` request with the
following parameters:

**1. id**
   The object id of the resource (the id by which the referring
   object in the CMS is identified).

**2. method**
   The request method (GET, PROPFIND... all HTTP/1.1 and WebDAV methods).

If the request is answered with a response status of 200, the
requested action on the resource is permitted, otherwise the action
will be denied (with a 401 response code, which will give the user
opportunity to choose a different user/password combination).

If authorization is required for the resource is question, the
Railroad server will supply user and password using the `Basic
Authorization` scheme of HTTP.

Only `Basic Auth` is and will be supported.

For a in depth explanation of the problems with authorization over
multiple domains see the `authorization.txt` document.

4.2 Implementing the CMS side
-----------------------------

On the CMS side only little work is needed to integrate a Railroad
server with authentcation/authorization.

As stated above, for every request to a resource on the Railroad
server a request to the owning CMS is made asking for authorization. 
So the CMS has to provide an URL which the Railroad server can query
(using a simple GET request, see 4.1.2).

The ``id`` parameter to the request denotes the object in the CMS that
refers to the resource in the Railroad repository. The CMS should take
the ``method`` and check if it is allowed for the given object. If so,
the CMS has to return a response with its status set to 200 and no
body. If the given method is not allowed for the object in question
the CMS has to return a response with status set greater or equal 400
and no body (usually 401).



5. Search
=========

Later...





..
   Local Variables:
   mode: rst
   indent-tabs-mode: nil
   sentence-end-double-space: nil
   fill-column: 70
   End:
