refactor the NBs as a troubleshooting section

README.md

@@ -89,69 +89,6 @@ inside `/opt/` (in fact it overrides the actual application files provided by
 the docker image). The purpose is to avoid rebuilding a new docker image for
 each development iteration. 
 
-**Nota Bene ; installation on fedora Os versions , GROUP EDITION**
-
-The docker demon is coded in such a way that if he doesn't find a docker group in the list of groups , 
-
-he automatically sets the socket's permission as root .
-
-Now if the group exists , the docker demon automatically gives the docker group read/write access to the socket , 
-
-then users belonging to this group inherit the same rights .
-
-So in order to install the developpement environment on fedora as non-sudo user you must edit the list of groups , 
-
-adding a docker group with your username on it .
-
-To do so you must run the following commands :
-
-<pre>sudo groupadd docker
-
-newgrp docker</pre>
-
-Now if the new group docker command doesn't work then you have another solution to validate the group creation changes .
-
-You can edit the changes using the vigr command .
-
-<pre>sudo vigr</pre>
-
-Beware though , while using vigr , you must put ":" after the group name before entering your username .
-
-**Nota Bene ; installation on fedora Os versions , dev-mysql installation as non-sudo**
-
-In the following "getting started" chapter , step 2 is a VERY important step , as a non-sudo user , you MUST set the permissions of these directories .
-
-If you do not , the bootstrap script won't be able to write down all the data needed in the /data/dev directories at its execution .
-
-Typically the error logs you will get will be :
-
-mkdir: cannot create directory ‘/vol/rw’: Permission denied
-
-mkdir: cannot create directory ‘/vol/log’: Permission denied
-
-If somehow you skipped this step , the fix is as follows :
-
- <pre>id USER</pre>
- 
- ==> uid=657078(USER) gid=29005(ascii) groups=29005(ascii),971(vboxusers),1000(docker)
- 
- <pre>sudo chown -R USER:ascii /data/dev</pre>
- 
- Then you must erase all the content of the /data/dev directories , to do so :
- 
- <pre>sudo rm -rf /data/dev/mysql/*</pre>
- 
- If you don't erase it's content , the typical error log you will get each time you try to execute the ./bootstrap script will be :
-
- error: db is already initialised
-
-**Besides** : dev-nginx won't be able to start too at the ./bootsrap execution if he can't access the database in dev-mysql , 
-
-so you would get the following error logs if dev-mysql hasn't started properly :
-
-ERROR: for dev-nginx  Cannot create container for service dev-nginx: Device is Busy
-
-ERROR: Encountered errors while bringing up the project.
 
 ### Getting started
 
@@ -268,6 +205,53 @@ https://docs.docker.com/compose/]()
 	fig logs --tail=1 --follow
 	</pre>
 
+
+### Troubleshooting
+
+#### Fedora OS: docker.sock usable by root user only
+
+The docker socket `/run/docker.sock` for interacting with the docker daemon is
+owned by `root:root` with `0600` permissions. Only the root user can use it
+
+To use it as an ordinary user, create the `docker` group, then the docker
+engine will automatically make its socket owned by `root:docker`. Users who are
+members of the docker group will be able to use it. 
+
+To do so you must run the following commands :
+
+<pre>sudo groupadd docker</pre>
+
+Edit the group to add the relevant users to the `docker` group (add them at the
+end of the line starting with `docker:`, separated by commas)
+
+<pre>sudo vigr</pre>
+
+Re-open your session (to be effectively in the docker group)
+
+
+#### **dev-mysql** initialisation fails
+
+The `prepare.sh` script (also sourced by the `./bootstrap` script) creates the
+`/data/dev/*/` with the ownership set to the calling user. **Be sure not to run
+it as root**, otherwise it will be owned by root and you may have errors like:
+
+	mkdir: cannot create directory ‘/vol/rw’: Permission denied
+	mkdir: cannot create directory ‘/vol/log’: Permission denied
+
+If somehow you skipped this step, you can reset the ownership to the current user:
+
+	sudo chown    USER: /data/dev
+	sudo chown -R USER: /data/dev/{registry,mysql,rails}
+
+If you are completely lost, you can just restart the initialisation from scratch:
+
+	fig down
+	sudo rm -rf /data/dev
+	. prepare.sh
+	./bootstrap
+ 
+
+
 Production environment
 ----------------------