Production Install and Config Guide

This guide will run through getting Formunculous installed and configured on a production Web server such as apache using WSGI. If you just want to get started right away and mess around with func. Check out the Quickstart guide.

Func is packaged using a setuptools script, so system wide installation is as easy as extracting the tarball from the download page, and running:

 python setup.py install

This should get it installed in the system's Python path. You can always choose not to run the setup though, and just manually add it to the path of your Web server.

settings.py

To get up and running after we have installed the application we'll look at what Func needs in the settings.py file. If none of this is making sense, you'll probably want to take a look at the Django tutorial to get a feel for how projects are configured. Here are the relevant sections form Formunculous:

.
.
.
FORMUNCULOUS_REVIEW_PAGE_SIZE = 10

APP_STORAGE_ROOT = '/tmp'
APP_STORAGE_URL = '/apply/'

LOGIN_REDIRECT_URL = '/'
.
.
.
INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.admin',
    'formunculous',
    'django.contrib.comments',
)
  

The first formunculous specific directive is the FORMUNCULOUS_REVIEW_PAGE_SIZE variable. This determines how many form submissions are shown per page of the review section. The default is 25, and this setting is not required.

The APP_STORAGE_ROOT and APP_STORATE_URL are used for forms that use file or image types. The ...ROOT variable tells func where to store uploaded files. This directory will need to be writable by the server running Django—typically www-data or apache for mod_wsgi or mod_python setups. The ...URL is the URL root to the func application as specified in the urls.py file.

The next highlighted section is the INSTALLED_APPS tuple in every Django project. Func requires that it be listed as well as the built-in comments application—django.contrib.comments. The comments application is used in the review area of Formunculous.

I have also made note of the LOGIN_REDIRECT_URL setting. This is a Django default configuration variable, and if you are using authenticated forms, then you will need to specify a URL to send users to by default or you may see some strange behavior.

urls.py

Now we'll take a look at the URL configuration file. This should be very straight forward if you are used to setting up Django projects. We simply need to include the Formunculous URLs and give them a prefix to work from:

urlpatterns = patterns('',
    (r'^func/', include('formunculous.urls')),
)

Here we will use func as the prefix to our formunculous urls. This will lead to form urls looking like /func/forms/name-of-form. You could probably be more creative here and use something like 'online' as the prefix, so urls are of the form /online/forms/name-of-form.

Media Files

This is the part that tends to be the hangup for configuring formunculous on production servers. The static media files—images, javascript, flash, and css. The harness that comes included serves out these files automatically, but in a production mod_wsgi/mod_python environment this doesn't occur by default. So we'll need to make a copy or symlink of the static media files included with formunculous.

The media files for func are stored in the formunculous/media/formunculous directory in the tarball. You generally will just have to make a symlink or do a full directory copy of this folder to your existing Django media folder. This is the location in your settings.py file called MEDIA_ROOT.

Note: If you used the setup.py install method of installing formunculous you can typically find the media folder in the python packages directory. On Ubuntu/Debian this is something like /usr/local/lib/python2.6/dist-packages/formunculous-2.1.0_final-py2.6.egg/, on Red Hat and similar this will usually be /usr/lib/python2.x/site-packages/formunculous-2.1.0_final-py2.x.egg/.

So doing something like: ln -s /usr/local/lib/python2.6/dist-packages/formunculous-2.1.0_final-py2.6.egg/formunculous/media/formunculous /path/to/media/root/ should take care of all the javascript, css, flash, and images needed by formunculous.

Media Update as of Formunculous 2.2.0

As of version 2.2.0 and higher, there is now a command for automatically copying and or symlinking the formunculous static media to the static media folder defined in your settings. You can just type:

	  python manage.py func_media_symlink
	  
	  -- or  --
	  
	  python manage.py func_media_copy
	

from your project folder to either symlink or copy respectively.

That pretty much sums up everything I can think of that comes up when installing func to a production server. If you have followed this and are still having issues, let me know what they are by either hitting the support section or contacting me directly via the Contact form.