Quickstart

Here's how to get started with artshow-jockey quickly, with little knowledge of Django. You'll still need to know the basics of your installation, a little bit about Python syntax, Apache configuration, and how to install system packages, and python packages. This is regularly tested on both Linux and Mac machines.

A message to experienced Django developers

These instructions will provide a complete Django project without needing to use "startproject". If you want to build the project from scratch and include the Artshow Jockey components, Django Setup might work better for you. See also the Project Layout Philosophy.

Installation Instructions

Installing required packages

• Ensure you have Python, at least version 2.5. This has been tested to work on Python 2.6 and 2.7. If your default is 2.4, but have a later version installed, you'll need to wrangle headers of some .py files to ensure the right version runs, or run all python commands specifying "python2.7" (for example) explicitly.
• Install the following python libraries. If you're using "pip" to install packages from PyPI, you can do pip install django, for example. The PyPI names are in parenthesis.
• Django version 1.4 (version 1.4.2 is current). Django 1.3 and earlier will not work. (django)
• South (south)
• Reportlab 2.5 or later (reportlab)
• django-ajax-selects (django-ajax-selects)
• pdfrw (pdfrw) - needed to print bid sheets, but can be ignored if you don't need this feature
• Install the mod_wsgi Apache module. mod_wsgi is compiled against a specific python version. Make sure you're using the right version for the version of Python you want to run.
• RedHat/CentOS 6 users can install the mod_wsgi package. The Python version under RedHat/CentOS 5.x is Python 2.4, which is too old. Install the python26 python26-devel and python26-mod_wsgi packages from EPEL.
• Ubuntu users have a mod-wsgi inside /etc/apache2/mods-available which can be linked from mods-enabled. I'm not an Ubuntu user, so I'm sure there's an easier way to enable it than creating your own symlink. Help?

Installing Artshow Jockey

Two recommended ways to obtain the Artshow Jockey source:

• You can clone the git repository and use it straight from there:

git clone git://github.com/chmarr/artshow-jockey.git

• You can download a Zip file, and unzip it:

curl -o artshow-jockey.zip https://nodeload.github.com/chmarr/artshow-jockey/zipball/master
unzip artshow-jockey.zip

In both cases a directory called "artshow-jockey" or "artshow-jockey-master" will be created. You can move or rename this to where you want. For the rest of these examples, this directory will be called PROJDIR. You should replace this with the full path name to that directory. Change into that directory: cd PROJDIR

Customising settings

Make a copy of the example settings file - cp local_settings.py.example local_settings.py - and edit it using the in-file comments and the following as a guide:

• DATABASES - sqlite3 is a simple file-based database. To use this, just replace PROJDIR. You can use PostgreSQL or MySQL databases instead if you're comfortable with that.
• STATIC_ROOT - Replace PROJDIR, or replace completely if you'd rather static files live elsewhere.
• SECRET_KEY - Fill the quotes with about 50 random characters. It can be anything. You can use this command:

python -c 'from django.utils.crypto import get_random_string;import string;print "SECRET_KEY =",repr(get_random_string(50,string.printable))'

• ARTSHOW_* - Replace these with values suitable for your show
• SITE_NAME - Name of the site used in the non-artshow-specific pages. Usually just the same as ARTSHOW_SHOW_NAME
• SITE_ROOT_URL - The proper URL for the site, used for e-mailing purposes. No trailing slash.
• RECAPTCHA_* - If you're allowing artists to log-in, Recaptcha is used for password recovery. Visit the site and get your own keys.

Setting up the database

• mkdir data
• ./manage.py syncdb This will create the tables and prompt you to create a superuser. If you skip this now, you can create one later with ./manage.py createsuperuser.
• ./manage.py migrate This creates the tables for applications managed by the South database migration too.
• ./manage.py loaddata artshow/fixtures/* This loads some initial data into the tables.
• ./manage.py collectstatic This copies all static files into a directory specified by STATIC_ROOT.

Test

Django comes with a built-in but low performance web server useful for development. You can use this to test what you have so far: ./manage.py runserver

This will create a webserver listening on localhost, port 8000. You can use a browser against this address only if the browser runs on the same machine as the server. You can request the server to listen on all available addresses by using: ./manager.py runserver 0.0.0.0:8000. Please be aware of any security implications, or firewalls.

If you can't run a browser on the server, you should still be able to use curl: curl http://localhost:8000/admin/

However, even just running 'runserver' will test a fair amount of the django installation.

Ctrl-C to stop the development web server.

Preparing Apache

Create a configuration for apache. How to do this will depend on your installation. Following is an example configuration. Replace the 5 (or so) instances of PROJDIR appropriately, and replace USER and GROUP with that required to access the files and database. For the moment I recommend it just be your own, non-root, login name and group. Also, set ServerName and DocumentRoot appropriately. I create a empty directory called /var/www/empty that I always leave empty, just for this purpose:

<VirtualHost *:80>
	ServerName myserver.example.com
	DocumentRoot /var/www/empty

	# Don't forget the trailing slash on both parameters	
	Alias /static/ PROJDIR/static/

	WSGIScriptAlias / PROJDIR/artshowjockey/wsgi.py
	WSGIDaemonProcess artshowjockey user=USER group=GROUP processes=3 threads=3 python-path=PROJDIR home=PROJDIR
</VirtualHost>
	
<Directory PROJDIR>
	WSGIProcessGroup artshowjockey
</Directory>

• Restart Apache to have it load the new settings.

Note: If you need to make any Django application changes (updating settings or changing .py files), you must either restart Apache, or simply update the timestamp on the wsgi.py file. Eg: touch artshowjockey/wsgi.py .

Test

Visit http://myserver.example.com/admin/ and log-in. You should be presented with a "Django Administration" page. If not, there's trouble!

Trouble?

The web server error log may give you some indication of what's going on, such as permission errors or crashes. Also, consider turning django debugging on, for as little time as possible, to see if anything's reported there. Here are some possible issues, and solutions:

• The instructions above assume you've created a user (here called "USER") to house the code and django settings files. If you've removed the "user" and "group" settings from the WSGI settings, it will still work but you'll need to worry about permissions.
• If you're sticking to using sqlite3 for your database, the process running the code needs to be able to write to the database file and the directory it's in; sqlite3 creates additional files in the same directory for synchronisation/locking purposes.
• If some information is displaying, but the CSS and JS are not being loaded, look for these problems:
• The Apache alias has trailing slashes on both parameters
• The static directory is reachable by the apache user (usually 'nobody' or 'www-data'). This means that not only does apache need to be able to read the files, but it must be able to traverse to the static directory. The 'execute' bit for directories means "traversal permission". Try this as a fix:

cd PROJDIR/static
chmod a+x . .. ../.. ../../.. ../../../.. ../../../../.. ../../../../../..

• If you've made any changes to .py files, don't forget to either touch wsgi.py or restart the web server.
• Python will save compiled files if able to. If not, it will cope but with degraded performance. However, it is possible that Python has been fooled into loading an out of date compiled file. If problems persist, as a last resort try this:

cd PROJDIR
find . -name \*.pyc -print0 | xargs -0 rm
python -m compileall .
touch artshowproj/wsgi.py

If that actually fixes something, let me know.

Now What?

• Visit http://myserver.example.com/admin/ and log in
• Click "Spaces". Some spaces have been set up for you. Create/Delete/Edit to whatever is appropriate for your show.
• Click "Artists" and start entering your artists.
• Click "Email Templates" and create a template from the example. Use this to email one artist based on entered information and check that email sending works. With the default settings, it will attempt to connect to a SMTP server at localhost. See the Django documentation on E-mail Backends on how to configure this, but note that using /usr/sbin/sendmail is not supported. Yet.
• Bug Chris to create better documentation.
• Use the GitHub Issues system to report bugs, make requests, or seek help.

Backups

If you've kept to the standard installation, all the files you'll need are in PROJDIR. Since sqlite3 is a file-based database, this can be simply copied as long as there's no transaction in process, but recent versions of the sqlite3 CLI command contain a backup command.

• Make a recursive copy or archive of PROJDIR. Eg: tar cvzf artshowbackup.tar.gz PROJDIR
• Make a live backup of the database: Eg: sqlite3 PROJDIR/data/artshowjockey.db '.backup artshowbackup.db' and drop it into the recursive copy.
• Done!

You may choose to only backup the database and the local_settings.py file.

Restores

Make sure the web server is down during this.

If you backed up the whole project just copy it back into place.

If not, reinstall from the instructions and overwrite your local_settings.py file, and the database.

Code Updates

If you obtained the code using git, updates are easy to apply. If not, you'll need a little wrangling with the zipfile supplied, but it's nearly as reliable. In either case, you'll need a couple of steps to ensure Django recognises the changes.

• Shut down the web server (or block access with a redirect in Apache) and back up the installation.
• To retrieve updates, either:
• run git pull inside PROJDIR. Or,
• Download another zip file, and extract it over the top of the existing installation.
• Apply schema changes:

./manage.py syncdb
./manage.py migrate

• Start the web server.
• If you simply blocked access, you'll need to tell Django to reload its modules. Either restart the web server, or touch PROJDIR/artshowjockey/wsgi.py.