Home

Welcome to the wiki! It outlines the features of Prepared.ly with the goal of making it easy to customize and deploy.

Table of Contents

• Overview
• Setting up your database
• Environment Variables
• Users and accounts
• The map
• The tasks
• Mailers, messages and alerts

Overview

• You can find basic Rails and database configuration info in the ReadMe. This page digs a bit deeper into setup and configuration. In addition to a local development version, we suggest setting up a staging app on Heroku, Open Shift or your hosting provider so you can push changes and test features there before touching your production code and database.
• Prepared.ly helps people get an estimated risk level and provides prevention suggestions for managing the danger of wildfires. Currently, users must sign up/in to gain full access. Once authenticated, the dashboard partial renders the main user layout. See prepared.ly/app/views/layouts.
• The dashboard partial pulls in other partials for each section - the map, user account, contact. See below for details on each. The sidetab navigation uses Bootstrap data tabs to toggle the display, and a bit of Javascript to get the url to change (and establish a permalink to each section). Take a look at the "data-toggle="tab"" elements for the former, and in application.js for the latter. The code has detailed comments.

Setting up your database:

• Remember to set up your local, staging and production and other environments.
• pgAdmin3 was very helpful in testing and managing the databases, especially the local ones (you can also connect to your hosted databases using this tool).
• Please review the ReadMe for setup details, or quick instructions below:
  • Setting up a local environment if using OS X and homebrew: brew install postgis # postgres is a dependency and will get installed, this takes a while
  • Create a database with: initdb /usr/local/var/postgres and start it with pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start
  • Heroku quick instructions
    • Install the postgres add-on
    • Create a database that supports postgis; Ronin or higher according to the documentation, Crane or lower seem ok too, use at your own risk though.
    • Manually promote the database you just created so you can use the postgis protocol. Promoting a database sets the DATABASE_URL config var and uses that for your app. Do this manually so we can use the postgis protocol. Run the following command using values for your database from https://postgres.heroku.com/databases

heroku config:add DATABASE_URL=postgis://user:password@Host:Port/Database then do heroku config and you should see something like: DATABASE_URL => postgis://u12345:p567890@ec2-111-11-111-1.compute-1.amazonaws.com:5432/dbabcdefg

Environment Variables - lots of 'em!

• Rather than putting secret authentication/account credentials right in the code, use env vars.
• You'll want to add them to your local bash profile, usually can access (on OS X) by going to your user's directory and typing vi .bash_pofile. You'll then want to type source .bash_profile to refresh it. The quickest way to make an env var available system wide is to enter it as export TWITTER_ID='abcDEFGhijk'. Heroku instructions here, note the slightly different syntax.
• Notes on using third party authentication providers with omniauth/oauth:
  • For authenticating with Google, tell the service about your app and get your key from here. You'll also want to do the same for Yahoo!, Twitter, Twilio, Facebook and any other third party services you're using.
  • For Yahoo!, note that your keys change every time you change the permissions in the Yahoo! dashboard. Also, you need to add some Yahoo! services beyond defaults for user login to work - add Social Directory to get Profile info, including email.
  • Here's a list of other environment variables used in the app's code. There are likely others pre-filled or that you'll need to set up depending on your hosting environment, for example Heroku or a host will add one for add-ons like Sendgrid. AUSTIN_EMAIL, LAKEWAY_EMAIL, TX_EMAIL, WILCO_EMAIL (emails from the Contact An Expert form depending on user selection), FACEBOOK_ID, FACEBOOK_SECRET (login via Facebook); GOOGLE_ID, GOOGLE_SECRET (login via Google, use of Maps autocomplete API); KISS_ID (if using KissMetrics); TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN (authenticate and send SMS); TWITTER_ID, TWITTER_SECRET (login via Twitter); TXWRAP_PASS, TXWRAP_USER (credentials to use the TxWRAP Esri server); WUNDERGROUND_API_KEY (Weather Underground); YAHOO_ID,YAHOO_SECRET (authenticate with Yahoo); NOTIFIER_SENDER_EMAIL, NOTIFIER_RECIPIENT_EMAIL (for exception/error notifications).

Users and accounts

• Rails Admin
  • Add users as administrators in the Rails console or by changing the Admin column in the Users table to TRUE, then go to http://appurl/admin heroku run rails console # fire up the console in whatever environment you're in, locally just rails c user = User.where('email' => 'you@youremail.com) user.admin = true`
• The app uses Devise for authentication, and Omniauth on top of that for third party authentication.
  • Since the Twitter omniauth hash doesn't return a user's email, the user is redirected on first sign in and must change in to continue. See comments in the following files: app/controllers/users/omniauth_callbacks_controller.rb, app/controllers/users_controller.rb, app/models/user.rb
• Additional resources for getting Omniauth set up can be found
  • https://github.com/plataformatec/devise/wiki/OmniAuth:-Overview
  • http://railscasts.com/episodes/304-omniauth-identity
  • http://net.tutsplus.com/tutorials/ruby/how-to-use-omniauth-to-authenticate-your-users/
  • http://www.communityguides.eu/articles/11

The map

• Both the map view and the necessary Javascript for it can be found in app/views/map/_mapinfo partial.html.erb
• Google Maps autocomplete API to standardize address inputs. It also uses the Google geocoder, which is the default for the Geocoder gem. The setupMapInfo() method in map_controller.rb provides some examples of pulling information out of the Yahoo! geocoder's response as well.
• The map uses Leaflet.js and tiles from Stamen.
• For the Risk level, we get information via the ESRI API, see app/controllers/map_controller.rb Class TFS for how it grabs the info and returns an integer that is matched to a risk title ("high", "very low", etc.) in the view. This is set up by agreement and permission of the Texas Forest Service, using the information that serves the TxWRAP map. The code should be a pretty good guide for accessing data from an ESRI services generally. Check with your city's GIS department to see if their servers support this.
• Countywide burn ban. In map_controller.rb#setupMapInfo, you'll see use of the Google geocoder to both get lat/lng coordinates and the county of an address. Later, it checks this @county against other counties lists to return a yes/no value (such as the burn bans). The Google geocoder doesn't always return a county, unlike the Yahoo one. The code for both is in map_controller.rb#setupMapInfo, just make sure the geocoder is calling the correct service in vendor/plugins/geocoder/lib/geocoder.rb
• National Weather Service Warning is returned from a parsed XML document. The Red flag warning parses a plain text document (we couldn't find a machine-readable one, unfortunately). The weather comes from the Weather Underground API. These are all documented in the map controller.

The tasks

• List taken from various sources and most can be found in the seeds.rb. You can add these manually in the console or in Rails Admin. As of this writing, a validation needs to be added so the body field, which is used in SMS reminders, is under 160 characters OR separate it into multiple 160-character-limited SMSs (calling the method with remaining characters then appending 1/2, 2/2 etc.). This is due to a carrier restriction on SMS message length.
• For scheduling tasks, the front end uses the Jquery datetimepicker (see gemfile and application.js) to let the user select a time on the hour (the finest frequency the Heroku Scheduler add-on will run). When a user schedules a prevention task, a new Message is created and its scheduled_time is set to the user's input; reminder_type is set to text or email (see messages_controller.rb#remind).
  • On Heroku, we used the Scheduler add-on. The basic tier allows a maximum of one scheduled job per hour, so the Message's scheduled time is the user's input minus one minute. Then the task runs on the hour. The task itself can be found in lib/tasks/scheduler.rake

Mailers, messages and alerts

• This thread was particularly helpful in sending email on user signup.
• Emails are sent via the Sendgrid Heroku add-on. The free version allows 200 emails per day. For periods of high expected traffic, such as a press release, you might wish to upgrade temporarily.
• Sending an SMS to all users
  • To send an SMS to all users (with phone number and SMS opted in), go into Rails admin and create a new Message. http://www.yourapp.com/admin/message/new
  • The only thing you need to enter is the body.
  • If using Twilio, note that SMS messages are limited to 160 characters, so you might wish to send two messages one immediately after another and include the message number in each, as shown above, or write code to automate this.
  • If including a url in the body for smartphone users to click on, it is a good idea to include the http:// prefix to make sure phones to interpret it as a url.
  • Optionally to track/organize your SMSs, you can enter a Reminder Type as 'alert' or 'notification' or whatever you want, just don't use 'text' since the user-scheduled reminders use that.
  • If sending to all opted-in users, and sending immediately, leave the scheduled time and user fields empty.
  • NOTE: When you hit Save without including a scheduled time, it will send instantly! No turning back! A great reason to have a staging environment.
• Scheduled user reminders

Misc.

• We also use AddThis for some sharing features, and Pingdom to monitor uptime.