This document tells how to install the Early Detection Research Network (EDRN) public portal and knowledge environment, or more simply, the "EDRN portal", version 4. Preparation and installation takes nearly two hours.


Before installing the EDRN site, you'll need to prepare the target host and gather some information. This installation assumes the following:

  • You're installing this software on the same host that currently runs EDRN portal version 3.
  • The Unix account running the EDRN portal, "edrn", won't be changing.
  • The current EDRN installation directory is available for reading. If it's not, copy one over from some other host.
  • You're installing this software in a new directory, not overwriting the current EDRN installation directory.
  • The Apache HTTPD configuration may be updated as needed to reverse proxy to this, the new EDRN software installation.

Once the deployment process is complete, this software will become the new EDRN portal software. The old directory with version 3 may then be removed.

This software has dependencies on several external packages. Many of these should already be installed, however some are new dependencies in this release of the site:

  • Python 2.4 or later plus development environment (Python.h headers, etc.).
  • C/C++ compiler and "make" (to build additional software)
  • JPEG 6B development libraries
  • OpenSSL development libraries
  • wvWare tools
  • PDF-to-HTML tools
  • SASL (new dependency)
  • OpenLDAP (new dependency)
  • Varnish (new dependency)

Check and install these dependencies using your system provided tools (such as Pirut, Aptitude, etc.) or by building and installing from source.

Note: Ensure your OpenLDAP is linked with OpenSSL and not with GNUTLS (which is the default on Debian). GNUTLS is not compatible with EDRN. Red Hat users won't have to worry.

Deploying the EDRN Portal

To deploy this version of the EDRN portal, perform the following steps:

  1. Cancel the current system services (log rotation, cron jobs) for the old version 3 of the portal.
  2. Run the deploy script for the new portal, version 4.
  3. Stop the old portal 3 and update its init.d startup script for the new version 4.
  4. Start the new version 4 site.
  5. Adjust the Apache HTTP reverse proxy configuration.
  6. Make the site.cfg file readable only by user "edrn".
  7. Install the log rotation, cron jobs, and startup scripts for the new version 4 portal.

The rest of this document details the above steps.

Canceling the Current System Services

The old version of the EDRN portal currently running takes advantage of a few operating system services, including log file rotation and periodic cron jobs. These need to be canceled. To do so, remove the following files/symlinks:

  • /etc/cron.daily/edrn (might be named "backup" or "edrn-backup")
  • /etc/cron.weekly/edrn (might be named "edrn-maint")
  • /etc/cron.monthly/edrn (might be named "zeopack" or "edrn-pack")
  • /etc/logrotate.d/edrn (might be named "edrn-portal")

Running the Deploy Script

Deploying the new version of the EDRN portal is easier than ever before. To do so:

  1. Extract the software archive:

    tar xjf edrn-portal-VERSION.tar.bz2

    Replace VERSION with the version number being deployed. Do not extract the file over an existing installation directory; as a sibling directory, or elsewhere, is fine. Do so as the EDRN user "edrn".

  2. Change the current working directory to the newly extracted directory, which from here on out we'll call $INSTALL_DIR:

    cd edrn-portal-VERSION
  3. Run the deployment script:

    ./ --existing-install=OLDPORTAL

    Replace OLDPORTAL with the path to the old, currently running EDRN portal. For example:

    ./ --existing-install=/home/edrn/

The deployment script will check dependencies and system configuration, download the EDRN portal software and its related packages, configure them, copy the old content database, upgrade it, and prepare everything automatically.

You must have a copy of the old version 3 of the portal with all of its content intact. If you don't, tar up its installation directory from wherever host it's currently running on and bring it over!

The deployment script will also create a detailed log file, deploy.log, with lots of information that can be helpful if anything goes wrong. You won't need to redirect or save the console output of the command at all.

For finer control over what the deployment script does, you can specify additional command-line arguments. Run ./ --help for a list of options.

If the script fails to run, try running it with the Python interpreter; i.e.:

/usr/bin/python ./ --existing-install=/home/edrn/

All of the steps that the script carries out can take an enormous amount of time. If you're fond of food, now would be a great time to take a lunch break; be sure to get cocktails, appetizers, a bottle of wine, dessert, and coffee.

Deployment Options

There is only one required command-line "option" for the deployment script, --existing-install. All of the rest are optional. The full set of command-line options you can provide to the script includes:

This option is required. Tells the deployment script to use the old, existing installation of the EDRN portal software in the directory EXISTING_INSTALL.
Username to use for the process Supervisor (default "supervisor")
Password for Supervisor (will be generated if not given)

These two options control the administrative username and password for the Zope application server. Please note that if the username you specify matches the existing Zope administrative username in the EXISTING_INSTALL, then the password must also match. Otherwise, you can specify a new username and password, or let the script use the default username "edrn-admin" (which doesn't match the EXISTING_INSTALL) and it will generate a fresh password.

-z ZOPE_USER, --zope-user=ZOPE_USER
Username for the Zope appserver (default "edrn-admin")
Password for the Zope appserver (will be generated if not given)

The remaining options control the TCP ports on which the various processes that comprise the EDRN portal listen. You can specify a base port number (and each process listens on a port number offset from the base), and/or individual port numbers.

Base port (procs get base +1,+2,..., default 7310)
Cache control port (default base+1)
Cache port (default base+2)
Supervisor port (default base+3)
ZEO monitor port (default base+4)
--zeo-port=NUM ZEO database port (default base+5)
Zope debug port (default base+6)
Zope appserver 1 (default base+7)
Zope appserver 2 (default base+8)

Starting the Site

To start the site, run:

sudo bin/supervisord

You can then visit the Supervisor's web interface with a browser. Unless you changed the port setting on the deploy script's command-line, the Supervisor listens on port 7313, i.e., http://localhost:7313/. From the web interface you can check on the status of the processes that run the EDRN site, view their log files, stop and restart them, etc. The username and password for the Supervisor are in the site.cfg file.

If you don't like web browsers, you can also access the Supervisor by running bin/supervistorctl.

All of the following processes should be listed as running:

Process ID Description
cache Varnish reverse proxy caching engine
instance1 First Zope application server
instance2 Second Zope application server
zeo Zope Enterprise Objects database server

If you need to re-do any of the installation steps, you can shutdown the Supervisor and all of its processes by running:

bin/supervisorctl shutdown

The supervisorctl command provides additional commands; run it with help as an argument for more, or give it no arguments to enter an interactive command-line mode.

You can check that the site is active by fetching the following URLs (adjusting port numbers as needed):

You should get an identical web page from all three URLs.

Protecting the site.cfg file

Make sure site.cfg is readable only by user "edrn":

chmod 600 site.cfg

Connecting the Front End Web Server

Previous versions of this software included Nginx pre-configured for EDRN and serving ports 80 (HTTP) and 443 (HTTPS). In practice, we found that NCI preferred to maintain their own front-end web server (Apache HTTPD).

The Apache HTTPD configuration will need some port updating to work with this release of the EDRN portal. For HTTP communication, the last rewrite rule should reverse-proxy to Varnish listening on port 7312 (unless overridden by the deploy script):

RewriteRule ^(.*)

And for HTTPS communication the last rewrite rule should reverse-proxy to Zope instance 1 listening on port 7317 (unless overridden by the deploy script):

RewriteRule ^(.*)

Finally, the "/blobstorage" URI should not be have a reverse-proxy, and should be set up with a directory alias, just like the "/snapshots" URI:

<Directory $INSTALL_DIR/var/blobstorage>
    AuthType basic
    AuthName "Database Blobstorage"
    AuthUserFile $INSTALL_DIR/etc/snapshots.cfg
    Require valid-user
    Order Deny,Allow
    Allow from All
    Options Indexes
Alias /blobstorage $INSTALL_DIR/var/blobstorage

For your reference, an HTTPD configuration is generated in $INSTALL_DIR/ops/apache-httpd.conf. Feel free to use it as a guide.

Hooking into the Operating System

The EDRN site relies on services provided by the Unix operating system for its operation. Specifically, it needs help from Unix ...

  • At boot time, to start the EDRN site
  • Via cron, to run periodic maintenance
  • Via logrotate, to trim and archive log files

Boot Time

To ensure the EDRN public portal is always available, you should arrange to have it started at boot-up time. How you do so depends on your operating system. You may need to:

  • Create a SysV-style init script in /etc/init.d that calls bin/supervisord to start and bin/supervisorctl shutdown to stop
  • Add execution of bin/supervisord to /etc/rc.local
  • Add bin/supervisord to the @reboot event of root's crontab
  • Something even more exotic

Consult your operating system documentation for details.

Cron Jobs

The EDRN site relies on the Unix cron scheduler for periodic tasks. These tasks include:

  • Daily database backups
  • Weekly restarts and snapshots
  • Monthly database packing

Depending on your system, you may have a root /etc/crontab file and/or /etc/cron.daily, /etc/cron.weekly, and /etc/cron.monthly directories. Consult your system documentation for more details.

Single Crontab File

If your operating system uses a single crontab file, make the following additions (substituting $INSTALL_DIR as appropriate):

0 0 * * * $INSTALL_DIR/bin/backup
0 0 * * 0 $INSTALL_DIR/bin/snapshotbackup
0 0 * * 5 $INSTALL_DIR/bin/supervisorctl restart instance2
0 0 * * 6 $INSTALL_DIR/bin/supervisorctl restart instance1
0 0 1 * * $INSTALL_DIR/bin/zeopack

Cron Directories

If your operating system provides /etc/cron.daily, /etc/cron.weekly, and /etc/cron.monthly (or similar) directories, do the following:

  1. Install $INSTALL_DIR/bin/backup as /etc/cron.daily/edrn-backup.

  2. Install $INSTALL_DIR/bin/zeopack as /etc/cron.monthly/edrn-pack.

  3. Create a script /etc/cron.daily/edrn-maint with the following contents (substituting the appropriate value for $PARENT_DIR):

    day=`/bin/date '+%w'`
    case $day in
    0) $INSTALL_DIR/bin/snapshotbackup ;;
    5) $INSTALL_DIR/bin/supervisorctl restart instance2 ;;
    6) $INSTALL_DIR/bin/supervisorctl restart instance1 ;;
    exit 0
  4. Make the script executable: sudo chmod 755 /etc/cron.daily/edrn-maint

Log Rotation

During the buildout, a configuration file compatible with logrotate was generated and placed in operations/logrotate.conf. If your system uses logrotate to prune log files periodically, you can either link or copy that generated file to /etc/logrotate.d; for example:

install -o root -g root -m 644 $INSTALL_DIR/ops/logrotate.conf /etc/logrotate.d/edrn-portal

If you don't have logrotate, you'll want to arrange for the following log files to be rotated and the listed signal sent to the given process to have it close its log file and start a new one:

Log File Signal Process ID file
var/log/instance1*.log USR2 var/
var/log/instance2*.log USR2 var/
var/log/zeoserver.log USR2 var/

Updating DNS

The last step in deploying the EDRN site is to update your domain name servers, or DNS. Currently, your DNS has a CNAME record for as an alias for If that's already correct, you're done. Otherwise, update the CNAME as needed.

Questions, Bug Reports, and Help

For feedback about this product, please visit the feedback page at