Skip to content

Quickstart

Jump to bottom
chmarr edited this page Nov 28, 2012 · 22 revisions

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 packages or programs.

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)
  • South (south)
  • Reportlab 2.5 (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 is 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.

Preparing settings and database

  • cd PROJDIR
  • mkdir data
  • cp local_settings.py.example local_settings.py
  • Edit local_settings.py, and update the DATABASES and STATIC_ROOT variables to replace PROJDIR. You can use PostgreSQL or MySQL databases instead if you're comfortable with that. Also update the ARTSHOW_* variables to your preferred settings.
  • ./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.

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

	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 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.
  • Make sure the /static/ alias in the apache configuration exists and points to the right place, and that the Apache user (www-data or nobody) can transit to that directory. Ie: all parent directories above static should have the execute bit set, and all files in the directory should be readable.
  • 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, if problems persist, as a last resort try this:
cd PROJDIR
find . -name \*.pyc -delete
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'
  • Done!

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

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.
Clone this wiki locally