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.
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.
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.
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
Get the Plenario source:
git clone [email protected]: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
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.
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
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
- Charlie Catlett
- Brett Goldstein
- Will Engler
- Jesus Bracho
Join us on Gitter for technical help with the Plenario API,
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
If something is not behaving intuitively, it is a bug, and should be reported. Report it here: https://github.com/UrbanCCD-UChicago/plenario/issues
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.
Copyright (c) 2014 University of Chicago and DataMade. Released under the MIT License.