h1. Deploying the MAUS web-front end

{{>toc}}

h2. Deploy Python 2.7 and related packages

If you do *not* have and do *not* want to download the MAUS software (which comes with Python 2.7 and Python easy_install) then keep reading. 

Otherwise, *go down to* the next section, "Deploy ImageMagick".

For full information on deploying Python 2.7, see http://www.python.org/getit/releases/2.7/

To install Python 2.7.2 via building from it's source code:

* Log in as super-user e.g. using @sudo su -@ or @su@.

* Get Python 2.7 source distribution and unpack it,

<pre>

$ wget http://www.python.org/ftp/python/2.7.2/Python-2.7.2.tgz

$ mv Python-2.7.2.tgz Python-2.7.2.tar.gz

$ gunzip Python-2.7.2.tar.gz 

$ tar -xf Python-2.7.2.tar 

$ cd Python-2.7.2

</pre>

* Configure,

<pre>

$ ./configure

</pre>

* Build,

<pre>

$ make

</pre>

* Install,

<pre>

$ make install

</pre>

h3. Deploy Python setuptools

Now, install the Python setup tools (0.6c11) for Python 2.7. For full information, see http://pypi.python.org/pypi/setuptools.

* Log in as super-user e.g. using @sudo su -@ or @su@.

* Get the setuptools egg,

<pre>

$ wget http://pypi.python.org/packages/2.7/s/setuptools/setuptools-0.6c11-py2.7.egg#md5=fe1f997bc722265116870bc7919059ea

</pre>

* Execute the egg,

<pre>

$ sh setuptools-0.6c11-py2.7.egg 

</pre>

This will install the Python @easy_install@ tool.

h2. Deploy ImageMagick

The ImageMagick library is used to convert between image types in the MAUS web-front end. For full information see http://www.imagemagick.org/script/index.php

Check to see if you already have this as it is a commonly deployed tool,

<pre>

$ /usr/local/bin/convert -h

Version: ImageMagick 6.7.4-0 2011-12-13 Q16 http://www.imagemagick.org

Copyright: Copyright (C) 1999-2011 ImageMagick Studio LLC

Features: OpenMP    

</pre>

If so then *go down to* the next section on installing Django, MagickWand and PIL.

To install ImageMagick 6.7.4,

* Log in as super-user e.g. using @sudo su -@ or @su@.

* Get and unpack ImageMagick,

<pre>

$ wget http://www.imagemagick.org/download/ImageMagick.tar.gz

$ gunzip ImageMagick.tar.gz

$ tar -xf ImageMagick.tar

$ cd ImageMagick-6.7.4-0/

</pre>

* Configure,

<pre>

$ ./configure

</pre>

* Make,

<pre>

$ make

</pre>

* Install,

<pre>

$ make install

</pre>

** This places libraries in @/usr/local/lib@.

* Cache the libraries,

<pre>

$ ldconfig /usr/local/lib

</pre>

** This avoids problems with libraries not being found by Python's magickwand library.

* Check,

<pre>

$ /usr/local/bin/convert -h

Version: ImageMagick 6.7.4-0 2011-12-13 Q16 http://www.imagemagick.org

Copyright: Copyright (C) 1999-2011 ImageMagick Studio LLC

Features: OpenMP    

</pre>

h2. Deploy Django, MagickWand and Pyton Image Library Python packages

Install these Python packages using @easy_install@:

* If you do NOT have and do NOT want to download the MAUS software and have deployed Python 2.7 as a super-user then, first log in as super-user e.g. using @sudo su -@ or @su@.

* Run,

<pre>

$ easy_install django

$ easy_install magickwand

$ easy_install pil

</pre>

Check MagickWand,

<pre>

$ python

$ import magickwand

$ from magickwand.image import Image

...

</pre>

* If you get an error like,

<pre>

Traceback (most recent call last):

  File "<stdin>", line 1, in <module>

  File "build/bdist.linux-i686/egg/magickwand/image.py", line 2, in <module>

  File "build/bdist.linux-i686/egg/magickwand/api/__init__.py", line 1, in <module>

    #

  File "build/bdist.linux-i686/egg/magickwand/api/lib.py", line 11, in <module>

  File "/home/michaelj/maus-bzr/maus/third_party/install/lib/python2.7/ctypes/__init__.py", 

  line 353, in __init__ self._handle = _dlopen(self._name, mode)

OSError: libMagickWand.so.5: cannot open shared object file: 

 No such file or directory

</pre>

* then run @ldconfig@ as described in the instructions for ImageMagick above.

h2. Deploy Apache 2.2

Apache 2.2 (http://httpd.apache.org/) is an HTTP server. For full deployment information, see http://httpd.apache.org/docs/current/install.html

If you do *not* want to use Apache 2 but are happy to use the stand-alone lightweight Django web server then *go down to* Deploy the MAUS Django web front-end.

* Log in as super-user e.g. using @sudo su -@ or @su@.

* Download,

<pre>

$ wget http://mirrors.ukfast.co.uk/sites/ftp.apache.org//httpd/httpd-2.2.22.tar.gz

</pre>

* Extract,

<pre>

$ gzip -d httpd-2.2.22.tar.gz 

$ tar xvf httpd-2.2.22.tar

$ cd httpd-2.2.22

</pre>

* Configure,

<pre>

$ ./configure

</pre>

** This uses a default deployment directory of @/usr/local/apache2@.

* Compile,

<pre>

$ make 

</pre>

* Install,

<pre>

$ make install 

</pre>

* Start-up server,

<pre>

$ /usr/local/apache2/bin/apachectl -k start

</pre>

** If you get an error like,

<pre>

(98)Address already in use: make_sock: could not bind to address [::]:80

(98)Address already in use: make_sock: could not bind to address 0.0.0.0:80

no listening sockets available, shutting down

Unable to open logs

</pre>

** Then edit @/usr/local/apache2/conf/httpd.conf@,

<pre>

$ xemacs /usr/local/apache2/conf/httpd.conf 

</pre>

** and change,

<pre>

Listen 80 

</pre>

** to a port that is not in use e.g.

<pre>

Listen 9090

</pre>

** and start Apache,

<pre>

$ /usr/local/apache2/bin/apachectl -k start

</pre>

* Browse to http://localhost:8080 (or whatever port you specified above) and you should see @It works!"@

Useful files:

* Configuration: @/usr/local/apache2/conf/httpd.conf@

* Error log: @/usr/local/apache2/logs/error_log@

h2. mod_wsgi deployment

mod_wsgi (http://code.google.com/p/modwsgi/) is an Apache module allowing the hosting of Python applications which suppport Python's WSGI (Web Server Gateway Interface). For full deployment information, see http://code.google.com/p/modwsgi/wiki/QuickInstallationGuide, http://code.google.com/p/modwsgi/wiki/InstallationInstructions and  http://code.google.com/p/modwsgi/wiki/InstallationIssues

* Download latest release (July 2010),

<pre>

$ wget http://modwsgi.googlecode.com/files/mod_wsgi-3.3.tar.gz

</pre>

* Extract,

<pre>

$ gunzip mod_wsgi-3.3.tar.gz 

$ tar -xf mod_wsgi-3.3.tar

$ cd mod_wsgi-3.3

</pre>

* Set Python library path. 

** If you have Python 2.7 installed and it is your default Python then skip this step. 

** If you are using Python 2.7 in the MAUS software then set @LD_PYTHON_PATH@ to the location of its libraries e.g. if using Python bundled with MAUS, set:

<pre>

$ export LD_LIBRARY_PATH=/home/user/maus/third_party/install/lib/

</pre>

* Configure,

** If you have Python 2.7 installed and it is your default Python then run,

<pre>

$ ./configure --with-apxs=/usr/local/apache2/bin/apxs

</pre>

** If you are using Python 2.7 in the MAUS software you need to provide the path, so run,

<pre>

$ ./configure --with-apxs=/usr/local/apache2/bin/apxs

  --with-python=/home/user/maus/third_party/install/bin/python2.7

</pre>

** If you get an error like:

<pre>

/home/user/maus/third_party/install/bin/python2.7: error while loading 

shared libraries: libpython2.7.so.1.0: cannot open shared object file: 

No such file or directory

</pre>

** Then set the @LD_LIBRARY_PATH@ as above.

** If you get an error like:

<pre>

checking for apxs2... no

checking for apxs... no

checking Apache version... ./configure: line 1704: apxs: command not found

./configure: line 1704: apxs: command not found

./configure: line 1705: apxs: command not found

./configure: line 1708: /: is a directory

checking for python... /home/user/maus/third_party/install/bin/python

./configure: line 1877: apxs: command not found

configure: creating ./config.status

config.status: error: cannot find input file: Makefile.in

</pre>

** Then you forgot to provide the path to Apache's @apxs@ command,

* Compile,

<pre>

$ make

</pre>

* Install,

<pre>

$ make install

</pre>

* A @mod_wsgi.so@ library is installed in @/usr/local/apache2/modules@.

* Configure Apache, edit @/usr/local/apache2/conf/httpd.conf@,

<pre>

$ xemacs /usr/local/apache2/conf/httpd.conf 

</pre>

* and add,

<pre>

LoadModule wsgi_module modules/mod_wsgi.so

</pre>

* Set the @LD_LIBRARY_PATH@ in the Apache environment.

** If you have Python 2.7 installed and it is your default Python then skip this step. 

** If you are using Python 2.7 in the MAUS software then set @LD_PYTHON_PATH@ to the location of its libraries e.g. if using Python bundled with MAUS, then:

*** Edit @/usr/local/apache2/bin/envvars@ and add a line to set the Python library path e.g.

<pre>

LD_LIBRARY_PATH="/home/user/maus/third_party/install/lib/:$LD_LIBRARY_PATH" 

</pre>

*** Ensure that the permissions in this path allow group and world read and execute permission (755) e.g.:

<pre>

$ ls -l /home

drwxr-xr-x 26 user group 4096 Mar  6 10:08 user

</pre>

** If not then set these,

<pre>

$ chmod go+rx /home/user

</pre>

* Restart Apache,

<pre>

$ /usr/local/apache2/bin/apachectl restart

</pre>

* If all is well you should see, in @/usr/local/apache2/logs/error_log@ a line like,

<pre>

[Tue Feb 07 18:50:37 2012] [notice] Apache/2.2.22 (Unix) mod_wsgi/3.3 

Python/2.7.2 configured -- resuming normal operations

</pre>

* If you see an error like,

<pre>

[Tue Feb 07 18:46:40 2012] [notice] SIGHUP received.  Attempting to restart

httpd: Syntax error on line 55 of /usr/local/apache2/conf/httpd.conf: Cannot 

load /usr/local/apache2/modules/mod_wsgi.so into server: 

libpython2.7.so.1.0: cannot open shared object file: No such file or directory

</pre>

** then you have to set the @LD_LIBRARY_PATH@ as above.

* If you see an error like,

<pre>

Could not find platform independent libraries <prefix>

Could not find platform dependent libraries <exec_prefix>

Consider setting $PYTHONHOME to <prefix>[:<exec_prefix>]

ImportError: No module named site

</pre>

** then it is likely you did not set the file permissions for the directory in which Python is as described above.

* Clean up,

<pre>

$ make clean

</pre>

To check your installation (following http://code.google.com/p/modwsgi/wiki/CheckingYourInstallation),

* List server information,

<pre>

$ /usr/local/apache2/bin/httpd  -V

Server version: Apache/2.2.22 (Unix)

...

Server MPM:     Prefork

  threaded:     no

    forked:     yes (variable process count)

Server compiled with....

 -D APACHE_MPM_DIR="server/mpm/prefork"

...

</pre>

** Important information is the version and prefork settings,

* List compiled-in modules,

<pre>

$ /usr/local/apache2/bin/httpd  -l

Compiled in modules:

...

  prefork.c

</pre>

** You should see @prefork.c@.

* List dynamically-loaded modules,

<pre>

$ /usr/local/apache2/bin/httpd  -M

 mpm_prefork_module (static)

 ...

 wsgi_module (shared)

 ...

</pre>

** You should see @wsgi_module@.

** If this fails with,

<pre>

httpd: Syntax error on line 55 of /usr/local/apache2/conf/httpd.conf: 

Cannot load /usr/local/apache2/modules/mod_wsgi.so into server: 

libpython2.7.so.1.0: cannot open shared object file: No such file or directory

</pre>

** Then set your @LD_LIBRARY_PATH@ as above and try again,

<pre>

$ export LD_LIBRARY_PATH="/home/michaelj/maus-bzr/maus/third_party/install/lib/:$LD_LIBRARY_PATH"

$ /usr/local/apache2/bin/httpd -M

Loaded Modules:

...

</pre>

* List modules linked to by @mod_wsgi@:

<pre>

$ ldd /usr/local/apache2/modules/mod_wsgi.so

...

libpython2.7.so.1.0 => /home/michaelj/maus-bzr/maus/third_party/install/lib/libpython2.7.so.1.0 

(0x00110000)

...

</pre>

** You should see the link to your Python library.

h2. Deploy the MAUS Django web front-end

* Check-out the MAUS Django code,

<pre>

$ bzr branch -v lp:~michaelj-h/maus-apps/devel maus-apps

</pre>

* Set up environment,

<pre>

$ cd maus-apps

$ ./configure

$ ./install.sh

</pre>

* Copy a couple of sample images,

<pre>

$ cp images/* media/raw

</pre>

* Log in as super-user e.g. using @sudo su -@ or @su@.

* Edit Apache 2.2 environment, so it has access to the MAUS and MAUS web-front end environments (in particular all the Python libraries that have been easy_installed):

<pre>

$ xemacs -nw /usr/local/apache2/bin/envvars

</pre>

* Add, changing to use your own paths,

<pre>

source /home/michaelj/maus-bzr/maus/env.sh 

source /home/michaelj/maus-apps/env.sh

</pre>

* Ensure that the permissions in to your paths allow group and world read and execute permission (755) e.g.:

<pre>

$ ls -l /home

drwxr-xr-x 26 michaelj epcc 4096 Mar  6 10:08 michaelj

</pre>

** If not then set these,

<pre>

$ chmod go+rx /home/michaelj

</pre>

* Edit Apache 2 configuration,

<pre>

$ xemacs -nw /usr/local/apache2/conf/httpd.conf

</pre>

Add,

<pre>

WSGIScriptAlias / ${MAUS_WEB_DIR}/apache/django.wsgi  

# Location of django.wsgi 

<Directory ${MAUS_WEB_DIR}/apache> 

Order deny,allow  

Allow from all  

</Directory> 

</pre>

* where:

** @/@ specifies the root URL - so all URL requests will be directed to Django.

** @/...@ - location of WSGI file within the MAUS Django project.

* Restart Apache 2.2,

<pre>

$ /usr/local/apache2/bin/apachectl restart

</pre>

* Test,

** Visit http://localhost:8080/maus/, remembering to change the port number if you use a custom port.

For general information on Django deployment under Apache 2.2/mod_wsgi, see https://docs.djangoproject.com/en/1.3/howto/deployment/modwsgi/ and  http://code.google.com/p/modwsgi/wiki/IntegrationWithDjango.