Download as
Browse Code »

Commit 896b8e22b53446eca0a70049c0d1b027256081f3

Authored by Stephen Crosby
1 parent c0b84268
Exists in master and in 1 other branch production

review docs and prep rc0.4

Showing 2 changed files with 109 additions and 223 deletions   Show diff stats
CHANGELOG.md
  Diff comments   View file @896b8e2
1   -## 0.4.0 - Not released Yet
  1 +## 0.4.0
2 2  
3 3 - #791 Fix double escaping of problem title in list view.(@felixbuenemann)
4 4 - #790 Fix favicon location.(@felixbuenemann)
5 5 - #716 Fix inline comments styles.(@oelmekki)
6   -- Update to rails 4.1.(@arthurnn)
  6 +- #778 Update to rails 4.1.(@arthurnn)
7 7 - #682 Namespace fingerprint classes better.(@csaunders)
8 8 - Drop ruby support for versions 1.9.x, and 2.0.x.(@arthurnn)
9   -- #773 Only leave GitHub issue tracker on vanila errbit, as the others could be added just using the plugin.(@arthurnn)
  9 +- #773 Only leave GitHub issue tracker on vanila errbit, as the others could be
  10 + added just using the plugin.(@arthurnn)
10 11 - #768 Update to Mongoid 4.0 and rails to 4.0 (@arthurnn)
  12 +- #820 Environment-only configuration
11 13  
12 14 ## 0.3.0
13 15  
... ...
README.md
  Diff comments   View file @896b8e2
... ... @@ -9,15 +9,11 @@
9 9 [gemnasium-img-url]:https://gemnasium.com/errbit/errbit.png
10 10 [gemnasium-url]:https://gemnasium.com/errbit/errbit
11 11  
12   -
13   -
14 12 ### The open source, self-hosted error catcher
15 13  
16   -
17 14 Errbit is a tool for collecting and managing errors from other applications.
18   -It is [Airbrake](http://airbrake.io) (formerly known as Hoptoad) API compliant,
19   -so if you are already using Airbrake, you can just point the `airbrake` gem to your Errbit server.
20   -
  15 +It is [Airbrake](http://airbrake.io) API compliant, so if you are already using
  16 +Airbrake, you can just point the `airbrake` gem to your Errbit server.
21 17  
22 18 <table>
23 19 <tr>
... ... @@ -52,10 +48,10 @@ so if you are already using Airbrake, you can just point the `airbrake` gem to y
52 48 </tr>
53 49 </table>
54 50  
55   -
56 51 Errbit may be a good fit for you if:
57 52  
58   -* Your exceptions may contain sensitive data that you don't want sitting on someone else's server
  53 +* Your exceptions may contain sensitive data that you don't want sitting on
  54 + someone else's server
59 55 * Your application is behind a firewall
60 56 * You'd like to brand your error catcher
61 57 * You want to add customer features to your error catcher
... ... @@ -64,26 +60,18 @@ Errbit may be a good fit for you if:
64 60 If this doesn't sound like you, you should probably stick with a hosted service such as
65 61 [Airbrake](http://airbrake.io).
66 62  
67   -
68 63 Mailing List
69 64 ------------
70 65  
71   -Join the Google Group at https://groups.google.com/group/errbit to receive updates and notifications.
72   -
73   -Demo
74   -----
75   -
76   -There is a demo available at [http://errbit-demo.herokuapp.com/](http://errbit-demo.herokuapp.com/)
77   -
78   -Email: demo@errbit-demo.herokuapp.com<br/>
79   -Password: password
  66 +Join the Google Group at https://groups.google.com/group/errbit to receive
  67 +updates and notifications.
80 68  
81 69 # Requirements
82 70  
83   -The list of requirements to install Errbit are :
  71 +The list of requirements to install Errbit are:
84 72  
85   - * Ruby 2.1.0 or higher
86   - * MongoDB 2.2.0 or higher
  73 +* Ruby 2.1.0 or higher
  74 +* MongoDB 2.2.0 or higher
87 75  
88 76 Installation
89 77 ------------
... ... @@ -92,49 +80,11 @@ Installation
92 80 Rails applications. If you're uncomfortable with any steps below then Errbit is not
93 81 for you.
94 82  
95   -**Set up your local box or server(Ubuntu):**
96   -
97   - * Install MongoDB. Follow the directions [here](http://www.mongodb.org/display/DOCS/Ubuntu+and+Debian+packages), then:
98   -
99   -```bash
100   -apt-get update
101   -apt-get install mongodb-10gen
102   -```
103   -
104   - * Install libxml, libzip, libssl and libcurl
105   -
106   -```bash
107   -apt-get install libxml2 libxml2-dev libxslt-dev libcurl4-openssl-dev libzip-dev libssl-dev
108   -```
109   -
110   - * Install Bundler
111   -
112   -```bash
113   -gem install bundler
114   -```
115   -
116   -**Running Locally:**
117   -
118   - * Install dependencies
119   -
120   -```bash
121   -bundle install
122   -```
123   -
124   - * Install MongoDB. Follow the directions [here](http://www.mongodb.org/display/DOCS/Ubuntu+and+Debian+packages), then:
125   -
126   - * Bootstrap Errbit. This will seed the database. Make sure you copy the
127   - username and password down someplace safe.
128   -
129   -```bash
130   -rake errbit:bootstrap
131   -```
132   -
133   - * Start Server
134   -
135   -```bash
136   -rails s
137   -```
  83 +* [Install MongoDB](https://www.mongodb.org/downloads)
  84 +* git clone https://github.com/errbit/errbit.git
  85 +* bundle install
  86 +* bundle exec rake errbit:bootstrap
  87 +* bundle exec rails server
138 88  
139 89 Configuration
140 90 -------------
... ... @@ -152,57 +102,63 @@ See [notes on deployment](docs/deployment.md)
152 102 Authentication
153 103 --------------
154 104 ### Configuring GitHub authentication:
155   -* Set GITHUB_AUTHENTICATION to true
  105 +* Set GITHUB_AUTHENTICATION=true
156 106 * Register your instance of Errbit at https://github.com/settings/applications
157 107  
158   -If you hosted Errbit at errbit.example.com, you would fill in:
  108 +If you host Errbit at errbit.example.com, you would fill in:
159 109  
160   -<table>
161   - <tr><th>URL:</th><td><a href="http://errbit.example.com/">http://errbit.example.com/</a></td></tr>
162   - <tr><th>Callback URL:</th><td><a href="http://errbit.example.com/users/auth/github">http://errbit.example.com/users/auth/github</a></td></tr>
163   -</table>
  110 +<dl>
  111 +<dt>URL
  112 +<dd>http://errbit.example.com
  113 +<dt>Callback URL
  114 +<dd>http://errbit.example.com/users/auth/github
  115 +</dl>
164 116  
165 117 * After you have registered your app, set GITHUB_CLIENT_ID and GITHUB_SECRET
166 118 with your app's Client ID and Secret key.
167 119  
168 120 When you start your applicatoin, you should see the option to **Sign in with
169   -GitHub** on the Login page.
170   -
171   -You will also be able to link your GitHub profile to your user account on your
172   -**Edit profile** page.
173   -
174   -If you have signed in with GitHub, or linked your GitHub profile, and the App
175   -has a GitHub repo configured, then you will be able to create issues on GitHub.
176   -You will still be able to create an issue on the App's configured issue
177   -tracker.
178   -
179   -You can change the requested account permissions by setting
180   -`GITHUB_ACCESS_SCOPE` to:
181   -
182   -<table>
183   - <tr><th>['repo'] </th><td>Allow creating issues for public and private repos.</td></tr>
184   - <tr><th>['public_repo'] </th><td>Only allow creating issues for public repos.</td></tr>
185   - <tr><th>[] </th><td>No permission to create issues on any repos.</td></tr>
186   -</table>
  121 +GitHub** on the Login page. You will also be able to link your GitHub profile
  122 +to your user account on your **Edit profile** page.
  123 +
  124 +If you have signed in with GitHub, or linked your GitHub profile, and you're
  125 +working with an App that has a GitHub repo configured, then you will be able to
  126 +create issues on GitHub. If you use another issue tracker, see [Issue
  127 +Trackers](#issue-trackers).
  128 +
  129 +You can change the OAuth scope Errbit requests from GitHub by setting
  130 +`GITHUB_ACCESS_SCOPE`. The default ['repo'] is very permissive, but there are a
  131 +few others that could make sense for your needs:
  132 +
  133 +<dl>
  134 +<dt>GITHUB_ACCESS_SCOPE="['repo']"</dt>
  135 +<dd>Allow creating issues for public and private repos</dd>
  136 +<dt>GITHUB_ACCESS_SCOPE="['public_repo']"</dt>
  137 +<dd>Allow creating issues for public repos only</dd>
  138 +<dt>GITHUB_ACCESS_SCOPE="[]"</dt>
  139 +<dd>No permissions at all, but allows errbit login through github</dd>
  140 +</dl>
187 141  
188 142 * GITHUB_ORG_ID is an optional environment variable you can set to your own
189   - github organization id. If set, any user of the specified GitHub organization
190   - can login. If it is their first time, an account will automatically be
191   - created for them.
  143 + github organization id. If set, only users of the specified GitHub
  144 + organization can log in to Errbit through GitHub. Errbit will provision
  145 + accounts for new users.
192 146  
193 147 ### Configuring LDAP authentication:
194 148  
195   - * Set `USER_HAS_USERNAME` to `true`
196   - * Follow the instructions at https://github.com/cschiewek/devise_ldap_authenticatable
197   - to set up the devise_ldap_authenticatable gem.
198   - * Ensure to set ```config.ldap_create_user = true``` in ```config/initializers/devise.rb```, this enables creating the users from LDAP, otherwhise login will not work.
199   - * Create a new initializer (e.g. ```config/initializers/devise_ldap.rb```) and add the following code to enable ldap authentication in the User-model:
  149 +* Set USER_HAS_USERNAME=true
  150 +* Follow the instructions at
  151 + https://github.com/cschiewek/devise_ldap_authenticatable to set up the
  152 + devise_ldap_authenticatable gem.
  153 +* Set ```config.ldap_create_user = true``` in ```config/initializers/devise.rb```, this enables creating the users from LDAP, otherwhise login will not work.
  154 +* Create a new initializer (e.g. ```config/initializers/devise_ldap.rb```) and add the following code to enable ldap authentication in the User-model:
  155 +
200 156 ```ruby
201 157 Errbit::Config.devise_modules << :ldap_authenticatable
202 158 ```
203 159  
204   - * If you are authenticating by `username`, you will need to set the user's email manually
205   - before authentication. You must add the following lines to `app/models/user.rb`:
  160 +* If you are authenticating by `username`, you will need to set the user's email manually
  161 +before authentication. You must add the following lines to `app/models/user.rb`:
206 162  
207 163 ```ruby
208 164 def ldap_before_save
... ... @@ -215,8 +171,8 @@ Errbit::Config.devise_modules &lt;&lt; :ldap_authenticatable
215 171 end
216 172 ```
217 173  
218   - * Now login with your user from LDAP, this will create a user in the database
219   - * Open a rails console and set the admin flag for your user:
  174 +* Now login with your user from LDAP, this will create a user in the database
  175 +* Open a rails console and set the admin flag for your user:
220 176  
221 177 ```ruby
222 178 user = User.first
... ... @@ -237,114 +193,55 @@ rake assets:precompile
237 193  
238 194 This will ensure that your application stays up to date with any schema changes.
239 195  
  196 +### Upgrading errbit from version 0.3 to 0.4
240 197  
241   -### Upgrading errbit from version 0.2 to 0.3
242   -
243   -The MongoDB connection file `config/mongoid.yml` has changed between version 0.2 and
244   -0.3. We have provided a new example configuration file to use at `config/mongoid.example.yml`.
245   -
246   -This change is not needed if you use ENV variables to
247   -define access to your MongoDB database.
248   -
249   -
250   -## User information in error reports
251   -
252   -Errbit can now display information about the user who experienced an error.
253   -This gives you the ability to ask the user for more information,
254   -and let them know when you've fixed the bug.
255   -
256   -If you are running a Rails application and would like to include information
257   -about the current user in your error reports, you can replace the `airbrake`
258   -gem in your Gemfile with `airbrake_user_attributes`.
259   -This gem is a wrapper around the `airbrake` gem and will automatically
260   -inject information about the user into any error reports,
261   -so long as your controllers respond to a `#current_user` method.
262   -The user's attributes are filtered to remove authentication fields.
263   -
264   -If user information is received with an error report,
265   -it will be displayed under the *User Details* tab:
266   -
267   -
268   -![User details tab](http://errbit.github.com/errbit/images/error_user_information.png)
269   -
270   -(This tab will be hidden if no user information is available.)
  198 +* All configuration is now done through the environment. See
  199 + [configuration](docs/configuration.md)
  200 +* Ruby 1.9 and 2.0 are no longer offically supported. Please upgrade to Ruby
  201 + 2.1+
  202 +* Errbit now maintains an issue tracker only for github. If you're using
  203 + another issue tracker integration, you may need to maintain it yourself. See
  204 + (issue trackers)[#issue-trackers]
271 205  
272 206 Javascript error notifications
273 207 --------------------------------------
274 208  
275   -You can log javascript errors that occur in your application by including
  209 +You can log javascript errors that occur in your application by including the
276 210 [airbrake-js](https://github.com/airbrake/airbrake-js) javascript library.
277 211  
278   -First you need to add airbrake-shim.js to your site and set some basic configuration
279   -options:
280   -
281   -```
282   -<script src="airbrake-shim.js" data-airbrake-project-id="ERRBIT API KEY" data-airbrake-project-key="ERRBIT API KEY" data-airbrake-environment-name="production" data-airbrake-host="http://errbit.yourdomain.com"></script>
283   -```
284   -
285   -Or you can just add shim file and set these options using:
  212 +Install airbrake-js according to the docs at
  213 +[airbrake-js](https://github.com/airbrake/airbrake-js) and set your project and
  214 +host as early as possible:
286 215  
287   -```
  216 +```javascript
288 217 Airbrake.setProject("ERRBIT API KEY", "ERRBIT API KEY");
289 218 Airbrake.setHost("http://errbit.yourdomain.com");
290 219 ```
291 220  
292   -And that's it.
293   -
294   -Testing API V3 using ruby airbrake client
295   ------------------------------------------
296   -
297   -If you want you test standard airbrake ruby gem with API V3. To do that you
298   -need to change your airbrake initializer file to something like this:
299   -
300   -```
301   -Airbrake.configure do |config|
302   - config.api_key = ENV['airbrake_api_key']
303   - config.host = ENV['airbrake_host']
304   - config.port = ENV['airbrake_port'].to_i
305   - config.secure = ENV['airbrake_secure'] == 'true'
306   - config.project_id = ENV['airbrake_api_key']
307   -end
308   -
309   -class Airbrake::Sender
310   - def json_api_enabled?
311   - true
312   - end
313   -end
314   -```
315   -
316   -It is important to set project_id option to the same value as api_key, because
317   -project_id is required for building url to api endpoint. And airbrake has a bug
318   -that removes api_key from endpoint url. The only way to get this value is by passing
319   -it as project_id. This little monkey-patch is required because airbrake gem only
320   -uses v3 api when host is set to collect.airbrake.io.
321   -
322   -V3 request don't have framework option so you won't see this value in your error
323   -notices in errbit. Besides that everything looks the same. It was tested using
324   -rake airbrake:test for both v2 and v3.
325   -
326 221 Using custom fingerprinting methods
327 222 -----------------------------------
328 223  
329   -Errbit allows you to use your own Fingerprinting Strategy.
330   -If you are upgrading from a very old version of errbit, you can use the `Fingerprint::MD5` for compatibility. The fingerprint strategy can be changed by adding an initializer to errbit:
  224 +Errbit collates errors into groups using a fingerprinting strategy. If you find
  225 +your errors are not getting grouped the way you would expect, you may need to
  226 +implement your own strategy. A fingerprinting strategy is just a class that
  227 +implements a ::generate class method. See the classes in
  228 +`app/models/fingerprint/` if you need some inspiration. You can install it with
  229 +an initializer like:
331 230  
332 231 ```ruby
333   -# config/fingerprint.rb
334   -ErrorReport.fingerprint_strategy = Fingerprint::MD5
  232 +# config/initializers/fingerprint.rb
  233 +ErrorReport.fingerprint_strategy = MyStrategy
335 234 ```
336 235  
337   -The easiest way to add custom fingerprint methods is to simply subclass `Fingerprint`
338   -
339 236 Plugins and Integrations
340 237 ------------------------
341   -You can extend Errbit by adding Ruby gems and plugins which are generally also
342   -gems. It's nice to keep track of which gems are core Errbit dependencies and
343   -which gems are your own dependencies. If you want to add gems to your own
344   -Errbit, place them in a new file called `UserGemfile`. If you want to use a
345   -file with a different name, you can pass the name of that file in an
346   -environment variable named `USER_GEMFILE`. For example, if you wanted to use
347   -errbit_jira_plugin, you could:
  238 +You can extend Errbit by adding Ruby gems and plugins which are typically gems.
  239 +It's nice to keep track of which gems are core Errbit dependencies and which
  240 +gems are your own dependencies. If you want to add gems to your own Errbit,
  241 +place them in a new file called `UserGemfile` and Errbit will treat that file
  242 +as an additional Gemfile. If you want to use a file with a different name, you
  243 +can pass the name of that file in an environment variable named `USER_GEMFILE`.
  244 +If you want to use errbit_jira_plugin, just add it to UserGemfile:
348 245  
349 246 ```bash
350 247 echo "gem 'errbit_jira_plugin'" > UserGemfile
... ... @@ -361,38 +258,29 @@ supported issue tracker plugin is
361 258 If you want to implement your own issue tracker plugin, read the README.md file
362 259 at [errbit_plugin](https://github.com/errbit/errbit_plugin).
363 260  
364   -Notification Service
365   ---------------------
366   -**Flowdock Notification**
367   -
368   -Allow notification to [Flowdock](https://www.flowdock.com/). See
369   -[complete documentation](docs/notifications/flowdock/index.md)
370   -
371   -
372 261 What if Errbit has an error?
373 262 ----------------------------
374 263  
375   -Errbit will log it's own errors to an internal app named **Self.Errbit**.
376   -The **Self.Errbit** app will be automatically created whenever the first error happens.
  264 +Errbit will log it's own errors to an internal app named **Self.Errbit**. The
  265 +**Self.Errbit** app is automatically created when the first error happens.
377 266  
378   -If your Errbit instance has logged an error, we would appreciate a bug report on GitHub Issues.
379   -You can post this manually at [https://github.com/errbit/errbit/issues](https://github.com/errbit/errbit/issues),
  267 +If your Errbit instance has logged an error, we would appreciate a bug report
  268 +on GitHub Issues. You can post this manually at
  269 +[https://github.com/errbit/errbit/issues](https://github.com/errbit/errbit/issues),
380 270 or you can set up the GitHub Issues tracker for your **Self.Errbit** app:
381 271  
382   - * 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`.)
383   -
  272 + * Go to the **Self.Errbit** app's edit page. If that app does not exist yet,
  273 + go to the apps page and click **Add a new App** to create it. (You can also
  274 + create it by running `rake airbrake:test`.)
384 275 * In the **Issue Tracker** section, click **GitHub Issues**.
385   -
386 276 * Fill in the **Account/Repository** field with **errbit/errbit**.
387   -
388 277 * Fill in the **Username** field with your github username.
389   -
390   - * 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).
391   -
  278 + * If you are logged in on [GitHub](https://github.com), you can find your
  279 + **API Token** on this page:
  280 + [https://github.com/account/admin](https://github.com/account/admin).
392 281 * Save the settings by clicking **Update App** (or **Add App**)
393   -
394   - * You can now easily post bug reports to GitHub Issues by clicking the **Create Issue** button on a **Self.Errbit** error.
395   -
  282 + * You can now easily post bug reports to GitHub Issues by clicking the
  283 + **Create Issue** button on a **Self.Errbit** error.
396 284  
397 285 Use Errbit with applications written in other languages
398 286 -------------------------------------------------------
... ... @@ -415,17 +303,14 @@ Solutions known to work are listed below:
415 303 </tr>
416 304 </table>
417 305  
418   -TODO
419   -----
420   -
421   -* Add ability for watchers to be configured for types of notifications they should receive
422   -
423   -
424 306 People using Errbit
425 307 -------------------
426 308  
427   -See our wiki page for a [list of people and companies around the world who use Errbit](https://github.com/errbit/errbit/wiki/People-using-Errbit).
428   -Feel free to [edit this page](https://github.com/errbit/errbit/wiki/People-using-Errbit/_edit), and add your name and country to the list if you are using Errbit.
  309 +See our wiki page for a [list of people and companies around the world who use
  310 +Errbit](https://github.com/errbit/errbit/wiki/People-using-Errbit). You may
  311 +[edit this
  312 +page](https://github.com/errbit/errbit/wiki/People-using-Errbit/_edit), and add
  313 +your name and country to the list if you are using Errbit.
429 314  
430 315  
431 316 Special Thanks
... ... @@ -440,8 +325,7 @@ Special Thanks
440 325 * [Relevance](http://thinkrelevance.com) - For giving me Open-source Fridays to work on Errbit and all my awesome co-workers for giving feedback and inspiration.
441 326 * [Thoughtbot](http://thoughtbot.com) - For being great open-source advocates and setting the bar with [Airbrake](http://airbrake.io).
442 327  
443   -See the [contributors graph](https://github.com/errbit/errbit/graphs/contributors) for further details.
444   -
  328 +See the [contributors graph](https://github.com/errbit/errbit/graphs/contributors) for more details.
445 329  
446 330 Contributing to Errbit
447 331 ------------
... ... @@ -456,4 +340,4 @@ Check the .travis.yml file to see how tests are run
456 340 Copyright
457 341 ---------
458 342  
459   -Copyright (c) 2010-2014 Errbit Team. See LICENSE for details.
  343 +Copyright (c) 2010-2015 Errbit Team
... ...