diff --git a/README.md b/README.md
index 9d55acec3..e614ca993 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,119 @@
 # postgres operator prototype (WIP)
 
-### Create minikube
+Postgres operator manages Postgres clustes in Kubernetes using the [operator pattern](https://coreos.com/blog/introducing-operators.html)
+During the initial run it registers the [third-party-resource (TPR)](https://kubernetes.io/docs/user-guide/thirdpartyresources/) for Postgres.
+The Postgres TPR is essentially a schema that describes the contents of the manifests for deploying individual clusters.
 
-    $ minikube start
+One the operator is running, it performs the following actions:
 
-### Deploy etcd
+* watches for new cluster postgres manifests and deploys corresponding clusters.
+* watches for updates to existing manifests and changes corresponding properties of the running clusters.
+* watches for deletes of the existing manifests and deletes corresponding database clusters.
+* watches for updates to the operator definition itself and changes the running clusters when necessary.
+* checks running clusters against the manifests and acts on the differences found.
 
-    $ kubectl create -f https://raw.githubusercontent.com/coreos/etcd/master/hack/kubernetes-deploy/etcd.yml
+For instance, when the user creates a new custom object of type postgresql by submitting a new manifest with kubectl, the operator fetches that object and creates the corresponding kubernetes structures (statefulsets, services, secrets) according to its definition.
 
-##  Set your go path and put the sources so that go build finds them
+Another example is changing the docker image inside the operator. In this case, the operator first goes to all statefulsets
+it manages and updates them with the new docker images; afterwards, all pods from each statefulset are killed one by one
+(rolling upgrade) and the replacements are spawned automatically by the statefulsets with the new docker image.
 
-    $ export GOPATH=~/git/go
+## Setting up Go.
+
+Postgres operator is written in Go. Use the [installation instructions](https://golang.org/doc/install#install) if you don't have Go on your system.
+You won't be able to compile the operator with Go older than 1.7. We recommend installing [the latest one](https://golang.org/dl/).
+
+Go projects expect their source code and all the dependencies to be located under the [GOPATH](https://github.com/golang/go/wiki/GOPATH).
+Normally, one would use a single GOPATH, by creating a directory (i.e. ~/go) and placing the source code under the ~/go/src subdirectories.
+
+Given the schema above, the postgres operator source code located at `github.bus.zalan.do/acid/postgres-operator` should be put at
+`~/go/src/github.bus.zalan.do/acid/postgres-operator`.
+
+    $ export GOPATH=~/go
     $ mkdir -p ${GOPATH}/src/github.bus.zalan.do/acid/
-    $ cd ${GOPATH}/src/github.bus.zalan.do/acid/ && git clone https://github.bus.zalan.do/acid/postgres-operator -b prototype
+    $ cd ${GOPATH}/src/github.bus.zalan.do/acid/ && git clone git@github.bus.zalan.do:acid/postgres-operator.git
 
-### Install Glide and Staticcheck
 
-    $ make tools 
+## Building the operator
 
-### Install dependencies with Glide
+You need Glide to fetch all dependencies. Install it with:
+
+    $ make tools
+
+Next, install dependencies with glide by issuing:
 
     $ make deps
 
-### Build dependencies
+This would take a while to complete. You have to redo `make deps` every time you dependencies list changes, i.e. after adding a new library dependency.
 
-    $ go build -i -v cmd
+Build the operator docker image and pushing it to pierone:
 
-## Run operator (as a pod)
+    $ make docker push
 
-    $ docker build -t postgres-operator:0.1 .
-    $ kubectl create -f postgres-operator.yaml
+You may define the TAG variable to assign an explicit tag to your docker image and the IMAGE to set the image name.
+By default, the tag is computed with `git describe --tags --always --dirty` and the image is `pierone.example.com/acid/postgres-operator`
 
-    If you are building docker image by yourself on OS X make sure postgres-operator is compiled with GOOS=linux flag
+Building the operator binary (for testing the out-of-cluster option):
+
+    $ make
+
+The binary will be placed into the build directory.
+
+## Testing the operator
+
+The best way to test the operator is to run it in minikube. Minikube is a tool to run Kubernetes cluster locally.
+
+### Installing and starting minikube
+
+See [minikube installation guide](https://github.com/kubernetes/minikube/releases)
+
+After the installation, issue the
+
+    $ minikube start
+
+Note: if you are running on a Mac, make sure to use the [xhyve driver](https://github.com/kubernetes/minikube/blob/master/DRIVERS.md#xhyve-driver)
+instead of the default docker-machine one for performance reasons.
+
+One you have it started successfully, use [the quickstart guide](https://github.com/kubernetes/minikube#quickstart) in order
+to test your that your setup is working.
+
+Note: if you use multiple kubernetes clusters, you can switch to minikube with `kubectl config use-context minikube`
+
+
+### Deploying the operator
+
+
+Before the operator is deployed, you need to tell your minikube cluster the OAuth2 secret token in order to communicate
+with the teams API. For a Live Zalando cluster, the token is populated in a secret described by `manifests/platform-credentials.yaml`
+via the infrastructure created by the Teapot team. The operator expects that secret (with the name set by the `oauth_token_secret_name
+variable to be present). That token is not present in minikube, but one can copy it from the production cluster:
+
+    $ zkubectl --context kube_db_zalan_do get secret postgresql-operator -o yaml| kubectl --context minikube create -f -  
+
+Note that the token normally expires after ~ 30 minutes, therefore, you should fetch the new one(and delete the old one):
+
+    $ kubectl --context minikube delete secret postgresql-operator
+    $ zkubectl --context kube_db_zalan_do get secret postgresql-operator -o yaml| kubectl --context minikube create -f -
+
+The fastest way to run your docker image locally is to reuse the docker from minikube. That way, there is no need to
+pull docker images from pierone or push them, as the image is essentially there once you build it. The following steps
+will get you the docker image built and deployed.
+
+    $ eval $(minikube docker-env)
+    $ export TAG=$(git describe --tags --always --dirty)
+    $ make docker
+    $ sed -e "s/\(image\:.*\:\).*$/\1$TAG/" -e "/serviceAccountName/d" manifests/postgres-operator.yaml|kubectl create  -f -
     
+The last line changes the docker image tag in the maniest to the one the operator image has been built with and removes
+the serviceAccountName definition, as the service account is not defined in minikube (neither it should, as one has admin
+permissions there).
+
+### Deploy etcd
+
+Etcd is required to deploy the operator.
+
+    $ kubectl create -f https://raw.githubusercontent.com/coreos/etcd/master/hack/kubernetes-deploy/etcd.yml
+
 ### Check if ThirdPartyResource has been registered
 
     $ kubectl get thirdpartyresources