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. See RCS Configration Options for a full description for all options, at a minimum update the following:

    • 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. If URL_PREFIX was set in the configuration it should be applied to the Request Path setting (e.g. /rcs1/* for a prefix of /rcs1).

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

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

Upgrading from 1.x 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. Remove all files except wfastcgi.py and config.py.

  3. If wfastcgi.py was removed please recreate the module mapping as described in IIS Integration .

  4. 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.

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

  6. 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

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

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

  9. Follow any other version specific upgrade notes in this section.

Upgrading from 1.6 to 1.7 or 1.8

Version 1.7 of RCS adds the capability to use a URL prefix for an RCS installation. This makes it possible to deploy multiple copies of RCS side by side in IIS. To prefix an existing RCS install please follow the steps.

  1. Select a common directory for the various RCS installations to share (this is only necessary if IIS needs to serve up static files)
  2. Create or copy RCS installations into various subfolders (e.g. rcs1 and rcs2)
  3. In IIS create or modify a website to be the root for the various RCS installations
  4. (Optional) The root directory should point to the common directory for the RCS installations
  5. For each RCS installation add a handler as described above using a Request Path of /<subfolder name>/* (if static files are not needed the prefix may be any prefix identifying the RCS installation)
  6. In the RCS installation set the configuration parameter URL_PREFIX (e.g. /rcs1 for a request path of /rcs1/*)

Upgrading from 1.7 to 1.8

RCS 1.8 adds a new endpoint but does not require any additional deployment changes.

Upgrading from 1.8.0 to 1.8.1

RCS 1.8.1 fixes issues in 1.8.0, no addtional deployment changes.

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)