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

  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
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 Configuration 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_reg_schema_v2_0_0.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)
    • DEBUG_ENDPOINTS should be set to False in Production, enables the /accesslog, /log, and /all_keys endpoints when True
    • PROD should be set to True only in a Production environment
    • HTTP_PROXY
    • URL_PREFIX A general prefix for the application, useful if you want to have side by side installs of RCS

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

  11. Seed the database python seed_qa_keys.py (change these values before running on Production!)

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: run.app

Upgrading from 1.8+ 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_reg_schema_v2_0_0.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)
    • DEBUG_ENDPOINTS should be set to False in Production, enables the /accesslog, /log, and /all_keys endpoints when True
    • PROD should be set to True only in a Production environment
    • HTTP_PROXY
    • URL_PREFIX A general prefix for the application, useful if you want to have side by side installs of RCS

  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.

  10. Update IIS’s FastCGI Environment variables collection: change WSGI_HANDLER’s value from rcs.app to run.app.

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 v2 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 key 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)