Getting started and installation

The following instructions should help you get started with BusTracker. If you get stuck or run into errors, check the troubleshooting section at the bottom of this page. If that doesn’t help, ask for help on the mailing list.

Requirements

To build BusTracker you’ll need a few different packages. First, since the code is hosted on GitHub, you’ll obviously need Git. You’ll also need Python (most of the development has been done with 2.5, but other versions may work as well). Odds are you already have all this installed. BusTracker is built using Django, though there’s no need to install it separately.

You’ll also need PostgreSQL with PostGIS. You’ll want to create a new database for use with BusTracker using PostgreSQL’s createdb command (you can name this database whatever you like, just make a note of this as you’ll need it below and when editing the settings.py file). After creating the database, you’ll need to load the PostGIS extensions with the following commands (this assumes you named your database bustracker):

$ createlang plpgsql bustracker
$ psql -d bustracker-f lwpostgis.sql
$ psql -d bustracker -f spatial_ref_sys.sql

If you’re not sure where lwpostgis.sql and spatial_ref_sys_sql are located, try running locate lwpostgis.sql. If you really can’t find them, you probably don’t have PostGIS installed.

Getting started with the code

When doing Python development, it’s nice to use virtualenv so you don’t have to install everything as a system-wide package. If you don’t have virtualenv, you can check out the source or simply easy_install it:

$ easy_install virtualenv

Next create a new virtual environment and activate it:

$ virtualenv BusTracker
$ cd BusTracker
$ . bin/activate

Now make a directory to store the source and check out the code:

$ mkdir src
$ cd src
$ git clone git://github.com/novalis/BusTracker.git

Copy the example configuration file

$ cd BusTracker
$ cp settings.py.EXAMPLE settings.py

and edit it with your favorite editor. Set the DATABASE_NAME, DATABASE_USER, and DATABASE_PASSWORD accordingly for your system (i.e., use the name of the database you created earlier and enter a PostgreSQL user that has access to that database). You should also set POSTGIS_SQL_PATH to point to where PostGIS lives on your system and update TEMPLATE_DIRS with the full path to BusTracker/tracker/templates.

If you are doing development or testing locally, you should set MEDIA_ROOT = ‘/path/to/BusTracker/tracker/static/’ so that the static files (e.g., JavaScript) will be served correctly. (For production servers, MEDIA_ROOT should not be set and your webserver should be configured to serve the files in BusTracker/tracker/static under YOUR_DOMAIN.COM/tracker/static.)

You should now be able to actually run the server:

$ python manage.py syncdb
$ python manage.py runserver

Try browsing to http://127.0.0.1:8000.

Loading data

Loading GTFS data

To actually make much use of the software, you’ll need to load in some data. You can download bus schedule data as GTFS files for some NYC buses here ¹ (if you have the data in STIF, BusTracker includes a utility for converting it into GTFS, see the README). After you’ve downloaded the GTFS, you can import it by borough with the following command (note this will take a decent amount of time to complete; grab a soda and be patient):

$ ./manage.py gtfs_import mta_data/bus-[borough].zip

Where [borough] is one of Bx, B, M, Q, or S.

Loading observation data

To test the algorithm it helps to have actual bus location data. The following command will import some observation data from several trips on the M6 bus in Manhattan:

$ python manage.py import_old_observations tracker/fixtures/old-observations

You can verify that this data was imported properly by experimenting with the demo interface. Try loading http://127.0.0.1:8000/tracker/map and playing with the various options to visualize the bus routes and data points.

Troubleshooting

GEOS import error

If you get the following or a similar error:

ImportError: Could not find the GEOS library (tried "geos_c", "GEOS"). Try setting GEOS_LIBRARY_PATH in your settings.

It means that you need to tell Python where your GEOS install is. Edit settings.py and add a line like the following:

GEOS_LIBRARY_PATH = '/opt/local/lib/libgeos_c.1.dylib'

Make sure that the path is actually to libgeos. If you’re not sure where this is, try runing locate libgeos. If you still can’t find it, you may need to install it using your OS’s package manager (if you’re using Mac OS X, you can use MacPorts and install it via sudo port install geos).

python setup.py develop complains about pysqlite2

The transitfeed package can be a pain to install as a dependency. Try downloading the source and running python setup.py install for it on its own (make sure your virtualenv is activated). After doing that, try running python setup.py develop for BusTracker again.

¹ Note that this data is currently out of date. It will hopefully be updated soon, and a group of us is working to improve relations between the MTA and the developer community and open up the data so that developers can download up-to-date GTFS files directly from the MTA. You can learn more about this effort here.