README

Introduction
==============

Flother is the personal web site for Matt Riggott.  It's been through many
iterations but now it runs on Python 2.5 and Django 1.1 and is in active
development.  This is the complete source code, released under the GPL v3.0.

It includes seven apps that offer a blog, a photo library, geographical
locations, a contact form, file uploads, a Google-powered search, and a copy of
a Twitter user's status messages.  (See "Features" below for more information.)
It's fairly specific to my needs but you may find it useful either as a base for
your own site or to help you learn Django.

You can see the code in action at http://www.flother.com/.  For more
information, contact me: http://www.flother.com/contact/.


Features
==========

There are seven main apps within the project. The largest is a blog with
Akismet-moderated comments.  Entries are formatted using Markdown and can be
public, private, or draft.  Draft entries can be previewed on the site by admin
users.  Comments can be enabled entry by entry (i.e. one entry can have comments
while another doesn't) and use Gravatar for author photos.

Next are the two tightly-coupled apps photos and places.  Both are currently in
active development and will see a full geocoded photo library with an option to
import from Flickr.

Fourth comes a contact form that emails site admins each time a message is sent.
Akismet is used to check whether or not messages are spam — if they are, no
email is sent.  Messages are stored in the database.

Fifth, file uploads.  Files of any type can be uploaded and stored via the
admin.  Thumbnails of images are created and displayed in the admin.  A
Javascript-based interface for using files in blog entries is provided.

Sixth is a very simple app that stores a copy of a single Twitter user's
messages.  A management command is included that should be used periodically
to save new messages from Twitter.

And finally, site search.  Google's AJAX API is used (server-side) to perform a
site-wide search and return results on the site itself.


Future work
=============

    * Google sitemap for blog
    * Print style sheet
    * Home page that aggregates site content


Requirements
==============

The blog requires Python 2.5 and Django 1.1 and depends on the following
packages:

    * Python Imaging Library (http://www.pythonware.com/products/pil/)
    * Markdown (http://www.freewisdom.org/projects/python-markdown/)
    * Smartypants (http://web.chad.org/projects/smartypants.py/)
    * G. Raphaelli's Flickr.API (http://pypi.python.org/pypi/Flickr.API)
    * South (http://south.aeracode.org/)
    * Django Compress (http://code.google.com/p/django-compress/)
    * StaticGenerator (http://github.com/flother/staticgenerator)
    * Typogrify (http://code.google.com/p/typogrify/)
    * Participation Graphs (http://github.com/flother/participationgraphs)
    * Python Twitter (http://code.google.com/p/python-twitter/)

Note that StaticGenerator is a fork of Jared Kuolt's original, to allow
Nginx to server up pre-compressed version of the cache.

All these dependencies are listed in a PIP requirements file, requirements.txt,
in the root directory of the repository.


Installation
==============

1. Clone the read-only repo

     git clone git://github.com/flother/flother.git

2. Install the dependencies via PIP.  (If you use virtualenv you'll want to
   create a virtual environment and activate it first.)

     pip install -r requirements.txt

   If you don't use PIP you should wonder what you've been missing all this
   time, read up on it, and install it.

     http://www.b-list.org/weblog/2008/dec/15/pip/

3. Create a Bash script so you can run the site locally.  In the directory
   flother/flother, create a file called manage.sh and paste in the following
   three lines:

     #!/bin/bash
     export PYTHONPATH=..:$PYTHONPATH
     django-admin.py $@ --settings=flother.settings.development

4. You'll notice that the settings file Django's using in that script,
   flother.settings.development, doesn't exist.  The settings file that does
   come with the code, flother.settings.common, is a base settings file
   containing the shared settings you'll need to run the code.

   You should create a settings file to use in development that first imports
   the common settings and then sets its own.  Create a file in the
   flother/flother/settings directory called development.py and paste in the
   example code from this gist:

     http://gist.github.com/434537

   Note you'll need to add your Akismet API key (to test comments for spam) and
   your Flickr API key (to download your photos to the app) to these settings.
   URLs to discover both are included as comments.

5. Create your local database and superuser.

     cd flother/flother
     bash manage.sh syncdb
     bash manage.sh migrate

6. Run the server and head over to the admin.

     http://localhost:8000/admin/

   Note that the front-end won't work until you've created your first blog post.
   Once you've done that you're ready to rock and roll.

     http://localhost:8000/blog/


Management commands
=====================

There are three management commands in the project; each one is summarised
below.  For more information read through the code as it's fairly well
commented.

django-admin.py publishnewentries

    Because the site can be heavily cached (if you use the Static
    Generator-created content you can serve the blog static HTML files), any
    entry published in the future will only actually appear once the cache is
    flushed, not once its publishing date has passed.  To ensure the entry
    appears as expected, this command will check for entries whose
    ``published_at`` field is within the last hour.  If there are any, the cache
    will be cleared.

    This command should be run as an hourly cron job.

django-admin.py import_from_flickr

    Imports public photos from a Flickr account (based on settings.FLICKR_NSID)
    and stores them and their metadata in the database.

    This command should be run as regularly if you want to download your photos
    from Flickr.

django-admin.py import_user_timeline

    Imports messages from Twitter for one particular user.  The Twitter username
    is defined as ``TWITTER_USERNAME`` in the project's settings and is mapped
    to a database user using the ``TWITTER_USER_MAPPING`` setting, e.g.:

        TWITTER_USERNAME = "riggbot"
        TWITTER_USER_MAPPING = {
            "riggbot": "matt",
        }

    The value for ``TWITTER_USER_MAPPING["riggbot"]``, ``matt``, is the username
    for the database user you want to assign the Twitter messages to.

    This command should be run as regularly if you want to download your
    messages from Twitter.