Skip to content

Latest commit

 

History

History
193 lines (130 loc) · 5.63 KB

wsgi.rst

File metadata and controls

193 lines (130 loc) · 5.63 KB
Raw

Running Kuma with mod_wsgi

Requirements

  • See the installation docs <installation>.
  • Apache HTTP server
  • mod_rewrite
  • mod_headers
  • mod_expires
  • mod_wsgi
  • Not mod_python! It is incompatible with mod_wsgi.

Overview

Setting up Kuma to run as a WSGI application is fairly straightforward. You will need to install the requirements and clone the vendor repo as described in the installation docs <installation>.

There are 3 steps once Kuma is installed:

  • Set the document root.
  • Set up aliases.
  • Some file permissions.
  • Set up WSGI itself.

Apache Modules

Most of the Apache modules are part of a default Apache install, but may need to be activated. If they aren't installed, all of them, including mod_wsgi should be installable via your favorite package manager.

WSGI Configuration

In the Apache config (or <VirtualHost>) you will need the following:

Note that values may be slightly different.

DocumentRoot /path/to/kuma/webroot/

<Directory "/path/to/kuma/webroot/">
    Options +FollowSymLinks
</Directory>

Alias /media/ "/path/to/kuma/media/"
Alias /admin-media/ \
    "/path/to/kuma/vendor/src/django/django/contrib/admin/media/"

WSGISocketPrefix /var/run/wsgi

WSGIDaemonProcess kuma processes=8 threads=1 \
    maximum-requests=4000
WSGIProcessGroup kuma

WSGIScriptAlias /k "/path/to/kuma/wsgi/kuma.wsgi"
WSGISocketPrefix:

May or may not be necessary. It was for me.

WSGIDaemonProcess:

processes should be set to the number of cores. threads should probably be left at 1. maximum-requests is good at between 4000 and 10000.

WSGIScriptAlias:

Will make Kuma accessible from http://domain/k, and we use rewrites in webroot/.htaccess to hide the /k. This will change soon, and the .htaccess file won't be necessary.

The Alias directives let Kuma access its CSS, JS, and images through Apache, reducing the load on Django.

Configuration

Most of our settings.py is under version control, but can be overridden in a file called settings_local.py in the base of the app (the same place as settings.py). You can see example settings in docs/settings/settings_local.prod.py:

settings/settings_local.prod.py

File Permissions

To upload files, the webserver needs write access to media/uploads and all its subdirectories. The directories we currently use are:

media/uploads
media/uploads/avatars
media/uploads/images
media/uploads/images/thumbnails
media/uploads/gallery/images
media/uploads/gallery/images/thumbnails
media/uploads/gallery/videos
media/uploads/gallery/videos/thumbnails

media/uploads and its subdirectories should never be added to version control, as they are installation-/content-specific.

Product Details JSON

Some people have issues with django-mozilla-product-details and file permissions. The management command manage.py update_product_details writes a number of JSON files to disk, and the webserver then needs to read them.

If you get file system errors from product_details, make sure the files are readable by the webserver (should be by default) and the directory is readable and executable.

By default, product_details stores the JSON files in:

vendor/src/django-mozilla-product-details/product_details/json

This is configurable. If you have multiple web servers, they should share this data. You can set the PROD_DETAILS_DIR variable in settings_local.py to a different path, for example on NFS.

Debugging

Debugging via WSGI is a little more interesting than via the dev server. One key difference is that you cannot use pdb. Writing to stdout is not allowed within the WSGI process, and will result in a Internal Server Error.

There are three relevant cases for debugging via WSGI (by which I mean, where to find stack traces):

Apache Error Page

So you've got a really bad error and you aren't even seeing the Kuma error page! This is usually caused by an uncaught exception during the WSGI application start-up. Our WSGI script tries to run all the initial validation that the dev server runs, to catch these errors early.

So where is the stack trace? You'll need to look in your Apache error logs. Where these are is OS-dependent, but a good place to look is /var/log/httpd. If you are using SSL, also check the SSL VirtualHost's logs, for example /var/log/httpd/ssl_error_log.

With DEBUG=True

With DEBUG = True in your settings_local.py, you will see a stack trace in the browser on error. Problem solved!

With DEBUG=False

With DEBUG = False in your settings_local.py, you'll see our Server Error message. You can still get stack traces, though, by setting the ADMINS variable in settings_local.py:

ADMINS = (
    ('me', 'my@email.address'),
)

Django will email you the stack trace. Provided you've set up email <email>.

Reloading WSGI

WSGI keeps Python and Kuma running in an isolated process. That means code changes aren't automatically reflected on the server. In most default configurations of mod_wsgi, you can simply do this:

touch wsgi/kuma.wsgi

That will cause the WSGI process to reload.