Large Lots

The City of Cleveland Land Bank sells vacant lots to homeowners for a side yard expansion.

Large Lots enables you to find if there is a vacant lot adjacent to your property that is eligible to be purchased for a side yard expansion and to complete the Land Bank's application.

A production version is available at clevelandlots.org.

This is based on a similar project in Chicago, called Large Lots made by Data Made.

Errors / Bugs

If something is not behaving as you expected, it could be a bug, and should be reported in our issue tracker at https://github.com/opencleveland/large-lots/issues

Developer Instructions

Configuring and running locally

Clone the repo and install the requirements:

We recommend creating a virtualenv environment although not required.

git clone https://github.com/opencleveland/large-lots.git
cd large-lots
pip install -r requirements.txt

Create local_settings.py and setup a few environmental variables (Ask Will in Slack for these keys.).

DJANGO_SECRET_KEY Django’s Secret Key used by the project. Can be any relatively hard to guess string.

AWS_ACCESS_KEY AWS key used by the file storage mechanism to store files in S3.

AWS_SECRET_KEY The secret that goes with the key above.

LOTS_EMAIL_HOST, LOTS_EMAIL_PORT, LOTS_EMAIL_USE_TLS, LOTS_EMAIL_HOST_USER, LOTS_EMAIL_HOST_PASSWORD These are used to configure the email settings for Django. See Django docs for more info.

SENTRY_DSN This is a connection string for Sentry

Run the app:

python manage.py runserver

navigate to http://localhost:8000/

Running in a production environment

We used nginx and uWSGI to run Cleveland Lots. The tutorial we used is here: http://uwsgi.readthedocs.org/en/latest/tutorials/Django_and_nginx.html, but the tutorial is a little out-of-date and doesn't include every step we needed to get a production-grade web server running for our app. Below is a details walkthrough of the steps needed to get this code running on a fresh Ubuntu install (we used the Ubuntu Server 14.04 LTS image provided by Amazon Web Services).

1. install the basics: nginx, git, PostgreSQL, Python utilities, Django, uWSGI, and assorted Python/Django modules.

• sudo apt-get install nginx
  • The nginx daemon starts automatically
• sudo apt-get install git
  • easiest way to get the Lots code off GitHub
• sudo apt-get install postgresql postgresql-contrib
  • install the SQL database.
• sudo apt-get install libpq-dev
  • needed to connect psycopg2 to PostgreSQL
• sudo apt-get install python-dev
  • need this to install pip
• sudo apt-get install python-pip
  • need this to install the latest version of uwsgi. Also the best way to install the latest version of Django.
• sudo pip install Django
  • the web app framework we're using.
• sudo pip install uwsgi
  • a web server that can talk to Django and nginx.
• sudo pip install raven
  • Django module used in our app; uWSGI won't start without it.
• sudo pip install psycopg2
  • Django module used in our app which connects Django to PostgreSQL; uWSGI won't start without it.
• sudo pip install python-dateutil
  • Django module used in our app; uWSGI won't start without it.

2. Create a user without root/sudo permissions

• The uWSG docs say uWSGI should not be run as root as a security measure: http://uwsgi-docs.readthedocs.org/en/latest/ThingsToKnow.html. Ubuntu on AWS has a default user named ubuntu so we'll run uWSGI under that user.

3. Pull the Lots code from GitHub onto your server.

• We hosted the code in /usr/share/large-lots/. You could put it somewhere else, but you'd have to change the nginx config file to match its new location.
• cd /usr/share/ - cd to the directory where you'll put large-lots
• sudo git clone https://github.com/opencleveland/large-lots.git
• In the /large-lots/ folder, copy local_settings_template.txt to create a file called local_settings.py. There are some sensitive settings in there (access keys) that we can't post on GitHub. See "Configuring and running locally" for a discussion of these settings.

4. Configure PostgreSQL

• Details to be added later. We used the standard Postgres tutorial: http://www.postgresql.org/docs/9.4/static/tutorial.html
• Whichever user runs uSWGI will need a role in PSQL and permissions to write to the database where the lots data will be stored.

5. Configure nginx

• cd to the directory where you put the Lots code. Above we used /usr/share/large-lots/, so cd /usr/share/large-lots/
• in /usr/share/large-lots/ create large_lots_nginx.conf. Set it up per tutorial at http://uwsgi.readthedocs.org/en/latest/tutorials/Django_and_nginx.html. We have also included our default large_lots_nginx.conf in the GitHub repo as an example; if you follow this tutorial exactly that file will work with minimal changes.
  • At the very least, you wil need to change the "Server name" setting to the domain name your server is running on. nginx will only use this configuration file if the domain in the request matches the Server Name here. For example: if this server name is set to www.example.com, but someone accesses the server using another domain name or an IP address, nginx will skip this configuration (and therefore skip the Lots app) and instead will give them the default nginx page.
• Some important details:
  • upstream block ("django"), then server block.
  • Has separate settings for static files and dynamic applications.
  • uwsgi_pass digano; - this redirects requests that don't match the static file URLs tot the dynamic application mentioned in "upstream django"
  • include /uwsgi_params - this file is required for uwsgi. We didn't make any changes to it, just downloaded it and used it out of the box.
• Point nginx to the new .conf file we created
  • put a symlink in /etc/nginx/sites-enabled/ pointing to /usr/share/large-lots/large_lots_nginx.conf: sudo ln -s /usr/share/large-lots/large_lots_nginx.conf /etc/nginx/sites-enabled/
  • Be sure to use sudo, not su -. For some reason if you su - then run the command it doesn't work.

6. Run uWSGI:

• cd to the large-lots folder (in our example, cd /usr/share/large-lots/, then start uwsgi like this: uwsgi --module lots.wsgi --socket :8001
  • lots.wsgi in that command refers to wsgi.py in the lots folder. So in this case, it refers to /large-lots/lots/wsgi.py
• Note that uwsgi uses FastCGI instead of HTTP by default. nginx uses FastCGI to talk to uwsgi so the default is fine.
• There are 2 ways to run uwsgi so it continues running after you log out.
  • The easiest is to make it a background process and use nohup to allow the command to keep running after you close your terminal: cd /usr/share/large-lots/, then start uwsgi like this: nohup uwsgi --module lots.wsgi --socket :8001 &. This is the method we are using in production today - log in as the ubuntu user, cd to the directory, and run uwsgi with nohup and &. Note that if you omit either nohup or &, the uswgi process will end when you log out of the server and the app will no longer be accessible.
  • Or you could write a bash script that starts the web server and run that script periodically with crontab. This has the added benefit of restarting uwsgi regularly if the server goes down. But crontab adds its own levels of complexity that may not be worth the effort.

7. restart nginx: sudo service nginx restart

• Once uWSGI is running and nginx has restarted, nginx should load your configuration and be able to serve the app.

Data

Our map was built using data from the City of Cleveland Land Bank. The data comes from NEO CANDO's NST site: http://neocando.case.edu/nst/

Dependencies

We used the following open source tools:

• QGIS - graphic information system (GIS) desktop application
• PostGIS - geospatial database
• Bootstrap - Responsive HTML, CSS and Javascript framework
• Leaflet - javascript library interactive maps
• jQuery Address - javascript library creating RESTful URLs

Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Commit, do not mess with rakefile, version, or history.
• Send me a pull request. Bonus points for topic branches.

Open Cleveland Contributors

• Ariel Koiman
• Carter Wang
• Paul Koepke
• Eamon Johnson
• Raul Montejo

Data Made Contributors (to the Chicago project)

• Demond Drummer - idea, content, outreach
• Derek Eder - developer, content
• Eric van Zanten - developer, GIS data merging
• Forest Gregg - process design, content
• Aya O'Connor - logo
• Juan-Pablo Velez - content

Copyright

Copyright (c) 2015 DataMade and LISC Chicago. Released under the MIT License.