Documentation is hard. People forget to write it, and they are asked the same question over and over again. When they finally do write it down, people can't find it or it gets out of date before it can be useful.
The goal of Orientation was to make a single point of entry for any internal question someone might have about our organization:
How can I help with bugs, maintenance and other issues?
Do we give student discounts?
How can I help on support?
Here's how Orientation works.
I originally tried to make Orientation as easy to onboard to as possible for people in our team. While a huge majority of us had GitHub accounts, not everyone did. Nor was it realistic to expect non-developers to setup a GitHub account just to use a documentation tool. We did โ however have โ company Google Apps accounts, so this is what I used. I want to enable custom OAuth providers soon.
- Ruby 2.2.0
- PostgreSQL 9.1 (with fuzzystrmatch and pg_trgm extensions)
- Python 2.7 (for Pygments)
- Node.js (for Bower)
- Bower
Both Node and Python are available on Heroku if you decide to deploy there, which means there should not be any issues when deploying or running Orientation there.
- Mandrill account for transactional emails
- Google API project with access to the "Contacts API" and "Google+ API" for OAuth authentication of users.
If you want to quickly test out your own Orientation installation, you can use the Heroku button:
See Docker installation instructions.
Almost one step: rake orientation:install
Make sure to check the installation task if anything strange happens during installation.
Once you're done, pay close attention to the .env
file that will appear at the
root. It's copied from .env.example
and contains all the
environment variables needed to configure Orientation.
OAuth is disabled in development and you will be signed in as whichever
user is returned from User.first
.
See .env.example file. Note that if you host your Orientation
on Heroku you'll need to set those environment variables manually. I recommend
dotenv-heroku to do this easily
using you local (git-ignored) .env
file as a canonical source.
Multiple buildpack support used to be unofficial and relied on a custom buildpack created by David Dollar. This is no longer the case since Heroku has rolled out official support for multiple buildpacks.
Therefore, if you decide to deploy Orientation on Heroku manually (without using the Heroku button, which would take care of this for you) you will need to add two buildpacks since the app relies on NodeJS for Bower package installation.
Note that for some reason you need to be the owner of the app on Heroku in order to be able to do this:
heroku buildpacks:add --index 1 https://github.com/heroku/heroku-buildpack-ruby -a yourappname
heroku buildpacks:add --index 2 https://github.com/heroku/heroku-buildpack-nodejs -a yourappname
When you run the following command, your output should be similar:
$ heroku buildpacks -a yourappname
=== yourappname Buildpack URLs
1. https://github.com/heroku/heroku-buildpack-nodejs
2. https://github.com/heroku/heroku-buildpack-ruby
- Go to the Google Developers Console and create a new project
- Once you've created the project, go to
APIs
and add theContacts API
and theGoogle+ API
(you won't need a Google+ account to sign in, this is just an annoying Google quirk). - Then go to
Credentials
andCreate a new Client ID
. You'll need the app's production URL to complete this step so if you're using the Heroku button, do that first. You can use your production URL for theJavaScript Origins
setting, but make sure to usehttp://yourdomain.com/auth/google_oauth2/callback
for in theRedirect URIs
setting. It's a good idea to also add the same URL but with the HTTPS protocol to ensure that if you ever force SSL, Google will still accept the redirect. - Don't forget to go update the
GOOGLE_KEY
andGOOGLE_SECRET
environment variables with the credentials Google gave you when you created your Client ID, otherwise the redirection process will fail.
If you enable transactional email notifications with Mandrill, you'll need to create Mandrill templates with names that match the ones listed in our Mandrill documentation.
Orientation uses a Sass-based CSS architecture called MVCSS. It was extracted from Envy and Code School work by both front-end teams.
It's not nearly as complex as a framework. The basic gist is that we try to keep things as modular and dynamic as possible. Magic values are not welcome. If you contribute styling changes to Orientation, please take the time to get the lay of the land.
In development we cheat around OAuth by simply using User.first
as the
current user because it's easy and we're lazy. Testing OAuth in dev is
hard.
If you're curious what the OmniAuth hash from Google OAuth 2 looks like check this out.
Orientation is MIT licensed. See LICENSE for details.