Drive the Vote helps people arrange free rides to the polls on election day. It consists of:
- A scheduling app, so either voters or volunteers can pre-schedule rides.
- A text-based interface for voters to request rides on-demand--no smartphone required!
- An app for dispatchers to monitor voters and volunteer drivers in real-time.
- A location-aware app for drivers, to notify them when a nearby voter has requested or scheduled a ride.
Here's what the Philadelphia dispatch and driver apps looked like on election morning 2016:
Running the app
Check out the repo
git clone firstname.lastname@example.org:john/drive.vote.git
Preparing your environment
Certain features require you to add a .env file to the root app directory containing these values:
SECRET_KEY_BASE=wwww TWILIO_SID=xxxx TWILIO_TOKEN=yyyy GOOGLE_API_KEY=zzzz
You can generate the value for SECRET_KEY_BASE by running
bundle exec rake secret.
The Twilio values are used for sms interactions with voters and can be obtained from your Twilio account, which you'll also use to create a Twilio number with sms capabilities, and update the ride zone you want to work with to use it. Using Twilio numbers during local dev requires setting up ngrok.
GOOGLE_API_KEY is used for geolocation, and can be created in the Google API console. Enable all geo APIs for the key.
Option 1: run with Docker (recommended)
- Install docker.
docker-compose up. This will start three containers: one for postgres, one for redis and one that runs rails + the webpack dev server.
- On the first run, or after a schema or seed-data change, run
docker-compose exec web bundle exec rails db:create db:schema:load db:seedto setup the database.
- To shut down the DtV containers:
Your current directory will be mounted into the docker instances so changes to the files should go live immediately without restarting the environment. If you need to restart the rails server, just run
docker-compose up again.
To get a bash shell on the current docker instance, run:
docker-compose exec web bash -l
To get a Rails console on the current docker instance, run:
docker-compose exec web bundle exec rails console
Option 2: run directly
- Install postgresql
- Install Redis (to run:
- Install bundler:
gem install bundler
- Install gems:
rake pg:first_runon the first run, and
rake pg:startfor subsequent runs to start the DB
- To set up the db:
rake db:create; rake db:migrate; rake db:seed.
- bundle exec rails webpacker:install (I think?)
bundle exec rake foreman:devto start the server in dev mode. You can check Procfile.dev to see the servers this starts.
For production, instead of
If you don't want to use foreman, you have to run the rails server (Puma) and the webpack server in separate terminals:
bundle exec rails server and
bundle exec ./bin/webpack-dev-server, respectively.
bundle exec rake spec executes all tests in the spec directory. Run locally before committing, the app won't deploy if specs don't pass.
If adding or modifying tests that will make new calls to the Google Maps APIs, you'll need to run with a valid
GOOGLE_API_KEY, both to get your tests to pass, and also to refill the cached test data for use in later runs (including CI). See the discussion in
spec/rails_helpers.rb for instructions on how to run with a live API Key.
Running cron or a scheduled Lambda to promote rides
A process needs to run every minute or so to check scheduled rides, and promote ones that are approaching their pickup time from 'scheduled' to 'waiting assignment,' so that they become available to drivers. That process needs to POST to this url, which will promote imminent rides:
The preferred production setup is to run a dedicated worker instance, but any instance acting as a worker (dedicated or not), needs to have the DTV_IS_WORKER env var set to TRUE.
The call to confirm_scheduled can be made via cron or using the scheduled AWS Lambda available in this repo.
The conversation bot
In practice it turns out scheduled rides seem to be the primary use case. The app also supports on-demand rides via SMS. In that case information is gathered by a basic text bot, information about which can be found in converation_bot.md
Using the app locally
Go to http://localhost:3000 and log in as the generic admin with email
email@example.com and password
1234abcd. Since this account has admin privileges, logging in with it takes you directly to the admin site. If it has only driver privileges, it would take you to the driver app, and if only dispatcher privileges, to the dispatch page for the ride zone attached to your account. If for some reason your account has no privileges at all, you'll end up at the homepage, but that shouldn't happen. Note the accounts in seeds.rb don't exist in production, so don't get cute.
- http://localhost:3000/admin -- Admin console Default page shows all dev Ride Zones.
- http://localhost:3000/dispatch/[slug] -- Dispatch app. The slug should correspond to the ride zone attached to the logged in user. Linked to for each ride zone from the admin page.
- http://localhost:3000/driving -- Driver app. It'll be connected to the Ride Zone the account is driving for. If this URL redirects to /, it means the account logging in isn't a driver.
Spoofing location in the browser
brew update && brew install mailhog brew services start mailhog
Once started you can view the Mailhog client at http://localhost:8025/
- Fork it
- Create your feature branch:
git checkout -b my-new-feature
- Follow rails core team coding conventions
- Provide test coverage/specs for your changes, and make sure all specs pass:
bundle exec rake
- Commit your changes:
git commit -am 'Add some feature'
- Push upstream:
git push origin my-new-feature
- Create new Pull Request
- Request a code review
- After review and approval, merge your own work to master
This software is released under the MIT License. See the LICENSE.md file for more information.