Implementation Notes for Maintainers

To The Trails: Implementation Notes

Summary

This document describes infrastructure and deployment details.

Components

To The Trails consists of three main parts:

1. A front-end user HTML5/JavaScript application (the "front-end"). * In production this is reachable at http://tothetrails.com.
2. A REST-based JSON API for the trails data, and a park user trail data uploader and editor, both part of the same Ruby on Rails application (the "back-end"). * In production this is reachable at http://tothetrails.com/admin.
3. A Postgres database with PostGIS spatial data extensions to store the application data. (the "DB")

Additionally, trail photos are stored in an Amazon S3 bucket.

Front-end

The front-end HTML/JavaScript application presents the map and trail info.

There are several open-source JS libraries included and used. The To-The-Trails-specific code is almost entirely in /js/trailhead.js.

There are custom versions of two JavaScript libraries:

1. Leaflet 0.6.4 is customized to fix the bug reported at https://github.com/Leaflet/Leaflet.markercluster/issues/254. The fixed version is located in a forked Github repository at http://github.com/danavery/Leaflet.
2. Modernizr has a custom-built download that include media-queries (Modernizr.mq).

The application will request trail data from the host specified in the API_HOST variable. It's currently set up to use 'localhost' by default, but can be changed to point to an instance of trailsyserver elsewhere for development.

The application code is available online at http://github.com/danavery/trailsy (although this will change soon to http://github.com/codeforamerica/trailsy).

The front-end git repository is included in the back-end repository as a git submodule located in the back-end's "public" directory, where Rails applications traditionally house their static assets. When using Heroku, this means that it is automatically included in the back-end's public directory when the back-end app is deployed.

• HTTP requests to http://tothetrails.com are set up to return the front-end index.html from the /public directory, starting the user application.
• HTTP requests to http://tothetrails.com/admin go to the back-end admin UI.

The CSS for the front-end is created using LESS, a CSS language extension, in the styles/less directory and processed on the command line by a LESS compiler to produce CSS in the styles/css directory that the application uses directly. The CSS may be edited directly if necessary, although any changes made directly to the CSS files will not survive if the LESS files are compiled into the /styles/css directory again. Only the "main.less" file needs to be compiled, as it @includes all of the other required LESS files.

Back-end

The back-end Rails application performs two roles: it works as a RESTful JSON endpoint for trail data requests, and as the trail data uploader and editor.

REST API

The front-end calls the REST API for trail data, using the following URLs. All the following requests return GeoJSON except for trails.csv. In general, if /data.json returns all of the 'data' records, /data/3.json will return only the record with an ID of 3, if one exists.

• /trails.json returns all trail metadata in GeoJSON
  • /trails.json?source_id=3 returns the JSON for trail records that have a source organization with an ID of 3, if one exists
  • Special note: while trail metadata records don't technically contain any geodata, JSON produced by this endpoint will include a dummy [0,0] Point geometry, which can be ignored. It's there because the RGeo GeoJSON generator doesn't work without geodata.
• /trails.csv returns all trail metadata in CSV format, for easier editing and re-uploading. The ?source_id=[x] query parameter works in the same way as in /trails.json.
• /trailheads.json returns all trailhead data
  • /trailheads.json?loc=*lat*,*lng* returns the trailhead data in order of distance from the location lat latitude and lng longitude, calculated in simple spherical distance. A "distance" field is also included in the JSON trailhead records if loc is specified, which is in meters.
• /trailsegments.json returns all trailsegment data (this will be large)
• /organizations.json returns all organization data

Trail Data Uploader and Editor

This back-end application allows users to upload new data and modify data their organization has uploaded. It can be reached at the relative URL /admin.

Note that the code for the RESTful API and the Editor UI overlap in the Rails app. The Editor actually uses the same REST API, except its endpoints are HTML instead of JSON. For example, /trails.json returns all trail data, and /trails (and its synonym /trails.html) returns the list of trails in HTML, for logged in users.

As is typical, there are many Ruby modules included in the back-end application. Two of the most important ones in the app are Devise, which handles user authentication and Paperclip, which handles the photo attachment uploads.

The GDAL/OGR command-line tool ogr2ogr is used to convert shapefiles to GeoJSON and change projections to lat/long coordinates. It's installed on Heroku using a custom buildpack.

Database

The trail, trailhead, segment, user, and organization data is stored in an instance of Postgres with PostGIS spatial extensions. Another database could be used--see the RGeo for usable databases.

Current Deployment

• The app is currently deployed and hosted on Heroku, a cloud-hosting service that works with several web frameworks and platforms.

• Deployment happens when a Git repository is "pushed" to a Git repository on Heroku's servers. The Heroku-based repository is created when an application is created in Heroku via the Heroku web site or via the Heroku Toolkit, a command-line interfaces. When a repository is pushed, the "master" branch of the Heroku repository is searched for a viable web application, and when one is found, it's intialized and made available at http://[appname].herokuapp.com.

• The Heroku application is called "trailsy" on the Heroku site. As of this writing, the app is "owned" by the Code for America Heroku account.

• The domain tothetrails.com has DNS records which point it to trailsy.herokuapp.com.

• The DB is also hosted by Heroku as a Heroku app "add-on". The command heroku pg:psql DATABASE_URL will invoke the 'psql' postgres command-line utility for direct database access.