Skip to content

Installation: Web UI

Jump to bottom
billzt edited this page Mar 10, 2020 · 7 revisions

The Web UI of PrimerServer2 is based on Flask. Therefore it is a little more complex (but is much more stable and flexible 👍) than the legacy PrimerServer.

Test (Please do it first)

Install

$ git clone https://github.com/billzt/PrimerServer2.git
$ cd PrimerServer2
$ python3 -m venv venv # (it is recommended it run FLASK app in a virtual environment)
$ . venv/bin/activate
$ python3 setup.py develop

Configure a database directory

In this step, we need to configure a database directory to place our template files and BLAST databases. This directory must be writable by the current user.

$ primerserver-config

After running the command, the configure file in JSON format ~/.primerserver.json is generated. Edit the "templates_directory" value in this file to specify a template directory:

{
    "cpu": 2,
    "templates_directory": "/put/your/template/directory/here", 
    "templates": {
        "example.fa": {
            "IDs": "seq1, seq2",
            "description": "Example Database",
            "group": "example"
        },
        "example2.fa": {
            "IDs": "seq1, seq2",
            "description": "Example Database 2",
            "group": "example"
        }
    }
}

Run

$ flask run

If you see the following information like this:

 * Serving Flask app "primerserver2.web" (lazy loading)
 * Environment: development
 * Debug mode: on
 * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: XXX-XXX-XXX

Then you can open your browser, and visit: http://your.IP.address:5000 .Good luck!

Add your own configurations

All configurations can be edited in the configure file in JSON format ~/.primerserver.json.

  • cpu: define how many CPUs to use.
  • templates_directory: the directory to store template sequences (in FASTA format) and BLAST databases
  • templates: Each database(species)
    • example.fa: file name (in FASTA format)
    • IDs: Give two examples of sequence IDs in the FASTA file. This information would be shown as place-holder in web UI.
    • description: Some description text of the FASTA file. This information would be shown as menu names, so don't be too long.
    • group: If you have many many databases (animals, plants, fungi, bacteria, etc, ..) to put in, you can add a group name to each database. If you don't want groups, just write any words here.

All FASTA files placed in the templates_directory should be index and samtools and makeblastdb

Deploy to Production

We recommend you to read https://flask.palletsprojects.com/en/1.1.x/deploying/#deployment to know something about how to deploy the flask app to web servers such as Apache.

Here we just use mod_wgsi on Apache to give an example.

Install mod_wsgi if absent

Please refer to the official manual to install mod_wsgi. It must be coupled with Python version >=3.6 and exactly the same interpreter as you install PrimerServer2. We strongly recommend to turn on the server-info function in Apache and check whether mod_wsgi with correct Python is installed. If you see information like this, then congratulations!

Server Settings

Server Version: Apache/2.4.25 (Red Hat) ********* mod_wsgi/4.5.18 Python/3.6

Re-install the PrimerServer2 app if needed

Please make sure the Python3 (pip3) which installs PrimerServer2 is exactly the same as that installs mod_wsgi!!! Otherwise the PrimerServer2 app should be re-installed.

Make the .wsgi file

Make a .wsgi file in any directory you like, such as /your/path/to/primerserver2.wsgi, and then edit as this:

from primerserver2.web import app as application

However we just image that you use the system-default Python interpreter for mod_wsgi and primerserver2, which is usually not the case (since most Linux distributions don't carry >=python3.6 by default). Also we just image that NCBI BLAST+ and samtools are also in the SYSTEM PATH (not PATH in your ~/.bashrc!!!), which is also usually not the case. Therefore a more robust .wsgi file should be:

import sys
import os
sys.path.insert(0, '/your/python3/path/lib/python3.x/site-packages')
sys.stdout = sys.stderr
os.environ["PATH"] = '/your/samtools/path/bin/:/your/ncbi-blast+/path/bin/:'+os.environ["PATH"]
from primerserver2.web import app as application

It is recommended to open your Python interpreter that installs mod_wsgi and primerserver2 and run the above codes. Make sure no error happens.

Edit the apache Configure file

WSGIDaemonProcess username user=username group=username threads=2
WSGIScriptAlias /primerserver2 /your/path/to/primerserver2.wsgi
<Directory /your/path/to/>
    WSGIProcessGroup username
    WSGIApplicationGroup %{GLOBAL}
    WSGIScriptReloading On
    Require all granted
</Directory>

Here are some tooltips:

  1. The username username must have proper permissions to access /your/path/to/primerserver2.wsgi, /your/python3/path/lib/python3.x/site-packages, /your/samtools/path/bin/, ~/.primerserver.json, and so on
  2. The threads number granted to username should be more than cpu values in ~/.primerserver.json.
  3. If your Apache server has already other wsgi apps, don't repeat the code. Just defining WSGIScriptAlias is enough

Run

Reload the Apache server:

# systemctl reload httpd

Then you can open your browser, and visit: http://your.IP.address/primerserver2 .Good luck!

Update

When you update primerserver2 using pip3, please reload apache server again.

Configuration

The product version also uses ~/.primerserver.json as the configuration file. If you decide to use another account to run the product version, either make a symlink or make the file accessible to the new account.

Clone this wiki locally