Download as
Browse Code »

Commit f3f95fd7fbea744b500bffa4e2beccdc379e8e1a

Authored by Nathan Broadbent
1 parent 50e3e2ab
Exists in master and in 1 other branch production

Added GitHub authentication info to README. Replaced numbers with bullets, since they always reset.

Showing 1 changed file with 63 additions and 30 deletions   Show diff stats
README.md
  Diff comments   View file @f3f95fd
... ... @@ -75,20 +75,20 @@ for you. Checkout [Airbrake](http://airbrakeapp.com) from the guys over at
75 75  
76 76 **Set up your local box or server(Ubuntu):**
77 77  
78   - 1. Install MongoDB. Follow the directions [here](http://www.mongodb.org/display/DOCS/Ubuntu+and+Debian+packages), then:
  78 + * Install MongoDB. Follow the directions [here](http://www.mongodb.org/display/DOCS/Ubuntu+and+Debian+packages), then:
79 79  
80 80 ```bash
81 81 apt-get update
82 82 apt-get install mongodb
83 83 ```
84 84  
85   - 2. Install libxml and libcurl
  85 + * Install libxml and libcurl
86 86  
87 87 ```bash
88 88 apt-get install libxml2 libxml2-dev libxslt-dev libcurl4-openssl-dev
89 89 ```
90 90  
91   - 3. Install Bundler
  91 + * Install Bundler
92 92  
93 93 ```bash
94 94 gem install bundler
... ... @@ -96,21 +96,21 @@ gem install bundler
96 96  
97 97 **Running Locally:**
98 98  
99   - 1. Install dependencies
  99 + * Install dependencies
100 100  
101 101 ```bash
102 102 bundle install
103 103 ```
104 104  
105   - 2. Bootstrap Errbit. This will copy over config.yml and also seed the database.
  105 + * Bootstrap Errbit. This will copy over config.yml and also seed the database.
106 106  
107 107 ```bash
108 108 rake errbit:bootstrap
109 109 ```
110 110  
111   - 3. Update the config.yml and mongoid.yml files with information about your environment
  111 + * Update the config.yml and mongoid.yml files with information about your environment
112 112  
113   - 4. Start Server
  113 + * Start Server
114 114  
115 115 ```bash
116 116 script/rails server
... ... @@ -118,14 +118,14 @@ script/rails server
118 118  
119 119 **Deploying:**
120 120  
121   - 1. Bootstrap Errbit. This will copy over config.yml and also seed the database.
  121 + * Bootstrap Errbit. This will copy over config.yml and also seed the database.
122 122  
123 123 ```bash
124 124 rake errbit:bootstrap
125 125 ```
126 126  
127   - 2. Update the deploy.rb file with information about your server
128   - 3. Setup server and deploy
  127 + * Update the deploy.rb file with information about your server
  128 + * Setup server and deploy
129 129  
130 130 ```bash
131 131 cap deploy:setup deploy
... ... @@ -133,13 +133,13 @@ cap deploy:setup deploy
133 133  
134 134 **Deploying to Heroku:**
135 135  
136   - 1. Clone the repository
  136 + * Clone the repository
137 137  
138 138 ```bash
139 139 git clone http://github.com/errbit/errbit.git
140 140 ```
141 141  
142   - 2. Create & configure for Heroku
  142 + * Create & configure for Heroku
143 143  
144 144 ```bash
145 145 gem install heroku
... ... @@ -155,13 +155,13 @@ heroku config:add ERRBIT_EMAIL_FROM=example@example.com
155 155 git push heroku master
156 156 ```
157 157  
158   - 3. Seed the DB (_NOTE_: No bootstrap task is used on Heroku!)
  158 + * Seed the DB (_NOTE_: No bootstrap task is used on Heroku!)
159 159  
160 160 ```bash
161 161 heroku run rake db:seed
162 162 ```
163 163  
164   - 4. If you are using a free database on Heroku, you may want to periodically clear resolved errors to free up space.
  164 + * If you are using a free database on Heroku, you may want to periodically clear resolved errors to free up space.
165 165  
166 166 ```bash
167 167 # Install the heroku cron addon, to clear resolved errors daily:
... ... @@ -171,23 +171,52 @@ heroku addons:add cron:daily
171 171 heroku rake errbit:db:clear_resolved
172 172 ```
173 173  
174   - 5. You may want to enable the deployment hook for heroku :
  174 + * You may want to enable the deployment hook for heroku :
175 175  
176 176 ```bash
177 177 heroku addons:add deployhooks:http url="http://YOUR_ERRBIT_HOST/deploys.txt?api_key=YOUR_API_KEY"
178 178 ```
179 179  
180   - 5. Enjoy!
  180 + * Enjoy!
  181 +
  182 +
  183 +Authentication
  184 +--------------
  185 +
  186 +**Configuring GitHub authentication:**
  187 +
  188 + * In `config/config.yml`, set `github_authentication` to `true`
  189 + * Register your instance of Errbit at: https://github.com/settings/applications
  190 + If you hosted Errbit at errbit.example.com, you would fill in:
  191 +
  192 +<table>
  193 + <tr><th>URL:</th><td>http://errbit.example.com/</td></tr>
  194 + <tr><th>Callback URL:</th><td>http://errbit.example.com/users/auth/github</td></tr>
  195 +</table>
  196 +
  197 + * After you have registered your app, set `github_client_id` and `github_secret`
  198 + in `config/config.yml` with your app's Client ID and Secret key.
  199 +
  200 +
  201 +After you have followed these instructions, you will be able to
  202 +<img src="http://errbit.github.com/errbit/images/sign_in_with_github_button.png" alt="Sign in with GitHub">
  203 +on the Login page.
  204 +
  205 +You will also be able to link your GitHub profile to your user account on your **Edit profile** page.
  206 +
  207 +If you have signed in with GitHub, or linked your GitHub profile,
  208 +you are able to create an issue on GitHub if the App has a GitHub repo configured.
  209 +You will also be able to create an issue on a configured issue trackers.
181 210  
182 211  
183 212 **Configuring LDAP authentication:**
184 213  
185   - 1. In `config/config.yml`, set `user_has_username` to `true`
186   - 2. Follow the instructions at https://github.com/cschiewek/devise_ldap_authenticatable
  214 + * In `config/config.yml`, set `user_has_username` to `true`
  215 + * Follow the instructions at https://github.com/cschiewek/devise_ldap_authenticatable
187 216 to set up the devise_ldap_authenticatable gem.
188 217  
189   - 3. If you are authenticating by `username`, you will need to set the user's email
190   - after authentication. You can do this by adding the following lines to `app/models/user.rb`:
  218 + * If you are authenticating by `username`, you will need to set the user's email manually
  219 + before authentication. You must add the following lines to `app/models/user.rb`:
191 220  
192 221 ```ruby
193 222 before_save :set_ldap_email
... ... @@ -198,7 +227,7 @@ heroku addons:add deployhooks:http url=&quot;http://YOUR_ERRBIT_HOST/deploys.txt?api_
198 227  
199 228 Upgrading
200 229 ---------
201   -*Note*: When upgrading Errbit, please run:
  230 +When upgrading Errbit, please run:
202 231  
203 232 ```bash
204 233 git pull origin master # assuming origin is the github.com/errbit/errbit repo
... ... @@ -209,7 +238,7 @@ If we change the way that data is stored, this will run any migrations to bring
209 238  
210 239  
211 240 User information in error reports
212   ------------------------------
  241 +---------------------------------
213 242  
214 243 Errbit can now display information about the user who experienced an error.
215 244 This gives you the ability to ask the user for more information,
... ... @@ -256,7 +285,11 @@ Issue Trackers
256 285 * Account is the host of your mingle installation. i.e. **https://mingle.example.com** *note*: You should use SSL if possible.
257 286 * Errbit uses 'sign-in name' & password authentication. You may want to set up an **errbit** user with limited rights.
258 287 * Project id is the identifier of your project, i.e. **awesomeapp** for project at https://mingle.example.com/projects/awesomeapp
259   -* Card properties are comma separated key value pairs. You must specify a 'card_type', but anything else is optional. i.e. card_type = Defect, status = Open, priority = Essential
  288 +* Card properties are comma separated key value pairs. You must specify a 'card_type', but anything else is optional, e.g.:
  289 +
  290 +```
  291 +card_type = Defect, status = Open, priority = Essential
  292 +```
260 293  
261 294 **GitHub Issues Integration**
262 295  
... ... @@ -275,19 +308,19 @@ If your Errbit instance has logged an error, we would appreciate a bug report on
275 308 You can post this manually at [https://github.com/errbit/errbit/issues](https://github.com/errbit/errbit/issues),
276 309 or you can set up the GitHub Issues tracker for your **Self.Errbit** app:
277 310  
278   - 1. Go to the **Self.Errbit** app's edit page. If that app does not exist yet, go to the apps page and click **Add a new App** to create it. (You can also create it by running `rake airbrake:test`.)
  311 + * Go to the **Self.Errbit** app's edit page. If that app does not exist yet, go to the apps page and click **Add a new App** to create it. (You can also create it by running `rake airbrake:test`.)
279 312  
280   - 2. In the **Issue Tracker** section, click **GitHub Issues**.
  313 + * In the **Issue Tracker** section, click **GitHub Issues**.
281 314  
282   - 3. Fill in the **Account/Repository** field with **errbit/errbit**.
  315 + * Fill in the **Account/Repository** field with **errbit/errbit**.
283 316  
284   - 4. Fill in the **Username** field with your github username.
  317 + * Fill in the **Username** field with your github username.
285 318  
286   - 5. If you are logged in on [GitHub](https://github.com), you can find your **API Token** on this page: [https://github.com/account/admin](https://github.com/account/admin).
  319 + * If you are logged in on [GitHub](https://github.com), you can find your **API Token** on this page: [https://github.com/account/admin](https://github.com/account/admin).
287 320  
288   - 6. Save the settings by clicking **Update App** (or **Add App**)
  321 + * Save the settings by clicking **Update App** (or **Add App**)
289 322  
290   - 7. You can now easily post bug reports to GitHub Issues by clicking the **Create Issue** button on a **Self.Errbit** error.
  323 + * You can now easily post bug reports to GitHub Issues by clicking the **Create Issue** button on a **Self.Errbit** error.
291 324  
292 325  
293 326 TODO
... ...