Installation & Deployment

MDsrv is working under Linux, Mac OS and Windows systems. Here, we explain how to deploy it (Debian-based Linux system as template system). Deployment support for other Linux systems as Arch Linux, Ret Hat, slackware linux, as well as for Windows are currently under development and testing. Current information can be found here.

1. Install the MDsrv

The latest stable release of MDsrv can be easily installed via PyPI or conda.

pip install mdsrv

conda config --add channels conda-forge
conda install -c ngl mdsrv

To install the development version, download it from the MDsrv GitHub page and install it manually (via executing setup.py within the repository).
Pip needs to be installed in advance to add underlying tools otherwise an installation error (e.g. "import setuptools not found") might rise.
For further information, consult the setuptools documentation.

Dependencies: As MDsrv depends on MDTraj, some packages need to be installed in advance to garantee, that MDTraj is working. MDsrv should install those packages but it can happend that some dependencie problems rise due to this. If you have problems running the simulations, please check if mdtraj is working: 

mdtraj:cython, numpy, scipy
mdsrv: setuptools, flask

Additional dependencies: You can speed up your trajectories by installing MDAnalysis (Please be aware that this package is large). MDsrv will automaticially detect when MDAnalysis is present and will use it prior to mdtraj. For installation instructions please see the MDAnalysis website.


There are three ways of installing, as root (sudo), as 'normal' user or within an virtual environment. Note that the installations paths will differ. When installing as 'normal' user the path will be (under Linux) '/home/USER/.local/lib/python3.8/site-packages ' while as root the installation will be under e.g. '/usr/lib/python3.8/'. You have to adjust the variable 'python-path' in the apache2 config (/etc/apache2/sites-available/000-default.conf) accordingly.


Test your installation:

To test your installation, execute mdsrv path/to/structure-file path/to/trajectory in your terminal. A new browser window will open. If nothing is shown, please just reload the website. Don't forget to play your trajectory.

If the executable 'mdsrv' cannot be found, you probably have to adjust your PATH variable, e.g.: export PATH=$PATH:~/.local/bin


Deployment even on your local machine - why?

With step 1, you can already use the MDsrv locally within your network. In order to add the MDsrv into your daily research, deploy and configure it to your system and your settings. The advantage is that you can add project folders permanently, including their security settings. By setting up an apache server (locally on your machine or global on a web server), you are able to share your sessions and files with colleagues within the same network, collaborators or reviewers. Additionally, you can add a link to your cluster and inspect your unprocessed simulations remotely.

2. Install Apache2 and WSGI

To serve MDsrv as an Apache Webserver via mod_wsgi, install apache2 and libapache2-mod-wsgi to your system. 

sudo apt-get install apache2 libapache2-mod-wsgi

If you are using python3, please install sudo apt-get install apache2 libapache2-mod-wsgi-py3
Then activate wsgi with a2enmod wsgi

3. Add MDsrv-wsgi settings to apache.config

Add the content of apache.config into /etc/apache2/sites-available/000-default.conf or replace this file.

apache configuration file

Important: Adjust the user and group according to your environment settings (e.g. local installation on a pc (nickname@pc) with user=nickname and group=nickname) so that the wsgi process can run with the specified user & group. Make also sure that the files and directories you want to serve are accessible with that user & group combination. Please also adjust the python-path, e.g. to your environment or conda directory or remove this variable to keep the default. Make sure to use absolut paths here. For further information on apache.config, please consult the documentation.

4. Add html for MDsrv gui

Copy mdsrv.html into the folder /var/www/html/. Make sure the right rights are set (chmod +r /var/www/html/mdsrv.html).

5. Add & adjust the MDsrv configuration file

Download the configuration file app.cfg and save it within a secure directory (e.g. not within /var/www/hmtl/). Here, you can change the host and port, the list of directories where you store your structure and trajectory files (DATA_DIRS) and the security settings. The content and setting is explained elsewhere.

6. Place mdsrv.wsgi

Generate a folder mdsrv in /var/www/ and place mdsrv.wsgi into this folder (/var/www/mdsrv/mdsrv.wsgi). Add the path of the configuration file (app.cfg) into the mdsrv.wsgi file including the name of the file (APP_CFG = '/home/nickname/important/app.cfg'). Restart now the apache server.

7. Restart the apache server

Whenever the app.cfg file is changed, the apache server has to be restarted. If content within the directories is changed, a restart is not necessary. To restart execute 

sudo /etc/init.d/apache2 restart
or 
sudo service apache2 restart

8. Access & Visualize your simulations

The MDsrv with the structures and trajectories within the defined folder can be reached at http://localhost/mdsrv.html by loading a structure via "File -> Import" and adding afterwards the trajectory within the structure menu by selecting "Remote trajectory - import". Find out more about the NGL gui at viewing or load trajectories chapter.

Toy example to test your installation & deployment

Find here a quick guide to setup your first mdsrv session:

  1. Go to https://github.com/nglviewer/mdsrv/tree/master/data
  2. Download script.ngl, md_1u19.gro, md_1u19.xtc into e.g. ~/example/

  3. In app.cfg, add the path where script.ngl is located, e.g.:

    4. DATA_DIRS={
"mytest" : os.path.abspath( "/home/USER/example/"),
}

  4. In script.ngl you have to change the basePath variable, e.g.:
    5. var basePath = "mytest/"

  5. Restart apache2: service apache2 restart

  6. In your browser call URL: http://localhost/mdsrv.html?load=file://mytest/script.ngl

More

If you have any questions, found some bugs, or want to report enhancement requests use the Issue Tracker, use the contact formular or write a mail to johanna.tiemann@gmail.com or alexander.rose@weirdbyte.de.

Please give us feedback!

top