Plenar.io

API for geospatial and time aggregation across multiple open datasets.

This project is funded by the NSF Computer and Information Science and Engineering (CISE) Directorate through a grant to the Urban Center for Computation and Data (UrbanCCD) at the Computation Institute of the University of Chicago and Argonne National Laboratory. It is maintained by UrbanCCD and was prototyped by DataMade.

Development Information

We are currently developing the next version of Plenario. Information regarding the build process and other information can found at https://github.com/UrbanCCD-UChicago/plenario-platform/wiki.

Running locally with Docker

To maximize development portability, we use Docker and Docker Compose. To build and run the Plenario application using docker, do the following:

$ docker-compose build  # will spew out tons of debug logs while building containers
$ docker-compose up     # will also produce tons of verbose logs

Once the server is running, navigate to http://localhost:5000/ . From the homepage, click 'Login' to log in with the username and password from settings.py. Once logged in, go to 'Add a dataset' under the 'Admin' menu to add your own datasets.

Developing with Docker

When you make code changes, you must reload the containers:

$ ^C                    # kill the running containers with Ctrl-C
$ docker-compose down   # ensure it's all down and ready to be rebuilt
$ docker-compose build  # rebuild them to load the changes and install anything new
$ docker-compose up     # restart the containers

Running locally

Get the Plenario source:

git clone git@github.com:UrbanCCD-UChicago/plenario.git

Install support libraries for Python:

cd plenario
pip install -r requirements.txt

If you aren't already running PostgreSQL, we recommend installing version 9.3 or later.

Make sure the host of your database has the PostGIS extension installed.

The following command creates a postgres database, imports the plv8 and postgis extensions, and creates all the necessary tables for plenario to work. The database name corresponds with the DB_NAME setting in your plenario/settings.py file and can be modified. It will be set to plenario_test by default.

./manage.py init

You'll need the ogr2ogr utility - part of the gdal package. We use it to import and export shape datasets.

OSX

brew install gdal --with-postgresql

Ubuntu/Debian

sudo apt-get install gdal-bin

The default settings should work given a typical postgres setup, however should you find that the init method fails to run - the first place to check would be the settings.py file.

You will likely want to change, at minimum, the following settings.py fields:

DATABASE_CONN: edit this field to reflect your PostgreSQL username, server hostname, port, and database name.
DEFAULT_USER: change the username, email and password on the administrator account you will use on Plenario locally.

Before running the server, Redis needs to be running.

To start Redis locally (in the background):

redis-server &

Start up a worker:

./manage.py worker

Finally, run the server:

./manage.py runserver

Tools we are grateful for:

Application Dependencies

Thanks to the maintainers of these open source projects we depend on.

PostgreSQL - database version 9.3 or greater
PostGIS - spatial database for PostgreSQL
Flask - a microframework for Python web applications
SQL Alchemy - Python SQL toolkit and Object Relational Mapper
psycopg2 - PostgreSQL adapter for the Python
GeoAlchemy 2 - provides extensions to SQLAlchemy for working with spatial databases
GDAL - geospatial data mungeing
Redis - key-value cache
Gunicorn - WSGI server
Celery - Task Queue

Production Support

Thanks for the following services that have given us free academic/open source accounts.

Sentry - exception and task monitoring
Code Climate - static analysis
JetBrains - open source license for PyCharm and WebStorm IDEs

Team

Charlie Catlett
Brett Goldstein
Will Engler
Jesus Bracho

Join Our Community

Join us on Gitter for technical help with the Plenario API,

Testing

The plenario/tests folder includes a suite of API tests split across the /points and /shapes directories. To run the tests using with nose, use the command 'nosetests tests' from the /plenario directory

Errors / Bugs

If something is not behaving intuitively, it is a bug, and should be reported. Report it here: https://github.com/UrbanCCD-UChicago/plenario/issues

Note on Patches/Pull Requests

Pull requests make us very happy. If you're interested in contributing, come chat with us on Gitter to discuss what you'd like to do. Then follow common best practices to send us a PR.

UrbanCCD-UChicago / plenario

readme