==================
Smug: Simple Setup
==================

Smug is built in the Django framework. If you aren't familiar with Django, I highly recommend that you familiarize yourself with the Django documentation. I'll repeat some of the steps here, but it's really best if you're already familiar with the process.


Cloning Smug
============

Currently, the only way to download Smug is by cloning its Git repository.  Pick a place to clone the repository to, such as a directory called ``clone`` inside of your home directory.  Within the ``clone`` directory, run::

    git clone git://mcnabbs.org/smug.git

This will create a directory called ``smug`` that has all of the Smug source code.


Create a Django Project
=======================

Clone the sample Smug Django project to your ``clone`` directory.  Just cd to the ``clone`` directory and run::

    git clone git://mcnabbs.org/django_smug.git

Make sure to replace the ``SECRET_KEY`` that comes with the sample repository.  You may also need to change a few settings in the ``settings.py`` file, such as the path to the database.  Either use ``generate_secret_key`` from django-command-extensions or run::

    python -c 'import random; print "".join([random.choice("abcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(-_=+)") for i in range(50)])'

The new ``SECRET_KEY`` goes in ``settings.py``.

To initialize the database, run "``python manage.py syncdb``".


Create a Smug Repository for Content
====================================

A sample Smug repository is available.  If you will just be using the Django development server (it's a local site only, or you're just testing), then you can run::

    git clone git://mcnabbs.org/smug_html.git

If you will be serving your site with Apache, you should check it out by running the following::

    mkdir /path/to/repository.git
    cd /path/to/repository.git
    git --bare init --shared=group
    chgrp -R shared_group_name .
    git fetch git://mcnabbs.org/smug_html.git master:master

Update the ``SMUG_REPOSITORIES`` setting in ``django_smug/settings.py`` to reflect the correct path to the ``smug_html.git`` repository.  Otherwise, Smug will be unable to find the repository.


Setting PYTHONPATH
==================

Python looks for modules in locations specified by the ``PYTHONPATH`` environment variable.  One way to deal with the ``PYTHONPATH`` is to create a directory called ``python`` in your home directory.  Add this directory to the PYTHONPATH by adding the line "``export PYTHONPATH=$HOME/python``" to your ``bashrc``, and reload the ``bashrc`` by running "``. $HOME/.bashrc``".  Any time you add a Python module, create a symbolic link in the ``python`` directory.  In the case of Smug, run::

    ln -s $HOME/clone/smug/smug $HOME/python/smug
    ln -s $HOME/clone/smug/gitlib $HOME/python/gitlib
    ln -s $HOME/clone/django_smug $HOME/python/django_smug


Django Development Server
=========================

If you're using the Django development server, you can cd to ``clone/django_smug``, run "``python manage.py runserver``", and go to ``http://localhost:8000/`` in a web browser. Note that the Django documentation has a lot of information about setting this up.


Django in Apache
================

If you're using Apache, you will need to set Python as the handler. You might have something like the following in ``httpd.conf`` (and if you want authenticated sessions to go over SSL, as I recommend, it should also go in ``ssl.conf``).

::

    <Location "/you/pick/the/location/">
        SetHandler python-program
        PythonPath "['/home/your_username/python'] + sys.path"
        PythonHandler django.core.handlers.modpython
        SetEnv DJANGO_SETTINGS_MODULE django_smug.settings
        #PythonDebug On
    </Location>

In this example, it really is important to have links to ``django_smug`` and ``smug`` in ``/home/your_username/python`` directory. Otherwise, Python won't know where to find these modules.
