Getting Started

Download

ResourceSync PuSH can be obtained here.

Installation

To install, Python version >= 2.6 is required. The installation process entails decompressing the downloaded file and executing the setup script.

To decompress zip files, run the following from the command line.

$ unzip resourcesync_push-<version>.zip

To decompress tarballs

$ tar xvzf resourcesync_push-<version>.tar.gz

To install ResourceSync PuSH, run the following command.

Note: Administrative privileges are needed to install.

$ cd resourcesync_push-<version>
$ sudo python setup.py install

Setup and Configuration

The install script, in addition to installing the ResourceSync PuSH library in Python's site-packages folder, will also install configuration files and binaries.

The binary files to start the servers will be installed in the system path (usually in the folder /usr/bin/ or /usr/local/bin).

Starting the server

To start the publisher, type:

$ resourcesync_pub

For starting the hub:

$ resourcesync_hub

For the subscriber:

$ resourcesync_sub

Stopping the server

If the server process is running in the foreground, it can be stopped by pressing CTRL+C.

For background processes, resourcesync_push creates one PID file for the Publisher, one for the Hub, and one for the Subscriber in /tmp/<resourcesync_component>.pid. This file contains the service's process ID which can be used to stop the component. The example below shows how to stop the resourcesync_hub process.

$ kill -INT `cat /tmp/resourcesync_hub.pid`

Configuration

By default, the hub will listen to the HTTP port 8000, the publisher 8100 and the subscriber will listen to 8200. Each of the servers will start with 8 processes and each of the processes with 2 threads each. These parameters can be changed in the configuration files, which can be found in the folder /etc/resourcesync_push/. Each of the modules above has it's own configuration file. The configuration files have the same file name as the module name, appended with the extension .ini as shown below.

$ ls -l /etc/resourcesync_push/
total 32
-rw-r--r--  1 root  wheel   399 Apr 17 13:08 resourcesync_hub.ini
-rw-r--r--  1 root  wheel   289 Apr 17 13:08 resourcesync_pub.ini
-rw-r--r--  1 root  wheel  1176 Apr 17 13:08 resourcesync_push.ini
-rw-r--r--  1 root  wheel   291 Apr 17 13:08 resourcesync_sub.ini

An example configuration file looks like:

$ cat /etc/resourcesync_push/resourcesync_hub.ini

[uwsgi]
pythonpath = $PYTHONPATH
http = :8000
processes = 8
threads = 2
module = resourcesync_push.hub.hub
callable = application
master = true
limit-post = 2097152

The parameters pythonpath, http, processes and threads can all be configured depending on the requirements. The parameter http denotes the HTTP port that the module must use and pythonpath is the path to the Python site-packages folder.

NOTE: The parameters module and callable should not be changed and doing so will break the installation.

More configuration parameters for uWSGI can be found here.

The three configuration files: resourcesync_pub.ini, resourcesync_hub.ini, resourcesync_sub.ini, help configure how the HTTP servers must start and run. The fourth configuration file resourcesync_push.ini, explained below, helps configure the PubSubHubbub and ResourceSync specific parameters.

resourcesync_push.ini

The resourcesync_push.ini file is the common configuration file for all the three modules: publisher, hub, and the subscriber. The necessary PubSubHubbub and ResourceSync specific parameters, that are needed for the modules to communicate with one another must be placed in this file. An example file can be found here.

This file contains three main sections with the titles [hub], [publisher] and [subscriber]. Depending on the ResourceSync module that is to be run, the corresponding section will have to be edited. For example, to run a hub, the variables in the section [hub] will have to be updated.

server_path

All the three modules have the parameter server_path in their sections. When running the hub, publisher or the subscriber behind a web-server like apache or nginx, it is common to use a reverse proxy setup. For the ResourceSync modules to work in this setup, it needs information about the proxy path that is used. For example, if the apache web server is configured like

ProxyPass /resourcesync/hub/ http://localhost:8000

then the server_path parameter should look like:

server_path = /resourcesync/hub/

This information helps determine the requested path information correctly.

Please refer to the individual sections in the documentation for detailed explanation on other parameters.

Deployment

The Web Server Integration section of the uWSGI documentation provides complete information on the deployment choices available.

The best and the simplest way to deploy ResourceSync_PuSH modules in an existing production server is to use a reverse proxy setup. For Apache web servers, the mod_proxy module is used to setup this proxy.

If the hub is running in port 9000, the Apache configuration will look like:

ProxyPass /resourcesync/hub http://localhost:9000
ProxyPassReverse /resourcesync/hub http://localhost:9000

The same configuration in nginx will look like:

location /resourcesync/hub {
    proxy_pass http://localhost:9000;
}

Please refer to the nginx documentation for complete information.

Note: Do not forget to set the server_path parameter in the resourcesync_push.ini config file as mentioned above.