Installation of CHARMMing
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.
CHARMMing is installed by means of an installation script (click link to download), which is designed to run on recent Debian or Ubuntu-based systems. This script automatically installs all necessary packages, sets up the database, and creates a basic, working configuration that can be modified.
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 (the installation script is written for Debian-based distrubtions, but with a bit of manual porting, it should work on most any Linux distro). With a bit of work, CHARMMing can be installed on any *nix-based system, including Max OS X, that supports Django. However, it has been developed and tested exclusively on Linux. You must have root access on this system - CHARMMing cannot be installed by a non-superuser.
- A CHARMM executable (version c37 preferred). We do NOT distribute CHARMM with CHARMMing; it must be properly licensed through Harvard University.
- In order to use REDOX calculations - the APBS module of CHARMM must be compiled into the executable; see apbs.doc for details.
- If additive QM/MM support is desired, a Q-Chem executable must also be present, and CHARMM must be compiled with Q-Chem support.
- If substractive QM/MM support (ONIOM) is desired, an additional CHARMM executable with Q-Chem and MSCALE enabled is required.
- 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.
Prerequisite software installation
There are two pieces of software used by CHARMMing: VMD and ProPKA, that cannot (for license reasons) be distributed with it. You must obtain these yourself.
- VMD is used by the drug design module, and can be downloaded from Klaus Schulten's Web site.
- ProPKa is (optionally) used to determine likely titration states of various residues when a new structure is uploaded. It can be downloaded from the developers' Web site.
- Stride is used to determine the secondary structure of proteins, which is needed to build coarse grained models. Unless it is installed, this functionality will not work.
Running the installer
Once you have downloaded the installation script, run it with:
sudo ./installer.sh -install
The installer will present a series of prompts describing the actions it is going to take. These are further described below. You have the option to skip individual steps if you would rather configure things manually.
The installer script will use apt-get to install all prerequisite software that is freely redistributable. You still need to download the non-redistributable prerequisites listed above.
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, which is the default web root on Debian-based systems. On Red Hat based systems the web root is usually /var/www/html and other distributions use paths like /srv/httpd, so be sure to check your own system before proceeding. You can edit the install directory at the top of the installer.sh script, but by default /var/www/charmming is used.
The installer script will download CHARMMing from subversion and place it in the distribution directory. Since there is a lot of software that is distributed with CHARMMing, this can take some time (10-15 minutes).
Initial database configuration
CHARMMing uses a MySQL database as back-end storage, and it is configured to use "charmming" as the database user. You may set your preferred database password at the top of installer.sh. You should also edit this script with the correct MySQL root password, as this script will try to create the database user. The installer then creates the job scheduler table.
You may skip this step if you prefer to configure database account yourself, however, if you do this be sure to create the job_scheduler table ((the schema is in the install script).
Set up $USERDIR and $DATADIR along with the schedd user
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 by editing the charmming_utils variable in installer.sh.
Please note that the CHARMM binary is NOT distributed with CHARMMing. We will explain how to install it into $DATADIR later on.
The scheduler user and $USERDIR
CHARMMing runs scripts via a non-privileged user, schedd, which runs the schedd daemon (see below). User data is stored in this account's home directory, which is set as $USERDIR. Therefore, thisdirectory must be writable by the account that the Web server runs under (www-data in Debian/Ubuntu). The installer.sh script will set up this account with the necessary permissions.
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)
Configuration of schedd
The schedd daemon is very simple; the only information that is required is the hostname of the system. The installer.sh will determine this and adjust the pbs_sched.py script accordingly.
The installer.sh script installs TORQUE automatically via the package manager.It would be configured with a basic set-up with the local system set up as the only compute node. If you wish to add more nodes for CHARMMing to use, you must install the torque-mom package on them and edit /etc/torque/server_name to point to your Web server. You can then run the following on the server:
qmgr -c 'create node <hostname> np <number of cores>' qmgr -c 'set node <hostname> properties=batch'
If you then run "pbsnodes -a", the new node should be seen in state "free".
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 with the stocl Debian/Ubuntu Apache systems. It has not yet been tested on other systems.
Under the default configuration, the installer add the following lines to /etc/apache2/sites-enabled/000-default:
<Directory "/var/www/charmming"> SetHandler python-program PythonHandler django.core.handlers.modpython SetEnv DJANGO_SETTINGS_MODULE settings PythonDebug On PythonPath "['/var/www/charmming'] + sys.path" </Directory>
These are necessary to process the CHARMMing pages using mod_python. You can adjust as necessary for your system.
The Django configuration step does a database sync to create the database schema used by CHARMMing. It will also prompt for the creation of an administrative user account, which will be used for the first login to your CHARMMing install (see below). You should answer the prompts exactly as directed by the installer.sh script.
The script then populates the database with some necessary initial data.
Starting the scheduler daemon
The final step is starting the scheduler daemon. The following commands are executed (assuming a default configuration) to do this:
su - schedd cd /var/www/charmming/scheduler PYTHONPATH=/var/www/charmming ./schedd.py
After the installation is complete, you can verify that schedd is running through the use of the "ps" command. The scheduler daemon keeps a log file in /var/www/charmming/scheduler/schedd.log; if it fails to start correctly, please examine this file for possible causes.
If desired, you can add the above commands to your init scripts to start schedd automatically on boot.
CHARMMing expects a CHARMM serial binary to be placed in its private directory. This binary can be built with the following install.com commands (assuming gfortran is used):
./install.com gnu xxlarge
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. You should put your qchem directory into $DATADIR, which is /usr/local/charmming by default. You will also need to add the requisite environment variable definitions to the schedd user's start up scripts to allow it to run Q-Chem.
If you wish to compile a separate parallel executable with Q-Chem and MSCALE support for subtractive QM/MM calculations, the following command should be used:
./install.com gnu xxlarge M QC +GENCOMM +MSCALE
The REDOX module of CHARMMing requires CHaRMM's APBS interface to be built in. Please refer to apbs.doc and this Web page for information on how to do this.
Once you've got your executable(s) built, you should copy them into $DATADIR and edit charmming_config.py to point to them. The following variables should be changed:
- charmm_exe: points to your regular serial CHARMM executable (with or without Q-Chem support),
- charmm_apbs_exe: a version with APBS if available (may be the same as charmm_exe, but it does not have to be).
- charmm_mscale_exe: If you built an executable with Q-Chem and MSCALE support, put it here (this cannot be the same as charmm_exe, which must be a serial executable).
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.