« back to Projects
Ohana API Admin
This is 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.
You can see a running version of the application at http://ohana-api-admin-demo.herokuapp.com/.
- Ruby version 2.1.1
- Rails version 3.2.17
- MongoDB with the Mongoid ORM
- Testing Frameworks: RSpec, Factory Girl, Capybara
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.
Git, Ruby 2.1+ (+ Homebrew on 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:
MongoDB installation instructions using MacPorts are available on the Wiki.
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:
If you get a
permission denied message, set the correct permissions:
chmod -R 755 script
Set up the environment variables
config folder, you will find
Rename it to
application.yml and double check that it is in your
.gitignore file (it should be by default).
By default, the app is configured to point to the
To point to your own instance of Ohana API, change the value of
OHANA_API_ENDPOINT in your
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:
And visit it in a web browser at:
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.
Test the app
Run tests locally with this simple command:
For faster tests (and many other rails commands, like rake):
gem install zeus zeus start #in a separate Terminal window or tab zeus rspec spec
To see the actual tests, browse through the spec directory.
The tests will take around 3 to 5 minutes to run. Note that a browser window will open during the integration tests as some of them use the Selenium web driver.
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:
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:
rake secret from the command line to generate a random token.
Use that token to set
OHANA_API_TOKEN to the same value as
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).
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
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.
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.
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.
Copyright (c) 2013 Code for America. See LICENSE for details.