RCAS web interface

This is a simple web interface for RCAS. A user may upload a BED file, configure options for RCAS, and then schedule RCAS to be run on the file.

Separate worker processes pick up the jobs and run them. Once they are done the user is provided with a link to the generated RCAS report.

Preparing the environment

The easiest way to set up the RCAS web interface is to use GNU Guix. We need the Redis server to be running and we need to be in an environment in which RCAS itself is available.

With Guix you can easily create an environment in which all required external dependencies are available:

guix environment --ad-hoc redis

RCAS and the RCAS web interface have been packaged for Guix, so you can install the web interface with all its dependencies into your default profile by running:

guix package -i rcas-web

If you rather want to build RCAS manually we suggest you use Guix to create an environment with tools needed to build the web interface. This repository comes with an environment definition file guix.scm, which you should load up with Guix:

guix environment --load=guix.scm

Building RCAS web

Now we’re ready to build the web interface. RCAS web uses the common GNU build system.

autoreconf -vif
./configure --prefix=/srv/rcas-web
make

At this point you can already use RCAS web—without installing it—by using the “pre-inst-env” script, e.g. to start the web server:

./pre-inst-env scripts/rcas-web --config=rcas.conf server

Note that when using pre-inst-env outside of the “rcas-web” directory you will need to configure the “assets-dir” by modifying the example configuration file.

Installing RCAS web

To install RCAS web to the configured target directory just run make install as root.

Configuring RCAS web

RCAS web comes with crude defaults that you probably want to change. The defaults are recorded in the %config value in the file rcas/config.scm. You can override individual values or all of them by putting an association list (i.e. a list of key-value pairs) expression in a file and pointing rcas-web to the file with the --config option.

Here’s an example for a configuration file:

((assets-dir  . "/path/to/web/assets")
 (upload-dir  . "/path/to/file/uploads")
 (results-dir . "/where/to/store/reports")
 (host        . "localhost")
 (port        . 12345)
 (gtf-files   . ((hg19 . "/path/to/hg19.gtf")
                 (mm9  . "/path/to/mm9.gtf")
                 (ce10 . "/path/to/ce10.gtf")
                 (dm3  . "/path/to/dm3.gtf")))
 (msigdb      . ((c2.cp.v5.0 "MSigDB Curated Pathways (c2.cp.v5.0)" "/srv/rcas-web/msigdb/c2.cp.v5.0.entrez.gmt"))))

Assuming that this is stored as a file called rcas.conf you can make rcas-web use it like this:

rcas-web --config=rcas.conf [command]

An example configuration file rcas.conf.example is also created by the configure script.

The only configuration keys that you will need to override are upload-dir (for the directory where RCAS web will store uploaded BED files), results-dir (where RCAS web will store generated reports), and the gtf-files paths. The gtf files are not included with RCAS or rcas-web and must be obtained separately.

The port key in the configuration file only overrides the default port on which the application web server will listen for HTTP requests. Since you will probably want to start multiple web servers behind a reverse proxy like Nginx, overriding the default is not very useful. Instead you should pass an additional numeric argument to the “server” sub-command to set the port.

Running RCAS web

First you need to start the redis server, which is used by rcas-web for the job queue.

redis-server &

To start the application web server and a single worker process do this:

${prefix}/bin/rcas-web --config=rcas.conf server &
${prefix}/bin/rcas-web --config=rcas.conf worker &

You can and should run a larger number of worker processes. Currently, one worker process runs exactly one job at a time. You may also want to start more than one web server process and use a reverse proxy like Nginx to dispatch to them.

The following shell command will start ten web server instances on the ports 3001 to 3010 (inclusive), redirect all output to separate log files, and record the pid of each web server process:

for port in $(seq 3001 3010); do
  rcas-web --config=rcas.conf server ${port} > rcas-web-${port}.log &
  echo $! > rcas-web-${port}.pid
done

You can find full documentation of a simple real-life deployment in the file deployment.org. We also provide an example service script at etc/service.sh

License

The RCAS web interface is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.