Merge remote-tracking branch 'pr/225' into develop

Fix install issue and update the documentation

During the rails 4 update db:migrate stopped working because the way couchrest loads all models broke. This includes a fix and also updates the install instructions.

I tried to separate advanced topics in development from the others by marking the sections (advanced) in doc/DEVELOP.md

1 files changed, 39 insertions, 19 deletions

diff --git a/README.md b/README.md
index b6f3d1b..e68c117 100644
--- a/README.md
+++ b/README.md
@@ -46,20 +46,6 @@ External docs:
   * Overview of the main code repositories
   * Ideas for discrete, unclaimed development projects that would greatly benefit the LEAP ecosystem.
 
-Known problems
----------------------------
-
-* Client certificates are generated without a CSR. The problem is that
-  this makes the web application extremely vulnerable to denial of
-  service attacks. This is not an issue unless the provider enables the
-  possibility of anonymously fetching a client certificate without
-  authenticating first.
-
-* By its very nature, the user database is vulnerable to enumeration
-  attacks. These are very hard to prevent, because our protocol is
-  designed to allow query of a user database via proxy in order to
-  provide network perspective.
-
 Installation
 ---------------------------
 
@@ -69,17 +55,37 @@ these instructions:
 
 ### Install system requirements
 
+You'll need git, ruby (2.1.5), couchdb and bundler installed.
+On a recent debian based distribution run
+
     sudo apt install git ruby couchdb bundler
 
-Your actual requirements might differ if you are running an older OS that defaults to ruby 1.9.
+For other operation systems please lookup the install instructions of these
+tools.
 
 ### Download source
 
+We host our own git repository. In order to create a local clone run
+
     git clone --recursive git://leap.se/leap_web
+    cd leap_web
+
+The repo is mirrored on github and we accept pull requests there:
+
+    https://github.com/leapcode/leap_web
+
+### Pick branch (development only)
+
+We use the master branch for the stable version deployed to production.
+Development usually happens on the develop branch. So for development you
+want to run
+
+    git checkout origin/develop -b develop
+
+This will create a local branch called develop based on our develop branch.
 
 ### Install required ruby libraries
 
-    cd leap_web
     bundle --binstubs
 
 Typically, you run ``bundle`` as a normal user and it will ask you for a
@@ -88,13 +94,13 @@ have sudo, run ``bundle`` as root.
 
 ### Installation for development purposes
 
-Please see `doc/DEVELOP.md` for further required steps when installing
+Please see `doc/DEVELOP.md` for details about installing
 leap_web for development purposes.
 
-Configuration
+Configuration for Production
 ----------------------------
 
-The configuration file `config/defaults.yml` providers good defaults for
+The configuration file `config/defaults.yml` provides good defaults for
 most values. You can override these defaults by creating a file
 `config/config.yml`.
 
@@ -167,3 +173,17 @@ To run an individual test:
     or
     ruby -Itest certs/test/unit/client_certificate_test.rb
 
+Known problems
+---------------------------
+
+* Client certificates are generated without a CSR. The problem is that
+  this makes the web application extremely vulnerable to denial of
+  service attacks. This is not an issue unless the provider enables the
+  possibility of anonymously fetching a client certificate without
+  authenticating first.
+
+* By its very nature, the user database is vulnerable to enumeration
+  attacks. These are very hard to prevent, because our protocol is
+  designed to allow query of a user database via proxy in order to
+  provide network perspective.
+