From c6661def314f80582170664333eca6defeb12614 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Robert=20Sch=C3=A4fer?= <git@roschaefer.de>
Date: Thu, 31 Jan 2019 23:52:24 +0100
Subject: [PATCH] Improve README

---
 .gitignore |  2 +-
 README.md  | 78 ++++++++++++++++++++++++++++++++----------------------
 2 files changed, 47 insertions(+), 33 deletions(-)

diff --git a/.gitignore b/.gitignore
index da61c76ef..32cfb3b9e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1 @@
-*secrets*.yaml
+*secrets*.yml
diff --git a/README.md b/README.md
index 48d644622..1c9212c07 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,9 @@
 
 ## Todo`s
 - [ ] check labels and selectors if they all are correct
-- [ ] configure NGINX from yaml
-- [ ] configure Let's Encrypt cert-manager from yaml
-- [ ] configure ingress form yaml
+- [ ] configure NGINX from yml
+- [ ] configure Let's Encrypt cert-manager from yml
+- [ ] configure ingress form yml
 - [ ] configure persistent & shared storage between nodes
 - [ ] reproduce setup locally
 
@@ -17,70 +17,84 @@ There are many Kubernetes distributions, but if you're just getting started, Min
 
 [Install Minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/)
 
+# Open minikube dashboard
+```
+$ minikube dashboard
+```
+This will give you an overview.
+Some of the steps below need some timing to make ressources available to other
+dependent deployments. Keeping an eye on the dashboard is a great way to check
+that.
+
 ## Create a namespace locally
 ```shell
-kubectl create -f namespace-staging.yml
+$ kubectl create -f namespace-staging.yml
 ```
+Switch to the namespace `staging` in your kubernetes dashboard.
 
-## Change config maps according to your needs
+## Setup config maps
 ```shell
-cd config/
-cp db-migration-worker-configmap.template.yaml db-migration-worker-configmap.yaml
+$ cp db-migration-worker.template.yml config/db-migration-worker.yml
 # edit all variables according to the setup of the remote legacy server
-cd ..
-```
 
-## Apply the config map to staging namespace
-```shell
-kubectl apply -f config/
+$ kubectl apply -f config/
 ```
 
 ## Setup secrets and deploy themn
+If you want to edit secrets, you have to `base64` encode them. See [kubernetes
+documentation](https://kubernetes.io/docs/concepts/configuration/secret/#creating-a-secret-manually).
 ```shell
-cp secrets.yaml.template secrets.yaml
-# change all vars as needed and deploy it afterwards
-kubectl apply -f secrets.yaml
+# example how to base64 a string:
+$ echo -n 'admin' | base64
+YWRtaW4=
+
+$ cp secrets.yml.template secrets.yml
+# change all variables as needed and deploy them
+$ kubectl apply -f secrets.yml
 ```
 
-## Create volumes and deployments
+## Create volumes 
 ```shell
-kubectl apply -f volumes/
-kubectl apply -f deployments/
+$ kubectl apply -f volumes/
 ```
-This can take a while.
-Sit back and relax and have a look into your minikube dashboard:
+Wait until the persistent volumes get available.
+
+## Create deployments
+```shell
+$ kubectl apply -f deployments/
 ```
-minikube dashboard
-```
-Wait until all pods turn green and they don't show a warning `Waiting: ContainerCreating` anymore.
+This can take a while because kubernetes will download the docker images.
+Sit back and relax and have a look into your kubernetes dashboard.
+Wait until all pods turn green and they don't show a warning
+`Waiting: ContainerCreating` anymore.
 
 ## Expose the services
 
 ```shell
-kubectl apply -f services/
+$ kubectl apply -f services/
 ```
 
-## Access the service
+## Access the services
 
 ```shell
-minikube service nitro-backend --namespace=staging
-minikube service nitro-web     --namespace=staging
+$ minikube service nitro-backend --namespace=staging
+$ minikube service nitro-web     --namespace=staging
 ```
 
 
-## Provisioning db-migration-worker
+## Provision db-migration-worker
 Copy your private ssh key and the `.known-hosts` file of your remote legacy server.
 ```shell
 
 # check the corresponding db-migration-worker pod
-kubectl --namespace=staging get pods
+$ kubectl --namespace=staging get pods
 # change <POD_ID> below
-kubectl cp path/to/your/ssh/keys/.ssh staging/nitro-db-migration-worker-<POD_ID>:/root/
+$ kubectl cp path/to/your/ssh/keys/.ssh staging/nitro-db-migration-worker-<POD_ID>:/root/
 ```
 
 Run the migration:
 ```shell
 # change <POD_IDs> below
-kubectl --namespace=staging exec -it nitro-db-migration-worker-<POD_ID> ./import.sh
-kubectl --namespace=staging exec -it nitro-neo4j-<POD_ID>               ./import/import.sh
+$ kubectl --namespace=staging exec -it nitro-db-migration-worker-<POD_ID> ./import.sh
+$ kubectl --namespace=staging exec -it nitro-neo4j-<POD_ID>               ./import/import.sh
 ```