Deployment

RCS uses Python and CouchDB and should be deployable on any platform that supports both. Currently deployment notes are provided only for Windows (and tested with 2008r2 and 2012).

Installation on Windows (IIS + FastCGI)

Install CouchDB

  1. Run the installer

  2. Open a web browser and navigate to http://127.0.0.1:5984/_utils

  3. Setup the admin account (see link in bottom left of the window)

  4. Update the configuration to listen on the correct network address (Tools | Configuration | bind_addr)

  5. Create a database rcs_cache (navigate to Overview | Create Database)

  6. Update the security for the rcs_cache database set Admin Roles: ["rcs"] and Member Roles: ["rcs"]

  7. Create a second database rcs_auth with the same permissions

  8. Add a new user to the _users database (Overview | _users | Create Document)

  9. Select source and enter the following then save document
    {
    "_id": "org.couchdb.user:rcs",
    "name": "rcs",
    "roles": ["rcs"],
    "type": "user",
    "password": "changeme"
}

  10. Logout and attempt to login as user rcs to test the setup

  11. Confirm that access to _users is restricted and access to rcs_cache and rcs_auth is enabled

Configure Python Environment

  1. Ensure python is a 2.7.x release

  2. Get an RCS release package rcs-X.Y.Z.zip

  3. Extract the release package, it should be somewhere IIS can be configured to read from c:\inetpub\rcs-X.Y.Z

  4. [Optional] Get prepackaged dependencies (should be a directory full of .whl files)

  5. Install pip (https://pip.pypa.io/en/latest/installing.html)

  6. Install virtualenv pip install virtualenv

  7. Create python virtual environment in the release location and activate it
    cd c:\inetpub\rcs-X.Y.Z
virtualenv .
scripts\activate

  8. Install the project dependencies (perform only one of the following steps):

    • via internet pip install -r requirements.txt
    • via local wheel cache pip install --use-wheel --no-index --find-links=c:\path\to\wheel\dir -r requirements.txt

  9. Update the configuration in config.py or set the environment variable RCS_CONFIG to point to a config which overrides the defaults set in config.py:

    • DB_CONN should match the account, password and host settings from the CouchDB installation
    • REG_SCHEMA should point to an absolute path (e.g. c:\\inetpub\\rcs\\rcs_schema_v1.json – use double backslashes to avoid string escape codes)
    • LOG_FILE should point to an absolute path (e.g. c:\\inetpub\\rcs\\rcs.log) this file should be writable by IIS
    • LOG_LEVEL set the log level to something appropriate (e.g. 20 for QC, 30 for Prod)

  10. Test the installation python rcs.py (this will run a test server on localhost)

  11. Seed the database python seed_qa_keys.py (do not perform this in pproduction)

IIS Integration

  1. Ensure IIS has CGI support (http://www.iis.net/configreference/system.webserver/cgi)

  2. Create a website in IIS and point it to the Python virtual environment

  3. Go to the website | Handler Mappings | Add Module Mapping ...
    Request Path: *
Module: FastCgiModule
Executable: C:\inetpub\rcs-X.Y.Z\Scripts\python.exe|C:\inetpub\rcs-X.Y.Z\wfastcgi.py
Name: (name)

  4. Go back to the server settings | FastCgi Settings | Right click Edit

  5. Select Environment variables and add the following:
    PYTHONPATH: C:\inetpub\rcs\
WSGI_HANDLER: rcs.app

Upgrading on Windows (IIS + FastCgi)

Upgrading RCS can be performed in place wihtout the need to change the IIS configuration. If you are upgrading from a post 1.5 release then there is no need to reinstall or reconfigure CouchDB either.

The following steps can be used in lieu of Configure Python Environment :

  1. Get an RCS release package rcs-X.Y.Z.zip

  2. In the existing RCS directory (e.g. c:\inetpub\rcs) remove all folders except Lib, Scripts and Include. By keeping those folders the virtualenv will remain intact.

  3. Extract the release package into the existing directory, by default it will extract into a subdirectory rcs-X.Y.Z and those files should be moved to the top level directory.

  4. Go into the RCS directory and activate the virtualenv:
    cd c:\inetpub\rcs
scripts\activate

  5. Install any new dependencies (do either one of the following):

    • via internet pip install -r requirements.txt
    • via local wheel cache pip install --use-wheel --no-index --find-links=c:\path\to\wheel\dir -r requirements.txt

  6. Update the following in config.py or the file pointed to by the enviornment variable RCS_CONFIG:

    • DB_CONN should match the account, password and host settings from the CouchDB installation
    • REG_SCHEMA should point to an absolute path (e.g. c:\\inetpub\\rcs\\rcs_schema_v1.json – use double backslashes to avoid string escape codes)
    • LOG_FILE should point to an absolute path (e.g. c:\\inetpub\\rcs\\rcs.log) this file should be writable by IIS
    • LOG_LEVEL set the log level to something appropriate (e.g. 20 for QC, 30 for Prod)

  7. Test the installation python rcs.py (this will run a test server on localhost)

Verification

This is a small test that can verify if all the major components have been installed.

  1. RCS comes pre-packaged with a testing interface, where you can test the GET, PUT, REGISTER, and DELETE requests. The full service contract is available at RCS Service Contract
  2. In a browser, load up http://rcs.localhost/static/test.html (replacing the hostname with the correct path to rcs)
  3. Enter a smallkey value (e.g. “test”)
  4. Press the Feature button in the second row of buttons
  5. Press PUT
  6. If successful you will see a 201 code that the service was properly added to the database
  7. Press GET
  8. It should return a JSON object with a status code of 200
  9. If a version of RAMP is configured alongside the RCS install the test can be extended by visiting the following RAMP URL: http://ramp.localhost/ramp-en.html?keys=test (replacing the hostname with the correct value)