= Ductus Development Instance =

Setting up a Ductus Development Instance is a great way to get a feel for the code and make any changes you would like to make.  Best of all, the system has a way of automatically pulling content from wikiotics.org, so you can make changes to the site's user interface and see how they work using actual content.  If you really want, you can even make your server face the public world and allow anybody else to use your improved version of Ductus (but let us know if you intend to do this; eventually you will need to register for an API key -- see ticket #48).  Keep in mind if you are distributing code (even Javascript code), anything that is a derivative work of Ductus must fall under GPLv3 or later.

== Install required dependencies ==

This list may not be completely up to date.  If in doubt, see source:setup.py for the latest information.

 * Python 2.6 or later (but not Python 3)
 * Django 1.2 or later
 * Creoleparser 0.7.2 or later (when tickets #38 and #44 are closed, we will depend on an even later version)
 * lxml
 * Python Imaging Library ("PIL")

== Obtain the source code ==

{{{
$ git clone git://git.garrison.cc/git/ductus.git
}}}

== Install optional dependencies ==

 * flickrapi (at the time of writing, this package is actually ''required'' for things to work properly; see #61)
 * pygments
 * recaptcha-client

== Set up site-specific settings ==

Create a file called {{{ductus_local_settings.py}}} in your {{{PYTHONPATH}}} with the following contents:

{{{
DATABASE_ENGINE = 'sqlite3'
DATABASE_NAME = 'ductus_data_path/db'

DUCTUS_MEDIA_PREFIX = "/static/"
DUCTUS_DISKCACHE_DIR = '/ductus_data_path/ductus-diskcache'
DUCTUS_WIKI_REMOTE = "http://alpha.wikiotics.org/wiki/"
}}}

Create a file {{{ductus_site.py}}} in your {{{PYTHONPATH}}} with the following contents:

{{{
from ductus.resource.storage import LocalStorageBackend, UnionStorageBackend, RemoteDuctusStorageBackend
local = LocalStorageBackend('/ductus_data_path/storage')
remote = RemoteDuctusStorageBackend("http://alpha.wikiotics.org/")
storage_backend = UnionStorageBackend([local, remote], collect_resources=True)
}}}

In both files, replace ''ductus_data_path'' with an appropriate pathname.  The code in {{{ductus_site.py}}} sets up a local storage backend, chained to a remote storage backend.  If a resource is not found in the local database, it will query alpha.wikiotics.org to see if it is available there (and then cache it indefinitely).

== Set up and run a development server ==

{{{
$ ./manage.py runserver
}}}

Assuming the above command returns no error messages, you can now point your browser to http://localhost:8000/

== Develop Ductus ==

Improve code.  Submit patches.  Read the DuctusDevelopmentGuide.  If your goal is to get patches accepted, bring up any major changes on the discussion list first.  Read the git documentation to understand how to rebase your changes onto the most recent development version of Ductus in the future.  If you haven't made any changes to your local version of Ductus, a regular "git pull" will suffice to update your repository and checkout.