OpenBlock v1.1.0 documentation

Creating a Custom Site Based on OpenBlock

If you want to do something much different than obdemo, you're better off starting from scratch with a custom Django project. We provide a script that will get you started with a skeleton app that you can edit.

(You can skip this if you are cloning an OpenBlock AMI.)

Setting up the app

Basic Setup

First, follow all the instructions in the Preparing Your System document and Installing the Openblock Software

If you followed the Installing the Openblock Software instructions properly, you've already got a virtualenv ready. Go into it and activate it, if you haven't yet:

$ cd path/to/your/virtualenv
$ source bin/activate

Create Custom App Package

Now do the following to create a new OpenBlock project. Note: Your project name should be suitable for use as a python module name; i.e. no spaces etc. Here we assume the project name is myblock:

$ cd $VIRTUAL_ENV/src
$ paster create -t openblock myblock

After answering a few questions, this will create a bare-bones Django project in the folder you specified. Next, install the project into your environment:

$ cd myblock
$ python develop

What You Get

The created package is a minimal Django project that includes:

  • you can edit.
  • that wraps ebpub's URLs; you can override individual views here, add custom views and other Django apps, etc.
  •, a tiny wrapper around / that saves you the trouble of activating your virtualenv or exporting DJANGO_SETTINGS_MODULE.
  • templates/homepage.html, an example of overriding one of ebpub's templates, edit as you like.
  • wsgi/<projectname>.wsgi, suitable for deploying your project under Apache and mod_wsgi. It takes care of finding the containing virtualenv and the DJANGO_SETTINGS_MODULE automatically.

Adjust Django Settings

Your django settings are located in within your project. You should review these and make adjustments based on your setup:

$ favorite_editor myblock/

Read more about important settings you can/should customize.

If you plan to use a remote database or have other changes to database connection information, make sure you change them in your See Database Access Settings and be sure everything works before you proceed.

Create and Initialize the Database

Now, as usual with Django projects, you'll need to create and initialize your database. If you haven't changed the default database settings, and if you've followed the PostGIS template setup instructions, then the database creation command would simply be:

$ sudo -u postgres createdb -U openblock --template template_postgis openblock_myblock

If you have a different postgresql setup, for example you're using a different user than openblock, just change the -U option accordingly.

Now initialize your database tables:

$ export DJANGO_SETTINGS_MODULE=myblock.settings
$ syncdb --migrate

(The --migrate option is important; it loads some initial data that openblock depends on including stored procedures, and some default Schemas that you can try out, modify, and delete as needed.)

This will also prompt you to create an administrative user, which is a good idea.

Starting the Test Server

Run django's test server using your project's settings and visit in your Web browser to see the site in action (with no data):

$ export DJANGO_SETTINGS_MODULE=myblock.settings
$ runserver
Development server is running at

You can now visit in your Web browser to see the site in action (with no data). You can log in to view the administrative site at .

Loading Data: Things You Will Need

To get anything useful out of your site, at minimum you will need the following:

  1. Geographic data for your area. See Loading Geographic Data.
  2. Sources of news data to feed in.
    1. Configure the system with schemas for them. See Creating a Custom NewsItem Schema and ebpub docs for NewsItems and Schemas.
    2. Write scraper scripts to retrieve news from your news sources and load it into the database. See the Data Scraper Tutorial, ebdata and .
  3. Optionally, customize the look and feel of the site. See the ebpub docs for Site views/templates.

Gathering all this data and feeding it into the database can be a bit of work at this point. The obdemo/bin/ script in the openblock source code does all this for the demo site with Boston data, by calling other scripts; together, they should serve as a decent example of how to do things in detail.

If you want to load the demo data into your project, you can use the steps listed in Loading Demo Data. Note: use the settings module for your project instead of obdemo.settings.

Additional Resources

For more documentation (in progress), see also: