Ohana API Admin

THIS REPO IS NO LONGER MAINTAINED. PLEASE USE OHANA API INSTEAD.

This is an example Rails app that shows how you can build an admin interface for the data that is exposed by the Ohana API. It allows organization members to sign up with their email address, and allows them to update the locations that belong to their organization.

Once a user is signed up, they can be given "master admin" status by setting their "role" field to "admin". This is done by editing the role field directly in the MongoDB interface (via Mongolab if you are deploying to Heroku using this app's default configuration). This will allow the admin to access and update all the data.

Current status

As of July 15, 2014, the admin functionality is now available in the Ohana API Rails app to make it easier to use and maintain. This repo will no longer be updated, but it will remain available as a demo application that you can use to build an external admin interface.

This admin interface most likely no longer works with the latest version of Ohana API. Also, note that the standalone app is very basic and is missing several handy features that have been added to the integrated admin interface.

Demo

You can see a running version of the application at http://ohana-api-admin-demo.herokuapp.com/. Feel free to make changes to get a feel for the admin interface, but please don't delete any locations that you didn't create yourself. Sign in with the following credentials:

Master Admin username: masteradmin@ohanapi.org, Master Admin password: ohanatest
Regular Admin username: ohana@samaritanhouse.com, Regular Admin password: ohanatest

Stack Overview

Ruby version 2.1.1
Rails version 3.2.17
MongoDB with the Mongoid ORM
Testing Frameworks: RSpec, Factory Girl, Capybara

Installation

Please note that the instructions below have only been tested on OS X. If you are running another operating system and run into any issues, feel free to update this README, or open an issue if you are unable to resolve installation issues.

###Prerequisites

Git, Ruby 2.1+ (+ Homebrew on OS X)

OS X: Set up a dev environment on OS X with Homebrew, Git, RVM, Ruby, and Rails

Windows: Try RailsInstaller, along with some of these tutorials if you get stuck.

MongoDB

OS X

On OS X, the easiest way to install MongoDB (or almost any development tool) is with Homebrew:

brew update
brew install mongodb

Follow the Homebrew instructions for configuring MongoDB and starting it automatically every time you restart your computer. Otherwise, you can launch MongoDB manually in a separate Terminal tab or window with this command:

mongod

MongoDB installation instructions using MacPorts are available on the Wiki.

Other

See the Downloads page on mongodb.org for steps to install on other systems: http://www.mongodb.org/downloads

PhantomJS (for running the specs locally)

Installation instructions for Mac, Linux, and Windows.

Clone the app on your local machine.

From the Terminal, navigate to the directory into which you'd like to create a copy of the Ohana API Admin source code. For instance, on OS X cd ~ will place you in your home directory. Next download this repository into your working directory with:

git clone git://github.com/codeforamerica/ohana-api-admin.git
cd ohana-api-admin

Install the dependencies and run the setup scripts:

script/bootstrap

Set up the environment variables

Inside the config folder, you will find a file called application.example.yml. Copy its contents to a new file called application.yml (which is gitignored by default) and make sure to read the instructions carefully.

By default, the app is configured to point to the demo API. To point to your own instance of Ohana API, change the value of OHANA_API_ENDPOINT in your application.yml.

If you made changes to config/application.yml in either the Admin app or the API app, or if you're pointing the Admin app to an API app that already has ADMIN_APP_TOKEN configured, make sure that the value of ADMIN_APP_TOKEN in the API matches OHANA_API_TOKEN in the Admin app.

Run the admin app

Start the app locally:

rails s

And visit it in a web browser at:

localhost:3000

Sign in

The bootstrap script you ran earlier created three users for you that you can sign in with. You can see the username and password for each user in db/seeds.rb. When you sign in with the first two, you'll have access to locations whose email or website domains match the domain name of the user's email address. The locations come from the sample data provided by the Ohana API.

The third user is there to let you try the interface as a master admin, but you can set any of the three users as an admin by setting the "role" field to "admin". To do that, you need direct access to your Mongo database. The easiest way to view and update Mongo data is with a GUI like one of these.

Pagination

To see more than one page of results, add the page parameter to the URL. For example, to go to the second page of results, go to http://localhost:3000/locations?page=2

Test the app

Run tests locally with this simple command:

rspec

For faster tests (optional):

gem install zeus
zeus start #in a separate Terminal window or tab
zeus rspec spec

Deploying to Heroku

First, you need to deploy the Ohana API to Heroku. Then, create a new app on Heroku for the Admin site. Run this command from the root directory of your local copy of this repo:

heroku apps:create your_app_name

Run the Heroku deployment script:

script/setup_heroku -a your_app_name -o your_api_endpoint

your_api_endpoint is the full URL to your API endpoint. For example: http://ohanapi.herokuapp.com/api

This script will take a few minutes to run, and when it's done, you'll see the following messages:

All done pushing code.
You can now visit your site at http://your_app_name.herokuapp.com

Once the script is done, do the following:

Set the ADMIN_EMAIL environment variable in Heroku:

heroku config:set ADMIN_EMAIL=your_email

Run rake secret from the command line to generate a random token.

Use that token to set OHANA_API_TOKEN to the same value as ADMIN_APP_TOKEN in your instance of Ohana API:

heroku config:set OHANA_API_TOKEN=value_of_ADMIN_APP_TOKEN

Visit your site:

heroku open -a your_app_name

You'll then want to sign up for an account to be able to edit the data. To set yourself (or anyone) as a "master admin" who will have access to everything in the database, you can set their "role" field to "admin". The easiest way to do this is by editing the "role" field directly in the MongoDB interface (via the Mongolab add-on if you are deploying to Heroku using this app's default configuration).

Contributing

In the spirit of open source software, everyone is encouraged to help improve this project.

Here are some ways you can contribute:

by using alpha, beta, and prerelease versions
by reporting bugs
by suggesting new features
by suggesting labels for our issues
by writing or editing documentation
by writing specifications
by writing code (no patch is too small: fix typos, add comments, clean up inconsistent whitespace)
by refactoring code
by closing issues
by reviewing patches
financially

Submitting an Issue

We use the GitHub issue tracker to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn't already been submitted. When submitting a bug report, please include a Gist that includes a stack trace and any details that may be necessary to reproduce the bug, including your gem version, Ruby version, and operating system. Ideally, a bug report should include a pull request with failing specs.

Submitting a Pull Request

Fork the repository.
Create a topic branch.
Add specs for your unimplemented feature or bug fix.
Run rspec. If your specs pass, return to step 3. In the spirit of Test-Driven Development, you want to write a failing test first, then implement the feature or bug fix to make the test pass.
Implement your feature or bug fix.
Run rspec. If your specs fail, return to step 5.
Add, commit, and push your changes.
Submit a pull request.

Supported Ruby Version

This library aims to support and is tested against Ruby version 2.1.1.

If something doesn't work on this version, it should be considered a bug.

This library may inadvertently work (or seem to work) on other Ruby implementations, however support will only be provided for the version above.

If you would like this library to support another Ruby version, you may volunteer to be a maintainer. Being a maintainer entails making sure all tests run and pass on that implementation. When something breaks on your implementation, you will be personally responsible for providing patches in a timely fashion. If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped.

codeforamerica / ohana-api-admin