{"id":13819128,"url":"https://github.com/orientation/orientation","last_synced_at":"2025-05-16T04:32:42.576Z","repository":{"id":5089560,"uuid":"6251961","full_name":"orientation/orientation","owner":"orientation","description":"Your best weapon in the fight against outdated documentation.","archived":false,"fork":false,"pushed_at":"2023-03-08T19:46:18.000Z","size":6342,"stargazers_count":362,"open_issues_count":65,"forks_count":71,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-11-19T18:46:39.940Z","etag":null,"topics":["documentation","rails","ruby"],"latest_commit_sha":null,"homepage":"http://orientation.io","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"netconstructor/node-rate-limiter","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orientation.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2012-10-16T21:25:35.000Z","updated_at":"2024-08-18T14:39:26.000Z","dependencies_parsed_at":"2023-07-05T19:02:06.132Z","dependency_job_id":null,"html_url":"https://github.com/orientation/orientation","commit_stats":{"total_commits":1806,"total_committers":38,"mean_commits":"47.526315789473685","dds":"0.47840531561461797","last_synced_commit":"562c55418252b05c01140ec0ff102e4d451b4ef1"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orientation%2Forientation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orientation%2Forientation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orientation%2Forientation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orientation%2Forientation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orientation","download_url":"https://codeload.github.com/orientation/orientation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254469610,"owners_count":22076526,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","rails","ruby"],"created_at":"2024-08-04T08:00:40.806Z","updated_at":"2025-05-16T04:32:37.747Z","avatar_url":"https://github.com/orientation.png","language":"Ruby","readme":"# ![Orientation][orientation-logo]\n\n[![Build Status][ci-image]][ci]\n[![Code Climate][codeclimate-image]][codeclimate]\n![Ruby Version][ruby-version-image]\n\n## What is Orientation?\n\nDocumentation is hard. People forget to write it, and they are asked the\nsame question over and over again. When they finally do write it down,\npeople can't find it or it gets out of date before it can be useful.\n\nThe goal of Orientation is to make a single point of entry for any\ninternal question someone may have about the organization:\n\n\u003e How can I help with bugs, maintenance and other issues?\n\n\u003e Do we give student discounts?\n\n\u003e How can I help with support?\n\n![Orientation's Homepage][orientation-homepage]\n\nCheck out the [Purpose of Orientation, and Current and Future Features](doc/FEATURES.md).\n\n[Try the Demo](http://orientation-demo.herokuapp.com)\nYou'll need a Google Apps account to sign in.*\n\n### Authentication\n\nI originally tried to make Orientation as easy to onboard to as possible for\npeople in our team. While a huge majority of us had GitHub accounts, not everyone\ndid. Nor was it realistic to expect non-developers to setup a GitHub account\njust to use a documentation tool. We did — however have — company Google Apps\naccounts, so this is what I used. I want to enable custom OAuth providers soon.\n\n## Requirements\n\n### Software\n\nSome of these system dependencies can be installed on a macOS development\nmachine with the `bin/system` command using [Homebrew](https://brew.sh/).\n\n- Ruby 2.4 to 2.6\n- PostgreSQL 9.3+ (with JSON support, and fuzzystrmatch \u0026 pg_trgm extensions)\n- Node.js 8.12.0 (for yarn)\n- yarn\n\nNode is available on Heroku if you decide to deploy there, which means\nthere should not be any issues when deploying or running Orientation\nthere.\n\n### Services\n- Mandrill account for transactional emails\n- Google API project with access to the \"Contacts API\" and \"Google+ API\" for OAuth authentication of users.\n\n## Installation\n\n### Heroku\nIf you want to quickly test out your own Orientation installation, you can use\nthe Heroku button:\n\n[![Heroku Button][heroku-image]][heroku]\n\n### Docker\nSee [Docker installation instructions](DOCKER.md).\n\n## Local Setup\n\n1. Run `git clone git@github.com:orientation/orientation.git` in Terminal.\n2. `cd` into the cloned directory.\n3. Run `bin/setup` in Terminal. This will install project dependencies.\n  - Run `USE_OSX_SERVICES=true bin/setup` if you don't plan on using Docker to run system dependencies\n4. Check the output in Terminal. You should see a line that says `Use 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 the `SECRET_KEY_BASE`, around `line 20`.\n5. In the `.env` file, set the `DATABASE_USERNAME` and `DATABASE_PASSWORD`.\n6. Run `rake db:create db:setup` in Terminal.\n7. Run `rails s` to start the server.\n8. Visit at `localhost:3000`.\n\n*Make sure to check the [installation task](lib/tasks/orientation.rake) if\nanything strange happens during installation.*\n\n*Once you're done, pay close attention to the `.env` file that will appear at the root. It's copied from [`.env.example`](.env.example) and contains all the\nenvironment variables needed to configure Orientation.*\n\n*OAuth is disabled in development and you will be signed in as whichever\nuser is returned from `User.first`.*\n\n## Deployment\n\n### Required Environment Variables\n\nSee [.env.example](.env.example) file. Note that if you host your Orientation\non Heroku you'll need to set those environment variables manually. I recommend\n[dotenv-heroku](https://github.com/sideshowcoder/dotenv-heroku) to do this easily\nusing you local (git-ignored) `.env` file as a canonical source.\n\n### Multiple Buildpacks\n\nMultiple buildpack support used to be unofficial and relied on [a custom buildpack created by David Dollar](https://github.com/ddollar/heroku-buildpack-multi.git). This is no longer the case since Heroku has rolled out official support for multiple buildpacks.\n\nTherefore, 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.\n\nNote that for some reason you need to be the owner of the app on Heroku in order to be able to do this:\n\n```shell\nheroku buildpacks:add --index 1 https://github.com/heroku/heroku-buildpack-ruby -a yourappname\nheroku buildpacks:add --index 2 https://github.com/heroku/heroku-buildpack-nodejs -a yourappname\n```\n\nWhen you run the following command, your output should be similar:\n\n```shell\n$ heroku buildpacks -a yourappname\n=== yourappname Buildpack URLs\n1. https://github.com/heroku/heroku-buildpack-nodejs\n2. https://github.com/heroku/heroku-buildpack-ruby\n```\n\n### Google OAuth 2 setup\n- Go to the [Google Developers Console](https://console.developers.google.com/project) and create a new project\n- Once you've created the project, go to `APIs` and add the `Contacts API` and the `Google+ API` (you won't need a Google+ account to sign in, this is just an annoying Google quirk).\n- Then go to `Credentials` and `Create 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 the `JavaScript Origins` setting, but make sure to use `http://yourdomain.com/auth/google_oauth2/callback` for in the `Redirect 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.\n- Don't forget to go update the `GOOGLE_KEY` and `GOOGLE_SECRET` environment variables with the credentials Google gave you when you created your Client ID, otherwise the redirection process will fail.\n\n### Transactional Emails with Mandrill\n\nIf 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](doc/MANDRILL.md).\n\n## Development\n\n### Styling\n\nOrientation uses a Sass-based CSS architecture called [MVCSS](http://mvcss.io/).\nIt was extracted from [Envy](http://madewithenvy.com) and [Code School](http//codeschool.com) work by both front-end teams.\n\nIt's not nearly as complex as a framework. The basic gist is that we try to\nkeep things as modular and dynamic as possible. Magic values are not welcome.\nIf you contribute styling changes to Orientation, please take the time to get\nthe lay of the land.\n\n### OAuth in development\nIn development we cheat around OAuth by simply using `User.first` as the\ncurrent user because it's easy and we're lazy. Testing OAuth in dev is\nhard.\n\nIf you're curious what the OmniAuth hash from Google OAuth 2 looks like [check\nthis out](doc/OAUTH.md).\n\n[ci]: https://travis-ci.org/orientation/orientation\n[ci-image]: https://travis-ci.org/orientation/orientation.svg?branch=master\n[gemnasium]: https://gemnasium.com/orientation/orientation\n[gemnasium-image]: https://gemnasium.com/orientation/orientation.svg\n[codeclimate]: https://codeclimate.com/github/orientation/orientation\n[codeclimate-image]: https://codeclimate.com/github/orientation/orientation/badges/gpa.svg\n[heroku]: https://heroku.com/deploy\n[heroku-image]: https://www.herokucdn.com/deploy/button.svg\n[ruby-version-image]: https://img.shields.io/badge/ruby-2.4%20%E2%80%94%3E%202.6-brightgreen.svg\n\n[orientation-logo]: https://github.com/orientation/orientation/blob/master/public/orientation_logo.png\n[orientation-homepage]: https://cloud.githubusercontent.com/assets/65950/6814712/66cb4684-d281-11e4-800c-329726411b7e.png\n\n## Contributions\n\nWe welcome those with open arms but we kindly ask that you [read our contribution guidelines](CONTRIBUTING.md) before submitting pull requests. :heart:\n\n## License\n\nOrientation is MIT licensed. See [LICENSE](LICENSE) for details.\n","funding_links":[],"categories":["Happy Exploring 🤘","Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forientation%2Forientation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forientation%2Forientation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forientation%2Forientation/lists"}