Installation

First of all, comics is just a Django application. Thus, if there are details not outlined in comics’ own docs, you’ll probably find the answer in Django’s docs. For example, database settings are mentioned on this page, but no details are given, as we’re just talking about Django’s database settings. Django got better docs for their database settings than we could ever write, so please refer to Django’s docs.

Get comics

You can get hold of comics in two ways:

  • Download the lastest release from http://github.com/jodal/comics/tags and unpack it.

  • Clone the Git repository. You can do so by running:

    git clone https://github.com/jodal/comics.git
    cd comics/
    

    You’ll then find the current stable/maintenance version in the master branch:

    git checkout master
    

    And the current development version in the develop branch:

    git checkout develop
    

Software requirements

The dependencies can be installed using pip.

You can either install the dependencies globally on your computer:

cd comics/
sudo pip install -r requirements.txt

Or, in an isolated environment using virtualenv:

cd comics/
virtualenv ../comics-virtualenv/
source ../comics-virtualenv/bin/activate
pip install -r requirements.txt

If you make use of a virtualenv for a real deployment, you’ll also need to make sure that the WSGI file and the cronjob activate the virtualenv.

Minimum dependencies

The absolute minimum requirements for getting comics up and running are documented in the file requirements.txt:

Django >= 1.7, < 1.8

# For timezone travel
pytz

# For image handling
Pillow >= 1.7, < 2.8

# For crawling comics and the REST API
lxml >= 3, < 4

# For crawling comics
feedparser >= 4.0, < 6
cssselect >= 0.8, < 0.10

# For static resource compression
django_compressor >= 1.1, < 1.5
cssmin >= 0.1, < 0.3
jsmin >= 2.0, < 2.1

# For user registration with email verification
django-registration >= 0.8, < 0.9

# For user invitation
-e ./django-invitation

# For Twitter Bootstrap compatible Django forms
django-bootstrap-form >= 3.1, < 3.2

# For REST API
django-tastypie >= 0.12, < 0.13
defusedxml >= 0.4, < 0.5

Optional dependencies for real deployments

For a real deployment, you should consider using another database than SQLite, which is the default. In that case, you also need to install Python libraries for connecting to your database of choice, e.g. psycopg2 if you are using PostgreSQL.

Optional dependencies for development

There are also some additional requirements only needed for development, which are listed in the file requirements-dev.txt:

# Automate tasks
invoke

# Mocking in unit tests
mock

# Debugging of database queries, etc.
django-debug-toolbar

# Generation of the model graph used in the docs
django-extensions

Run comics

To get comics to a state useful for testing of new crawlers and personal usage, the following steps are all that is needed.

Create database

A file-based SQLite database will be used, unless you have created a file comics/comics/settings/local.py where you have configured another database, like PostgreSQL.

To create the database and database schema, open a terminal, go to top level directory in your checkout of the comics repo, where you’ll find the file manage.py, and run:

python manage.py migrate --noinput

--noinput stops syncdb from asking you to create a superuser, as this will fail at this point. Instead, when syncdb has finished, create a superuser by running:

python manage.py createsuperuser

Seed database

Then we need to seed the database with information on what comics to crawl. E.g. to add the XKCD comic from comics/comics/comics/xkcd.py, run:

python manage.py comics_addcomics -c xkcd

Optionally, you can add all available active comics to the database:

python manage.py comics_addcomics -c all

Get some comic releases

Next, we need to get hold of some comic releases, so we will crawl the web for them. This will get today’s releases for all added comics:

python manage.py comics_getreleases

To get the release for a specific added comics, you can filter with --comic or -c:

python manage.py comics_getreleases -c xkcd

To get releases for a range of days, you can specify a date range with --from or -f and --to or -t. Both defaults to today, so you can leave the end of the range out:

python manage.py comics_getreleases -f 2011-11-11

Development web server

Finally, to be able to browse the comic releases we have aggregated, start the Django development web server by running:

python manage.py runserver --settings=comics.settings.dev

If you now point your web browser at http://localhost:8000/ you will be able to browse all available comics. If you provided a username and password at the syncdb step, you can log in at http://localhost:8000/admin/ to do simple administration tasks, like removing comics or releases.

More options

All of the manage.py commands got more options available. Add the --help argument to any of the commands to get a full listing of the available options.