Cleaned CONTRIBUTING.adoc and added information about problems with vagrant's synced folders.

Author: soltysh

CONTRIBUTING.adoc

@@ -20,7 +20,7 @@ Or if you are interested in development, start with:
 
 == Download from GitHub
 
-The OpenShift team periodically publishes binaries to GitHub on https://github.com/openshift/origin/releases[the Releases page].  These are Linux, Windows, or Mac OS X 64bit binaries (note that Mac and Windows are client only). You'll need Docker installed on your local system (see https://docs.docker.com/installation/#installation[the installation page] if you've never installed Docker before).
+The OpenShift team periodically publishes binaries to GitHub on https://github.com/openshift/origin/releases[the Releases page].  These are Linux, Windows, or Mac OS X 64bit binaries (note that Mac and Windows are client only). You'll need Docker installed on your local system (see https://docs.docker.com/installation/[the installation page] if you've never installed Docker before).
 
 The tar file for each platform contains a single binary `openshift` which is the all-in-one OpenShift installation.
 
@@ -31,7 +31,7 @@ The tar file for each platform contains a single binary `openshift` which is the
 
 == OpenShift Development
 
-To get started, https://help.github.com/articles/fork-a-repo[fork] the https://github.com/openshift/origin[origin repo]
+To get started, https://help.github.com/articles/fork-a-repo[fork] the https://github.com/openshift/origin[origin repo].
 
 === Develop locally on your host
 
@@ -45,7 +45,7 @@ Here's how to get set up:
 1. For Go, Git and optionally also Docker, follow the links below to get to installation information for these tools: +
 ** http://golang.org/doc/install[Installing Go]. You must install Go 1.4 and NOT use $HOME/go directory for Go installation.
 ** http://git-scm.com/book/en/v2/Getting-Started-Installing-Git[Installing Git]
-** https://docs.docker.com/installation/#installation[Installing Docker]. NOTE: OpenShift now requires at least Docker 1.6. RPMs for CentOS 7 are not yet available in the default yum repositories. If you're running CentOS, please see the link:README.md#docker-16[README] for information on where to get Docker 1.6 RPMs for your platform.
+** https://docs.docker.com/installation/[Installing Docker]. NOTE: OpenShift requires Docker 1.6 or higher or 1.6.2 on CentOS/RHEL.
 2. Next, create a Go workspace directory: +
 +
 ----
@@ -67,9 +67,9 @@ export PATH=$PATH:$GOPATH/bin
 
 5.  From here, you can generate the OpenShift binaries by running:
 
-        $ make clean run
+        $ make clean build
 
-6.  Next, assuming you have installed Docker 1.3.2 or higher, and that you have not changed the kubernetes/openshift service subnet configuration from the default value of 172.30.0.0/16, you need to instruct the Docker daemon to trust any Docker registry on the 172.30.0.0/16 subnet.  If you are running Docker as a service via `systemd`, add the `--insecure-registry 172.30.0.0/16` argument to the options value in `/etc/sysconfig/docker` and restart the Docker daemon.  Otherwise, add "--insecure-registry 172.30.0.0/16" to the Docker daemon invocation, eg:
+6.  Next, assuming you have not changed the kubernetes/openshift service subnet configuration from the default value of 172.30.0.0/16, you need to instruct the Docker daemon to trust any Docker registry on the 172.30.0.0/16 subnet.  If you are running Docker as a service via `systemd`, add the `--insecure-registry 172.30.0.0/16` argument to the options value in `/etc/sysconfig/docker` and restart the Docker daemon.  Otherwise, add "--insecure-registry 172.30.0.0/16" to the Docker daemon invocation, eg:
 
         $ docker -d --insecure-registry 172.30.0.0/16
 
@@ -94,9 +94,9 @@ export PATH=$PATH:$GOPATH/bin
 
 11.  If it is not there already, add the current directory to the $PATH, so you can leverage the OpenShift commands elsewhere.
 
-12.  You are now ready to edit the OpenShift source, rebuild / restart OpenShift, and test your changes.
+12.  You are now ready to edit the source, rebuild and restart OpenShift to test your changes.
 
-13.  NOTE:  to properly stop OpenShift and clean up so you can restart OpenShift, execute:
+13.  NOTE:  to properly stop OpenShift and clean up, so that you can start fresh instance of OpenShift, execute:
 
         $ sudo killall openshift
         $ docker ps | awk 'index($NF,"k8s_")==1 { print $1 }' | xargs -l -r docker stop
@@ -132,15 +132,32 @@ To facilitate rapid development we've put together a Vagrantfile you can use to
 6.  Run a build in SSH:
 
         $ cd /data/src/github.com/openshift/origin
-        $ make build
+        $ make clean build
 
-7.  Start an OpenShift all-in-one server in SSH (includes everything you need to try OpenShift)
+7.  Now change into the directory with the OpenShift binaries, and start the OpenShift server:
 
-        $ sudo systemctl start openshift
+        $ cd _output/local/go/bin
+        $ sudo ./openshift start --public-master=localhost &> logs/openshift.log &
+
++
+NOTE: when using vagrant synced folder (by default your origin directory is mounted using synced folder into `/data/src/github.com/openshift/origin`) it is advised to use a different directory for volume storage than the one in the synced folder. This can be achieved by passing `--volume-dir=/absolute/path` to `openshift start` command.
 
 8.  On your host system, try browsing to: https://localhost:8443/console
 
-9.  From here, you can follow https://github.com/openshift/origin/#start-developing[Start Developing] from the README.
+9.  Deploy the private docker registry within OpenShift with the following commands (note, the --credentials option allows secure communication between the internal OpenShift Docker registry and the OpenShift server, and the --config option provides your identity (in this case, cluster-admin) to the OpenShift server):
+
+        $ sudo chmod +r openshift.local.config/master/openshift-registry.kubeconfig
+        $ sudo chmod +r openshift.local.config/master/admin.kubeconfig
+        $ oadm registry --create --credentials=openshift.local.config/master/openshift-registry.kubeconfig --config=openshift.local.config/master/admin.kubeconfig
+
+10.  You are now ready to edit the source, rebuild and restart OpenShift to test your changes.
+
+11.  NOTE:  to properly stop OpenShift and clean up, so that you can start fresh instance of OpenShift, execute:
+
+        $ sudo killall openshift
+        $ docker ps | awk 'index($NF,"k8s_")==1 { print $1 }' | xargs -l -r docker stop
+        $ mount | grep "openshift.local.volumes" | awk '{ print $3}' | xargs -l -r sudo umount
+        $ cd <to the dir you ran openshift start> ; sudo rm -rf openshift.local.*
 
 TIP: To ensure you get the latest image.  First run `vagrant box remove fedora_inst` and `vagrant box remove fedora_deps`.
 

README.md

@@ -78,7 +78,7 @@ Once the container is started, you can jump into a console inside the container
     # See everything you just created!
     $ oc status
 
-Any username and password are accepted by default (with no credential system configured).  You can view the webconsole at https://localhost:8443/ in your browser - login with the same credentials you used above and you'll see the application you just created.
+Any username and password are accepted by default (with no credential system configured).  You can view the webconsole at [https://localhost:8443/console](https://localhost:8443/console) in your browser - login with the same credentials you used above and you'll see the application you just created.
 
 ![Web console overview](docs/screenshots/console_overview.png?raw=true)
 

docs/debugging-openshift.md

@@ -18,7 +18,7 @@ System Environment
         $ systemctl restart firewalld
 
     Alternatively you can disable it via:
-    
+
         $ systemctl stop firewalld
 
 1. Setup your host DNS to an address that the containers can reach
@@ -31,7 +31,7 @@ System Environment
         $ iptables-save > /path/to/iptables.bkp
         $ systemctl restart iptables
         $ iptables-restore < /path/to/iptables.bkp
-  
+
 
 
 Build Failures
@@ -40,7 +40,7 @@ Build Failures
 To investigate a build failure, first check the build logs.  You can view the build logs via
 
     $ oc build-logs [build_id]
-        
+
 and you can get the build id via:
 
     $ oc get builds
@@ -54,7 +54,7 @@ If you're unable to retrieve the logs in this way, you can also get them directl
 The most recent container in that list should be the one that ran your build.  The container id is the first column.  You can then run:
 
     $ docker logs [container id]
-        
+
 Hopefully the logs will provide some indication of what it failed (e.g. failure to find the source repository, an actual build issue, failure to push the resulting image to the docker registry, etc).
 
 One issue seen somewhat often is not being able to resolve any hostname (for example github.com) from within running containers.  If this shows up in your build logs, restart docker and then resubmit a build:
@@ -105,24 +105,41 @@ There are a number of suspicious looking messages that appear in the openshift l
 
         E1125 14:51:49.665095 04523 endpoints_controller.go:74] Failed to find an IP for pod: {{ } {7e5769d2-74dc-11e4-bc62-3c970e3bf0b7 default /api/v1beta1/pods/7e5769d2-74dc-11e4-bc62-3c970e3bf0b7  41 2014-11-25 14:51:48 -0500 EST map[template:ruby-helloworld-sample deployment:database-1 deploymentconfig:database name:database] map[]} {{v1beta1 7e5769d2-74dc-11e4-bc62-3c970e3bf0b7 7e5769d2-74dc-11e4-bc62-3c970e3bf0b7 [] [{ruby-helloworld-database mysql []  [{ 0 3306 TCP }] [{MYSQL_ROOT_PASSWORD rrKAcyW6} {MYSQL_DATABASE root}] 0 0 [] <nil> <nil>  false }] {0x1654910 <nil> <nil>}} Running localhost.localdomain   map[]} {{   [] [] {<nil> <nil> <nil>}} Pending localhost.localdomain   map[]} map[]}
 
-1. Proxy connection reset 
+1. Proxy connection reset
 
         E1125 14:52:36.605423 04523 proxier.go:131] I/O error: read tcp 10.192.208.170:57472: connection reset by peer
 
 1. No network settings
 
         W1125 14:53:10.035539 04523 rest.go:231] No network settings: api.ContainerStatus{State:api.ContainerState{Waiting:(*api.ContainerStateWaiting)(0xc208b29b40), Running:(*api.ContainerStateRunning)(nil), Termination:(*api.ContainerStateTerminated)(nil)}, RestartCount:0, PodIP:"", Image:"kubernetes/pause:latest"}
 
+
+Vagrant synced folder
+----------------
+
+When using [vagrant synced folder](http://docs.vagrantup.com/v2/synced-folders/), (by default your
+origin directory is mounted using synced folder into `/data/src/github.com/openshift/origin`) you may encounter
+following errors in OpenShift log:
+
+        E0706 11:29:43.421460    3664 empty_dir.go:322] Expected directory "/data/src/github.com/openshift/origin/openshift.local.volumes/pods/4c390e43-23d2-11e5-b42d-080027c5bfa9/volumes/kubernetes.io~secret/deployer-token-f9mi7" permissions to be: -rwxrwxrwx; got: -rwxrwxr-x
+        E0706 11:29:43.421741    3664 kubelet.go:1114] Unable to mount volumes for pod "docker-registry-1-deploy_default": operation not supported; skipping pod
+        E0706 11:29:43.438449    3664 pod_workers.go:108] Error syncing pod 4c390e43-23d2-11e5-b42d-080027c5bfa9, skipping: operation not supported
+
+This will happen when using our provided Vagrantfile to develop OpenShift with vagrant. One of the reasons
+is that you can't use ACLs on shared directories. The solution to this problem is to use a different directory
+for volume storage than the one in synced folder. This can be achieved by passing `--volume-dir=/absolute/path` to `openshift start` command.
+
+
 Must Gather
 -----------
 If you find yourself still stuck, before seeking help in #openshift on freenode.net, please recreate your issue with verbose logging and gather the following:
 
 1. OpenShift logs at level 4 (verbose logging):
 
         $ openshift start --loglevel=4 &> /tmp/openshift.log
-        
-1. Container logs  
-    
+
+1. Container logs
+
     The following bit of scripting will pull logs for **all** containers that have been run on your system.  This might be excessive if you don't keep a clean history, so consider manually grabbing logs for the relevant containers instead:
 
         for container in $(docker ps -aq); do

examples/sample-app/README.md

@@ -121,6 +121,8 @@ This section covers how to perform all the steps of building, deploying, and upd
 
     Note: sudo is required so the kubernetes proxy can manipulate iptables rules to expose service ports.
 
+    Note: when using vagrant synced folder it is advised to use a different directory for volume storage than the one in the synced folder. This can be achieved by passing `--volume-dir=/absolute/path` to `openshift start` command.
+
 
 3. Set up your client to reach the OpenShift master now running.
 
@@ -350,7 +352,7 @@ the ip address shown below with the correct one for your environment.
 
             $ sudo chmod +r openshift.local.config/master/openshift-router.kubeconfig
             $ oadm router --create --credentials=openshift.local.config/master/openshift-router.kubeconfig --config=openshift.local.config/master/admin.kubeconfig
-              router # the service 
+              router # the service
               router # the deployment config