Installation of CHARMMing

From CHARMM tutorial

CHARMMing (www.charmming.org) is an open source web-based front end to CHARMM. It can be used to prepare and run a variety of common tasks such as minimization, solvation, and molecular dynamics. In fact, the scripts used in this tutorial are based off of those created for CHARMMing.

You may download the CHARMMing source code from its Google code repository. If you'd like to live on the somewhat-bleeding edge, A subversion repository is available at http://charmming.googlecode.com/svn.

Anyone is welcome to set up their own CHARMMing server, however a few things are needed:

A computer capable of acting as the server with Linux installed (CHARMMing has been tested on CentOS and Ubuntu, but it should work on most any Linux distro). The Apache Web server and mod_python should be configured and working. In theory, any Unix or Unix-like operating system, including Max OS X, that supports Django should be able to run CHARMMing. However, it has been developed and tested exclusively on Linux.
MySQL and the Python MySQLdb module should be working.
Django version 0.96 installed (version 1.0 and later will NOT work -- we are in the process of making CHARMMing compatible with these versions of Django) -- Note: the installer program can fetch and install Django for you. Most recent Linux distributions (e.g. Ubuntu 9.10) include newer versions of Django in their repositories. Therefore, you should install version 0.96 yourself or let the installer do it for you.
A CHARMM executable (version c35 preferred). We do NOT distribute CHARMM with CHARMMing; it must be properly licensed through Harvard University.
If QM/MM support is desired, a Q-Chem executable must also be present.
Knowledge of the Torque batch scheduler is helpful, but not required.
Light to moderate Linux system administration experience is also very helpful.

You also need to decide where to store user data (structures users upload and create) and private CHARMMing data (the CHARMM executable, topology files, etc.). We'll refer to these two locations as $USERDIR and $DATADIR, respectively.

The installation of CHARMMing is done via an automated install script. This page will describe what the install script is doing. If you have questions or problems with the install, please post the on the CHARMMing board of the CHARMM forums.

Running the installer

This section assumes that you have downloaded a complete CHARMMing release tarball. For instructions on other install methods (e.g. installing from the Subversion repository), please see the INSTALLER documentation file distributed with CHARMMing. To get the install process started, extract the tarball and change into the newly extracted directory. Then run the installer.py script as root. We are looking at ways to make installation work as a non superuser, but right now root privileges are required. The installer will run some startup checks, and then present you with a prompt:

The prompt allows you to install any of the components of CHARMMing individually. However, for a new install you can just run through all the components in order which you can do by simply typing "install" (no quotes) at the prompt. The following sections will go through each of the install routines:

Installing Django

Django itself can be downloaded from the Django project web site. Remember to get only version 0.96. You are welcome to download and install it yourself, for example if you need to install it to a non-standard location. However, CHARMMing's installer can download and install Django for you. If you would like it to do so, answer "y" when prompted. If you already have Django installed, feel free to say "n" here to proceed to the next step. If you choose "y", the script will download Django 0.96 to /tmp and install it to the default location (generally /usr/lib/python2.X/site-packages). As stated above, Django 0.96 is required to make CHARMMing operate; work is in progress to make CHARMMing compatible with newer Django versions.

Installing third-party software

CHARMMing requires the freely-available OpenBabel software package, however it is not distributed directly with CHARMMing. The third-party software install routine will download and install it into /usr/local for you. Feel free to skip this step (answer "n" when prompted) if OpenBabel is already installed on your system. Some Linux distributions (Ubuntu and Debian, at least) have OpenBabel in their package repositories. These versions should be safe to use. More third-party software may be added as CHARMMing develops.

Installing the CHARMMing files

CHARMMing itself needs to be installed in a directory that your web server (Apache) is configured to serve up. The default install path is /var/www/html, which is the default web root on RHEL and Fedora based systems. On Debian based systems the web root is usually /var/www and other distributions use paths like /srv/httpd, so be sure to check your own system before proceeding. There is limited functionality to detect which operating system you are using, but it generally works best to just specify the installation path that you want the installer to use. As part of the install process, this routine also sets up the database that CHARMMing will use. You will be prompted to enter the MySQL user name, password, and database to use. If these are not configured, the installer will ask you for your MySQL root password and will create the database and charmming database user for you. Additionally, you have the opportunity to create a Django administrative account for your CHARMMing setup, which is required to administer your installation. These steps are described in further detail below:

Extracting the tarball

The first step of this process is the extraction of the charmming.tar.gz tarball in your chosen Web directory. This creates a subdirectory called charmming in this directory, which is the root of the CHARMMing install. CHARMMing assumes that the charmming directory is in the Web root directory so that all CHARMMing URLs look like:

http://www.mysite.org/charmming/<blah>

If this is not the case, you will need to edit charmming/urls.py to change the URLs to match up with the ones used on your server. If CHARMMing is the only site running on your server, it is suggested that you redirect www.mysite.com to www.mysite.com/charmming.

Configuring the database

Once the tarball has been extracted, the routine attempts to set up the database, prompting you for the correct MySQL credentials and database. The database is brought on-line by running:

"python manage.py syncdb"

Note that the database credentials are stored in settings.py. Currently only databases running on localhost are supported by the install script, but you can edit settings.py if you want to run the database on another system. Various tables must be populated before CHARMMing is started; the required data is in the .sql files distributed with CHARMMing, so these are processed automatically. The correct credentials for database access are also automatically loaded into the scheduler/schedd.py script since it needs to access the database independently.

At this point, Django offers the user a chance to create an administrator account to log in to CHARMMing. This task must be performed, otherwise you will be locked out and it will be necessary to reinstall.

Set up $USERDIR and $DATADIR

$DATADIR

CHARMMing requires a place to store private data. This store is created once and does not grow as the site is used (unless you add to it!). It is primarily used to hold topology, parameter, and other data files, water box coordinates, and the CHARMM binary itself. Web users will not have access to this area (although they are allowed to download topologies, parameters, and the water box coordinates). You are able to choose what directory is used for this. To get this area set up routine simply extracts the charmming-private.tar.gz tarball into the chosen directory and renames the created "charmming-private" directory into the "charmming" directory.

Please note that the CHARMM binary is NOT distributed with CHARMMing. We will explain how to install it into $DATADIR later on.

$USERDIR

Next, the installer will configure the user area and the area where CHARMMing keeps its own files. Each user has their own subdirectory of this main data directory into which the files that they generate are placed. Like with $DATADIR, you can choose the location of $USERDIR Consequently, the space requirements of this directory may grow substantially over time.

There is no tarball to extract to create this directory; the installer creates a data directory, along with an admin subdirectory to store files generated by the administrative user (who gets set up in section 1.3.

Install visualization Package

CHARMMing distributes the GPL licensed Jmol software to use for visualization; however, an interface to ChemAxon's MarvinSpace has also been developed. This interface may be enabled in this installation routine. However, you will have to obtain the MarvinSpace software yourself, as it requires a click-through license agreement. The Jmol software is simply copied from the CHARMMing software. You should be able to use a newer version than the one we distribute.

Install and configure the job scheduler

CHARMMing is designed to act as a front end to a larger computing resource, and as such runs jobs via an external job scheduler. A daemon (schedd) exists to arbitrate between CHARMMing and the target batch queuing system. Currently, CHARMMing integrates with both the TORQUE and Condor batch schedulers. Of these, TORQUE is more thoroughly tested and should be used unless you have some reason not to. There are thus two parts two the job scheduling system:

A daemon distributed with CHARMMing (schedd) that interfaces between the web application and the batch queue system.
The batch queue system itself which is an external program (currently PBS/TORQUE and Condor are supported)

Configuring each of these two is described here:

Configuration of schedd

The schedd daemon is very simple and only requires two pieces of information:

what user account it should run under
what batch queue system it will be interfacing with

The install routine will prompt for this information. Even if you already have a batch scheduler running you have to tell schedd which one it is and where it is installed (you don't actually have to have the installer download and install the batch scheduler for you though -- you can skip that part of the install routine).

You should create a user for schedd to run as. The user account specified should be a member of the apache group (this group might be named differently on different systems; it's the group that the Apache web server runs as) so it can write files into the Apache-created user directories. UNDER NO CIRCUMSTANCES SHOULD SCHEDD RUN AS ROOT OR ANY USER THAT CAN SU/SUDO TO ROOT!

Installation/configuration of the chosen batch scheduler

Currently, because CONDOR is distributed primary in binary form, automatic installation of it is not supported. You can download and install it directly from the Wisconsin site. Please make sure that the schedd user has condor_q, condor_submit, and condor_submit_dag in its $PATH.

If you choose to install PBS, a recent version of TORQUE (a free PBS-compliant scheduler) will be downloaded and installed into /usr/local. Please make sure that /usr/local/bin is in the $PATH of the schedd user. Although TORQUE is fully installed, it requires further configuration. Details on how to do this are given in section III.

Configuring Apache

The installer can attempt to configure your Apache set-up to use mod_python for CHARMMing. Note that the configuration method is very naive, and probably will not work or actively break more complex set-ups. Therefore this routine gives you an option to skip it. When in doubt (i.e. working on a production box), it is recommended that you skip this step. Nonetheless, the configurator seems to work OK on stock Fedora/CentOS httpd.conf files. It has not yet been tested on other systems.

If you elect to proceed with this routine, you will be asked the location of your httpd.conf file. The appropriate configuration for CHARMMing will be appended to the end of this file.

Please see the next section for information on how to configure Apache by hand.

Post-install configuration

Manual Apache configuration

It is necessary to configure Apache to use mod_python in order to run the Python files that power the Web site. Since CHARMMing is contained entirely in one directory you can create a directory specification that tells Apache to use mod_python in that directory. Here is an example of such a specification assuming that CHARMMing is installed in /var/www/html/charmming (adjust as necessary for your system):

 <Directory /var/www/html/charmming>
   SetHandler python-program
   PythonHandler django.core.handlers.modpython
   SetEnv DJANGO_SETTINGS_MODULE settings
   PythonDebug On
   PythonPath  "['/var/www/html/charmming'] + sys.path"
 </Directory>

Once this section has been added to the Apache configuration, it is necessary to restart the server. On Red Ht/Fedora systems, this is usually done with:

 /etc/init.d/httpd restart

and on Debian based systems (including Ubuntu) with:

 /etc/init.d/apache2 restart

however, startup scripts vary from distribution to distribution. Consult your documentation if you need help.

Installing CHARMM/Q-Chem

CHARMMing expects an XXLARGE CHARMM serial binary to be placed in its private directory. It expects the file to be named gfortran-xxlg.one (even if some non-gfortran compiler is used) although this can be changed by modifying the source. The binary can be either 32 or 64 bits. It can be created with the following install.com commands (assuming gfortran is used):

 ./install.com gnu xxlarge GFORTRAN # 32 bit mode
 ./install.com gnu xxlarge GFORTRAN X86_64  # 64 bit mode

To compile with Q-Chem support add the QC key word to the above commands. Note that you need the Q-Chem software itself in order to use CHARMM's Q-Chem interface.

Once install.com completes successfully copy exec/gnu/charmm into the private data directory with the file name gfortran-xxlg.one, e.g.:

  cp exec/gnu/charmm $DATADIR/gfortran-xxlg.one

If you would like to use Q-Chem, you will also need to put your qchem directory (containing bin/, exe/, and samples/) and the QCAUX directory into $DATADIR. If you do not have Q-Chem and wish to disable the QM/MM portion of the user interface, you can edit charmming_config.py in your CHARMMing install directory (set haveqchem = 0).

Start scheduling

It is necessary to start the two parts of the scheduling system before you can use CHARMMing. First you must start the batch scheduler that you chose (TORQUE or CONDOR) and then you need to start CHARMMing's own scheduler daemon (schedd), which mediates between CHARMMing itself and the batch scheduler. Since TORQUE is the default batch scheduler, its configuration is described below.

Starting TORQUE

If you installed TORQUE (PBS) from scratch, it is still necessary to configure it. In the extracted charmming-package tarball, there should be a subdirectory called pbs containing two files: (1) a sample node configuration file called node_config and (2) a script that can be passed to TORQUE's qmgr program to configure the pbs_server.

Here are the exact steps that you need to perform:

Copy the node_config file to /var/spool/torque/mom_priv/config (cp pbs/node_config /var/spool/torque/mom_priv/config).
Edit /var/spool/torque/mom_priv/config and adjust the $ideal_load and $max_load variables to something suitable for your system (note that the defaults are for a 4-core system).
In the same file, modify the $clienthost variable to be the host name of your server.
In the same file provide an appropriate $usecp line -- which determines whether or not to use rcp/scp to copy files remotely. For set-ups running entirely on one machine "$usecp *:/ /" should be OK. For more complex configurations, consult the TORQUE manual.
Start the TORQUE server, scheduler, and mom daemons with:

 pbs_server -t create
 pbs_sched
 pbs_mom

You will probably want to have a script to start these on boot. Assuming you have the installer script download TORQUE for you, you can find init scripts in /tmp/torque-2.2.1/contrib/init.d. Note, when starting the server after the first time, be sure to use pbs_server -t hot rather than pbs_server -t create.

Once the server, scheduler, and mom are up and running, you can configure the server to reasonable defaults by running qmgr < conf_pbs (where conf_pbs is in the pbs directory of the extracting charmming-package).

Once this is done, the final step is to configure the scheduler so it sees the local host as a worker node. This can be done with the following commands:

 qmgr -c "create node <your.host.name>"
 qmgr -c "set node np = <# of processors/cores in your node>"
 qmgr -c "set node properties = exec"

The last line isn't strictly necessary, but does help describe your node.

Starting CHARMMing's job scheduler

Once the batch scheduler is started, it is necessary to start CHARMMing's own scheduler daemon (schedd). Before doing so, make sure that the TORQUE or CONDOR commands are in the schedd user's $PATH. TORQUE requires qsub and qstat while CONDOR requires condor_q, condor_submit, and condor_submit_dag. To actually start schedd, su to the user that schedd is supposed to run as, and change to <CHARMMing install path>/scheduler. Then simply run ./schedd.py. You can look at the schedd.log for information about what schedd is doing, and it will also create either a pbs.log or condor.log detailing commands it has issued to the queuing system. Note that these files can grow quickly, so be sure to rotate them occasionally, especially on systems with limited disk space (the logrotate utility can be used to accomplish this).

Once again, it will probably be desirable to create an initialization script that will start schedd automatically on system boot.

Initial login

Once everything is up and running, you should be able to go to the URL of your CHARMMing install; if not you may need to restart the apache server. Log in using the administrative account you created in step II.b, and begin running jobs. At this point, it is a good idea to create a non-administrative account. Fill out the registration form (which is linked from the front page) and submit it. If you entered your e-mail address correctly in step II.b and outgoing mail is set up properly, you should receive an e-mail stating that a new user has registered.

To approve this user, go to www.mysite.com/charmming/admin (replace /charmming/ with the actual URL path of your install) and log in using your administrative user name and password. In the auth pane, click on the users link and select the user name of the new user. In the groups display at the bottom of the screen, click on "students", which will unselect "preapprove." Then click on "Save" (bottom right of the screen). You can also give the new user staff status (which allows them to log in to the administrative interface) or superuser status (which allows them to do anything they want in the administrative interface).

Log out as your administrative user and test that the newly-created user can now log in and submit jobs.

Everything should now be ready.