Merge lp:~muffinresearch/graphite/mod_wsgi_example into lp:~graphite-dev/graphite/main

[Stuart Colville]

This branch provides a basic example for running graphite under mod_wsgi along with updated docs.

The rationale behind this is that mod_python is not currently actively developed [1] and mod_wsgi is the recommended approach for using django in production with Apache. [2]

The branch retains the mod_python examples and instructions to be backwards compatible for existing users though I've written the docs adding a gentle emphasis that mod_wsgi is recommended.

[1] http://blog.dscpl.com.au/2010/05/modpython-project-soon-to-be-officially.html
[2] http://docs.djangoproject.com/en/dev/howto/deployment/modwsgi/

[chrismd (chrismd)]

Sorry it took me so long to get around to looking at this. Some of this is already in trunk (the example vhost config) but merging in the INSTALL doc update, etc

review: Approve

=== modified file 'INSTALL'
--- INSTALL	2010-03-25 15:01:48 +0000
+++ INSTALL	2010-06-15 18:55:42 +0000
@@ -18,7 +18,7 @@
  pycairo (with PNG backend support)
  django
  json (standard in python2.6) or simplejson
- mod_python (optional - but highly recommended)
+ mod_wsgi (optional, recommended) or mod_python (optional)
  python-ldap (optional - needed for ldap-based webapp authentication)
  python-memcached (optional - needed for webapp caching, big performance boost)
  python-sqlite2 (optional - a django-supported database module is required)
@@ -67,13 +67,37 @@
 
  Apache Configuration
 -------------------------------------------------------------------------------
-First off, Apache has to have mod_python configured, this is usually done
-by including a line like the following in your httpd.conf:
+When using apache there are two modules available to provide support for python
+web application.
+
+Graphite currently provides example configurations for both of these modules. 
+Of the two mod_wsgi is the most up to date and actively maintained so it's 
+highly recommended if you are starting afresh.
+
+ Apache Configuration for Mod_wsgi (recommended)
+-------------------------------------------------------------------------------
+
+If you are using mod_wsgi, Apache has to have mod_wsgi configured, 
+this is usually done by including a line like the following in your 
+httpd.conf:
+
+LoadModule wsgi_module    modules/mod_wsgi.so
+
+ Apache Configuration for Mod_python
+-------------------------------------------------------------------------------
+
+If you choose to use mod_python, Apache has to have mod_python configured, 
+this is usually done by including a line like the following in your 
+httpd.conf:
 
 LoadModule python_module    modules/mod_python.so
 
-Second you should configure a vhost for graphite (technically it doesn't have
-to be a vhost but its good practice). This can be done one of two ways.
+ General Apache Configuration
+-------------------------------------------------------------------------------
+
+Once you have configured the apache module you are using you should configure 
+a vhost for graphite (technically it doesn't have to be a vhost but its good 
+practice). This can be done one of two ways.
 
 The first way (highly preferred) is to include independent vhost configs.
 
@@ -82,10 +106,11 @@
 
 Then simply drop your graphite vhost conf file into the vhosts.d/ directory
 (or whatever directory your system uses) and apache is ready. You can use
-the examples/example-graphite-vhost.conf file included in this package as a
-starting point.
+either of the example vhost confs as a starting point (See the examples 
+directory of this package and choose the correct one based on whether you 
+are using mod_wsgi or mod_python.)
 
-The second approach is to copy the contents of the graphite vhost conf file
+The second approach is to copy the contents of your chosen graphite vhost conf file
 and insert it down at the end of your httpd.conf.
 
 
 
=== modified file 'README'
--- README	2009-09-14 21:40:04 +0000
+++ README	2010-06-15 18:55:42 +0000
@@ -2,7 +2,7 @@
 -------------------------------------------------------------------------------
 Graphite consists of two major components
 
- 1) the frontend Django webapp that runs under mod_python Apache
+ 1) the frontend Django webapp that runs under Apache with mod_python or mod_wsgi
  2) the backend carbon-cache.py daemon
 
 Client applications connect to the running carbon-cache.py daemon on port 2003 and send it
 
=== modified file 'check-dependencies.py'
--- check-dependencies.py	2010-03-25 15:01:48 +0000
+++ check-dependencies.py	2010-06-15 18:55:42 +0000
@@ -69,14 +69,25 @@
 
 
 # Test for mod_python
+mod_python_installed = 0
 try:
   import mod_python
+  mod_python_installed = 1
 except:
   print "[WARNING] Unable to import the 'mod_python' module, do you have mod_python installed for python %s?" % py_version
-  print "This means you will only be able to run graphite in the development server mode, which is not"
-  print "recommended for production use."
+  print "This means you will only be able to run graphite under mod_wsgi (if installed)"
+  print "OR the development server mode, which is not recommended for production use."
   warning += 1
 
+# Non-test for mod_wsgi
+print "[WARNING] Unable to reliably test for the presence of the 'mod_wsgi' module, do you have mod_wsgi installed?"
+print "Note: mod_wsgi is highly recommended for serving python web applications with Apache"
+mp_instructions = "mod_python (installed) \nOR " if mod_python_installed else ""
+print "If mod_wsgi is not installed you will only be able to run graphite "\
+        "under %sthe development server mode, which is not recommended for production use." % mp_instructions
+warning += 1
+
+
 
 # Test for python-memcached
 try:
 
=== renamed file 'examples/example-graphite-vhost.conf' => 'examples/example-graphite-mod-python-vhost.conf'
=== added file 'examples/example-graphite-mod-wsgi-vhost.conf'
--- examples/example-graphite-mod-wsgi-vhost.conf	1970-01-01 00:00:00 +0000
+++ examples/example-graphite-mod-wsgi-vhost.conf	2010-06-15 18:55:42 +0000
@@ -0,0 +1,34 @@
+NameVirtualHost *:80
+
+# You may need to manually edit this file to fit your needs.
+# This configuration assumes the default installation prefix
+# of /opt/graphite/, if you installed graphite somewhere else
+# you will need to change all the occurances of /opt/graphite/
+# in this file to your chosen install location.
+
+<VirtualHost *:80>
+    DocumentRoot "/opt/graphite/webapp"
+
+    ErrorLog /opt/graphite/storage/log/webapp/error.log
+
+    WSGIDaemonProcess graphite user=www-data group=www-data threads=25
+    WSGIProcessGroup graphite
+
+    WSGIScriptAlias / /opt/graphite/webapp/graphite/graphite.wsgi
+
+    <Directory /opt/graphite/webapp>
+        Order deny,allow
+        Allow from all
+    </Directory>
+	
+    # NOTE: In order for the django admin site media to work you
+	# must change @DJANGO_ROOT@ to be the path to your django
+	# installation, which is probably something like:
+	# /usr/lib/python2.6/site-packages/django
+    Alias /media/ "@DJANGO_ROOT@/contrib/admin/media/"
+    <Directory @DJANGO_ROOT@/contrib/admin/media>
+        Order deny,allow
+        Allow from all
+    </Directory>
+
+</VirtualHost>
 
=== added file 'webapp/graphite/graphite.wsgi'
--- webapp/graphite/graphite.wsgi	1970-01-01 00:00:00 +0000
+++ webapp/graphite/graphite.wsgi	2010-06-15 18:55:42 +0000
@@ -0,0 +1,19 @@
+# You may need to manually edit this file to fit your needs.
+# This configuration assumes the default installation prefix
+# of /opt/graphite/, if you installed graphite somewhere else
+# you will need to change all the occurances of /opt/graphite/
+# in this file to your chosen install location.
+
+import os
+import sys 
+sys.path.insert(0, '/opt/graphite/webapp/') 
+os.environ['DJANGO_SETTINGS_MODULE'] = 'graphite.settings' 
+ 
+import django.core.handlers.wsgi 
+ 
+_application = django.core.handlers.wsgi.WSGIHandler() 
+ 
+def application(environ, start_response): 
+    environ['PATH_INFO'] = environ['SCRIPT_NAME'] + environ['PATH_INFO'] 
+    return _application(environ, start_response)
+