Repository files navigation

Documentation is hard. People forget to write it, and they are asked thesame 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 is to make a single point of entry for anyinternal question someone may have about the organization:

How can I help with bugs, maintenance and other issues?

Do we give student discounts?

How can I help with support?

Check out thePurpose of Orientation, and Current and Future Features.

Try the DemoYou'll need a Google Apps account to sign in.*

I originally tried to make Orientation as easy to onboard to as possible forpeople in our team. While a huge majority of us had GitHub accounts, not everyonedid. Nor was it realistic to expect non-developers to setup a GitHub accountjust to use a documentation tool. We did — however have — company Google Appsaccounts, so this is what I used. I want to enable custom OAuth providers soon.

Some of these system dependencies can be installed on a macOS developmentmachine with thebin/system command usingHomebrew.

• Ruby 2.4 to 2.6
• PostgreSQL 9.3+ (with JSON support, and fuzzystrmatch & pg_trgm extensions)
• Node.js 8.12.0 (for yarn)
• yarn

Node is available on Heroku if you decide to deploy there, which meansthere should not be any issues when deploying or running Orientationthere.

• 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 usethe Heroku button:

SeeDocker installation instructions.

1. Rungit clone git@github.com:orientation/orientation.git in Terminal.
2. cd into the cloned directory.
3. Runbin/setup in Terminal. This will install project dependencies.

• RunUSE_OSX_SERVICES=true bin/setup if you don't plan on using Docker to run system dependencies

4. Check the output in Terminal. You should see a line that saysUse the following value for the SECRET_KEY_BASE key: with a long random string afterward. Copy the string and find the paste it in the.env file as theSECRET_KEY_BASE, aroundline 20.
5. In the.env file, set theDATABASE_USERNAME andDATABASE_PASSWORD.
6. Runrake db:create db:setup in Terminal.
7. Runrails s to start the server.
8. Visit atlocalhost:3000.

Make sure to check theinstallation task ifanything 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 theenvironment variables needed to configure Orientation.

OAuth is disabled in development and you will be signed in as whicheveruser is returned fromUser.first.

See.env.example file. Note that if you host your Orientationon Heroku you'll need to set those environment variables manually. I recommenddotenv-heroku to do this easilyusing you local (git-ignored).env file as a canonical source.

Multiple buildpack support used to be unofficial and relied ona 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 yarn 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 yourappnameheroku 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 URLs1. https://github.com/heroku/heroku-buildpack-nodejs2. https://github.com/heroku/heroku-buildpack-ruby

• Go to theGoogle Developers Console and create a new project
• Once you've created the project, go toAPIs 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 toCredentials 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 theGOOGLE_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 ourMandrill documentation.

Orientation uses a Sass-based CSS architecture calledMVCSS.It was extracted fromEnvy andCode School work by both front-end teams.

It's not nearly as complex as a framework. The basic gist is that we try tokeep things as modular and dynamic as possible. Magic values are not welcome.If you contribute styling changes to Orientation, please take the time to getthe lay of the land.

In development we cheat around OAuth by simply usingUser.first as thecurrent user because it's easy and we're lazy. Testing OAuth in dev ishard.

If you're curious what the OmniAuth hash from Google OAuth 2 looks likecheckthis out.

We welcome those with open arms but we kindly ask that youread our contribution guidelines before submitting pull requests. ❤️

Orientation is MIT licensed. SeeLICENSE for details.