1. TOHCC Medical Physics Avatar TOHCC Medical Physics
  2. QATrack+
  3. qatrackplus

Wiki

Clone wiki

qatrackplus / deployment / windows / iis

View History

Deploying QATrack+ with IIS, CherryPy & SQL Server

This guide is going to walk you through installing QATrack+ on a Windows Server server with IIS serving static assets (images, javascript and stylesheets) and acting as a reverse proxy for a CherryPy web server which serves our Django application (QATrack+). SQL Server 2008 will be used as the database.

The steps we will be undertaking are:

  1. Installing and configuring git
  2. Checkout the latest release of the QATrack+ source code from bitbucket.
  3. Setting up our Python environment (including virtualenv)
  4. Making sure everything is working up to this point
  5. Setting up a database with SQL Server
  6. Configuring CherryPy to serve our QATrack+ site.
  7. Configuring IIS
  8. Wrap up

I will be using Windows Server 2008R2, IIS & SQLServer for this guide but steps should be similar on other versions of Windows.

1. Installing git

Go to http://git-scm.com and download the latest version of git (msysgit) for Windows (Git-1.8.1.2-preview20130201 at the time of writing). Run the installer. I just leave all the settings on their defaults but you are free to modify them if you like.

Step 1 done ;)

2. Checkout the latest release of QATrack+ source code from bitbucket

From the Start Menu look for the Git folder under All Programs and select Git Bash. This will open up a console window which we will be using fairly heavily for the rest of the process. (Note: this is a fairly full featured bash shell and is a lot more powerful than the default windows command prompt).

To create a home for QATrack+ and check out the source code, use the following commands:

#!bash

mkdir /c/deploy
cd /c/deploy
git clone https://bitbucket.org/tohccmedphys/qatrackplus.git

3. Setting up our Python environment

Note all Python packages should be 32 bit versions even on 64 bit machines

Go to http://www.python.org/download/ and download the 32 bit Python 2.7.X Windows Installer for Python (current version is 2.7.3 at the time of writing -- QATrack+ does not currently support Python3). Go through the installer using the default options (Install for all users).

Next go to http://pypi.python.org/pypi/setuptools#files and download and run the MS Windows Installer (setuptools-0.6c11.win32-py2.7.exe at the time of writing)

We now need to download Scipy, matplotlib and pywin32. Go to http://sourceforge.net/projects/scipy/files/scipy/0.11.0/ and download the win32 superpack (eg scipy-0.11.0-win32-superpack-python27.exe. Save it in C:\deploy\ or somewhere else you can remember. Likewise, visit http://matplotlib.org/downloads.html and download the latest 32 bit version of matplotlib for Windows (matplotlib-1.2.0.win32-py2.7.exe at the time of writing). Finally visit http://sourceforge.net/projects/pywin32/files/pywin32/Build%20218/ and download pywin32-218.win32-py2.7.exe.

You will also want to add Python to your PATH environment variable. The process is slightly different depending on if you are on XP or something newer but the gist of it is: * Right click on My Computer * Select Advanced (or Advanced System Settings) * Select Environment Variables * Select Path under the System variables section and then click edit * Append ;C:\Python27;C:\Python27\Scripts to the end of the path. Don't overwrite the existing value! * Click Ok/Ok/Ok

Close the git bash command prompt you had open before and then open a new one (this will give you access to the updated PATH variable).

In your new git bash window the command which python should return /c/Python27/python. If it doesn't then your PATH variable has not been set correctly.

We're now ready to install all the libraries QATrack+ depends on. To install them, run the following:

#!bash
cd /c/deploy
easy_install pip
pip install virtualenv==1.9
mkdir venvs
virtualenv venvs/qatrack
source venvs/qatrack/Scripts/activate
easy_install numpy==1.7
easy_install /c/deploy/scipy-0.11.0-win32-superpack-python2.7.exe
easy_install /c/deploy/matplotlib-1.2.0.win32-py2.7.exe
easy_install /c/deploy/pywin32-218.win32-py2.7.exe
cd qatrackplus
pip install -r requirements/base.txt
pip install -r requirements/optional.txt
pip install -r requirements/win.txt

Last but not least, for this guide, we are going to be using the CherryPy package to act as our WSGI server and django-mssql as our database driver so install them too:

#!bash
pip install cherrypy
pip install django-mssql

4. Checking everything is functional so far

Getting everything installed was a pain, so lets take a minute and check everything is now functioning as it should. Create a directory called 'db' in the main qatrackplus directory and then setup a temporary database for testing (answer 'yes' and create a super user when prompted).

#!bash
cd /c/deploy/qatrackplus
mkdir db
python manage.py syncdb
python manage.py migrate
python manage.py loaddata fixtures/defaults/*/*
python manage.py collectstatic

You should now be able to run the built in test server and access your QATrack+ site for the first time! At the command prompt type the following to start the server:

#!bash
python manage.py runserver

You should then be able to open a browser window and visit http://127.0.0.1:8000 where you will be redirected to a login page (you can login using the superuser you created earlier).

In the terminal hit Ctrl+C to kill the server.

5. Creating a database with SQL Server

From the start menu find and open SQL Server Management Studio. Enter 'localhost' for the server name and click Connect.

In the Object Explorer frame, right click the Databases folder and select "New Database...".

Enter 'qatrackdb' as the database name and click OK.

Back in the Object Explorer frame, right click on the main Security folder and click New Login... Set the login name to 'qatrack', select SQL Server Authentication. Enter 'qatrackpass' (or whatever you like) for the password fields and uncheck Enforce Password Policy. Click OK.

Back in the Object Explorer frame, expand the qatrackdb database, right click on Security and select New->User.

Enter 'qatrack' as the User name and Login name and then below in the Database Role Membership select 'db_datawriter', 'db_datareader' and 'db_owner'. Click OK.

Configuring QATrack+ to use your new database

Create a file called local_settings.py in /c/deploy/qatrackplus/qatrack/ and add the following contents:

#!python
DEBUG = False
TEMPLATE_DEBUG = False

DATABASES = {
    'default': {
        'ENGINE': 'sqlserver_ado', # Add 'postgresql_psycopg2', 'mysql', 'sqlite3' or 'oracle'.
        'NAME': 'qatrackdb',                      # Or path to database file if using sqlite3.
        'USER': '',                      # Not used with sqlite3.
        'PASSWORD': '',                  # Not used with sqlite3.
        'HOST': '',                      # Set to empty string for localhost. Not used with sqlite3.
        'PORT': '',                      # Set to empty string for default. Not used with sqlite3.
    }
}

Once again, we will configure our new MS SQL database from the command prompt (answer 'yes' and create a super user when prompted):

#!bash
python manage.py syncdb
python manage.py migrate
python manage.py loaddata fixtures/defaults/*/*

6. Configuring CherryPy to Serve QATrack+

Django's built in web server that we used earlier is not meant to be used in production. Instead we will be using CherryPy to serve QATrack+ (you could also use waitress or rocket if you prefer).

Create a file called cherrypy_deploy.py in /c/deploy/qatrackplus/ with the following content:

#!python
from qatrack import wsgi
from cherrypy import wsgiserver
server = wsgiserver.CherryPyWSGIServer(
    ('127.0.0.1', 8080), wsgi.application
)
server.start()

and then to test that our CherryPy server is working run the following from the command line:

#!bash
python cherrypy_deploy.py

that command won't appear to do anything but you should be able to visit http://127.0.0.1:8080 in your browser and see the login screen. (Don't worry if it looks different than before...CherryPy is not setup to serve the style sheets and images)

Back in the terminal window hit Ctrl+C to kill the server.

Installing CherryPy as a Windows Service

In order to have CherryPy start when you reboot your server, or restart after a crash, you may wish to install your CherryPy server as a Windows service.

Create a file called QATrackCherryPyService.py and add the following contents to it:

#!python

"""

Basic CherryPy Windows service for QATrack+...cobbled together
from various places online.

Requires Mark Hammond's pywin32 package.

"""

import cherrypy
import win32serviceutil
import win32service
import win32event

import sys
import os

from qatrack import wsgi

DEPLOY_DIRECTORY = "C:/deploy/qatrackplus/"
ERROR_LOG = os.path.join(DEPLOY_DIRECTORY,"logs","cherry_py_err.log")
STD_ERR = os.path.join(DEPLOY_DIRECTORY,"logs","std_err.log")
STD_OUT = os.path.join(DEPLOY_DIRECTORY,"logs","std_out.log")
sys.stdout = open(STD_OUT,'a')
sys.stderr = open(STD_ERR,'a')

class QATrackService(win32serviceutil.ServiceFramework):

    """NT Service."""

    _svc_name_ = "QATrackCherryPyService"

    _svc_display_name_ = "QATrack CherryPy Service"

    def SvcDoRun(self):

        sys.path.append(DEPLOY_DIRECTORY)
        os.environ['DJANGO_SETTINGS_MODULE'] = 'qatrack.settings'
        os.chdir(DEPLOY_DIRECTORY)

        cherrypy.tree.graft(wsgi.application)

        cherrypy.config.update({
            'global':{
                'log.error_file':ERROR_LOG,
                'log.screen': False,
                'tools.log_tracebacks.on':True,
                'engine.autoreload.on': False,
                'engine.SIGHUP': None,
                'engine.SIGTERM': None
                }
            })

        cherrypy.engine.start()
        cherrypy.engine.block()

    def SvcStop(self):

        self.ReportServiceStatus(win32service.SERVICE_STOP_PENDING)

        cherrypy.engine.exit()

        self.ReportServiceStatus(win32service.SERVICE_STOPPED)
        # very important for use with py2exe
        # otherwise the Service Controller never knows that it is stopped !

if __name__ == '__main__':

    win32serviceutil.HandleCommandLine(QATrackService)

Then from the command line:

#!bash
mkdir /c/deploy/qatrackplus/logs
python QATrackCherryPyService.py install
python QATrackCherryPyService.py start

Your QATrack+ installation is now installed as a Windows Service. I would recommend configuring your service to auto start. Instructions on how to do that can be found on the Windows Service Wikipedia page. You may also wish to configure the service to email you in the event of a crash (see the Recovery tab of the QATrackCherryPyService configuration dialogue).

7. Setting up IIS

We are going to use IIS for two purposes: first, it is going to serve all of our static media (css, js and images) and second it is going to act as a reverse proxy to forward the QATrack+ specific requests to CherryPy.

Before starting please make sure you have the URL Rewrite and Application Request Routing IIS modules installed. Application Request Routing needs to have the reverse proxy setting enabled: for instructions see the section titled Enabling Reverse Proxy Functionality on this page.

Once you have the URL Rewrite extension installed, open the IIS Manager, select the default Web Site and click Stop on the right hand side.

Stop default web site

Now right click on Sites and click Add Web Site

Add a new web site

Enter QATrack Static for the Site Name and C:\deploy\qatrackplus\qatrack\ for the Physical Path then click OK and answer Yes to the warning.

To test that setup worked correctly open a browser on your server and enter the address http://localhost/static/img/tux.png You should see a picture of the Linux penguin.

Next, select the top level server in the Connections pane and then double click URL Rewrite

URL Rewrite

In the top right click Add Rule and select Blank Rule.

Give it a name of QATrack Static and enter ^(static|media)/.* for the Pattern field, and select None for the Action type. Make sure Stop processing of subsequent rules is checked.

static rule

When finished click Back To Rules and then add another blank rule. Give it a name of QATrack Reverse Proxy, enter (.*) for the Pattern and http://localhost:8080/{R:1} for the Rewrite URL. Make sure both Append query string and Stop processing of subsequent rules are checked.

URL Rewrite Reverse Proxy

Your URL rewrites should look like the following (order is important!)

URL Rewrites

You should now be able to visit http://localhost/ in a browser on your server and see the QATrack+ login page. Congratulations, you now have a functional QATrack+ setup on your Windows Server!

there are many different ways to configure IIS. The method I've used above is simple and works well when QATrack+ is the only web service running on a server.

8. Wrap Up

This guide shows only one of many possible method of deploying QATrack+ on Windows. It is very similar to what we use at The Ottawa Hospital Cancer Centre and it has proven to be a very solid setup. If you're stuck with a Windows stack it will likely work for you too. Hit me up on the QATrack+ Google Group if you want to discuss some other alternatives for deploying on Windows.

References:

[1] http://www.computerhope.com/issues/ch000549.htm

Updated