ph-ee: detailed instructions for ph-ee-env-template and ph-ee-env-labs

payment-hub-ee/overview/installation-instructions.md

@@ -36,13 +36,62 @@ Depending on the actual configuration, the payment hub's Helm chart installs the
   * Kibana
   * Zeebe Operate monitoring UI
 
+Each of these components has a git repository in [https://github.com/orgs/openMF/repositories?q=ph-ee](https://github.com/orgs/openMF/repositories?q=ph-ee), containing source code and Dockerfiles.
+
+Each component will contain a Jenkinsfile containing tasks related to deployment. Refer to this to understand the build steps of each project.
+
+Most components will also have a Dockerfile. After building the image, you may wish to host these docker images in a local docker registry. This can be done using docker locally per [https://docs.docker.com/registry/deploying/](https://docs.docker.com/registry/deploying/), once you make sure that whatever domain name you use is available via DNS, or a local entry in /etc/hosts. This will mean replacing the images at 'paymenthubee.azurecr.io' in ph-ee-env-template with your own images.
+
+For ph-ee-connector-common, a dependency of several of the connector components, you must build and install to a maven repository.
+
+```bash
+mvn deploy install
+```
+
 Certainly all these components have various Kubernetes objects \(ReplicationSets, Services, Ingresses, etc\). The Helm chart wraps all this complexity into a single package and allows a single-command deployment, as we will see very soon.
 
 ## First deployment
 
+For the first deployment attempt, we suggest taking one of the 3 Lab Environments for a test-drive.
+
+### ph-ee-engine
+
+The `ph-ee-engine` dependency is defined in [https://github.com/openMF/ph-ee-env-template](https://github.com/openMF/ph-ee-env-template)
+
+The lab environments depend on this component, and are configured to pull this from `http://jenkins.mifos.io:8082`. This can be operated locally by installing a custom host entry in your local hosts file (/etc/hosts on linux), and installing a local web server to serve the files.
+
+A sample nginx vhost file is provided:
+
+```
+server {
+        listen 8082;
+        listen [::]:8082;
+
+        root /var/www/jenkinsmifos-helm;
+
+        index index.html index.htm index.nginx-debian.html;
+
+        server_name _;
+
+        location / {
+                try_files $uri $uri/ =404;
+        }
+}
+```
+
+Add these two entries to your /etc/hosts file. `x.x.x.x` should be replaced with your network IP - as some kubernetes environments run inside a VM, they need a network reachable IP to connect to. Only specifying `127.0.0.1` would make that VM try to connect to itself, not the host which provides the charts.
+```
+127.0.0.1 jenkins.mifos.io
+x.x.x.x jenkins.mifos.io
+```
+
+Inspect [https://github.com/openMF/ph-ee-env-template/blob/master/helm/package.sh](https://github.com/openMF/ph-ee-env-template/blob/master/helm/package.sh) for build instructions, and customize the commands to suit your installation. Unless you are remotely pushing the files, you will not need to run scp. Only cp is needed in that case, however please ensure the web root directory (/usr/share/nginx/html) is updated to reflect your configuration. If using the nginx file above, it would be `/var/www/jenkinsmifos-helm`.
+
+Verify your results by doing `curl http://jenkins.mifos.io:8082/index.yaml` to download your index.yaml. If problems occur, check your web server logs.
+
 ### Deploying the Helm chart
 
-For the first deployment attempt, we suggest taking one of the 3 Lab Environments for a test-drive. Deploying any of there is as simple as cloning the Labs repository, changing directory to eg. [https://github.com/openMF/ph-ee-env-labs/tree/master/helm/payment-hub-med](https://github.com/openMF/ph-ee-env-labs/tree/master/helm/payment-hub-med) and executing the command `helm install <release-name> .`, where release name is freely chosen, eg. `ph-ee-med`, in this case.
+Deploying any of there is as simple as cloning the Labs repository, changing directory to eg. [https://github.com/openMF/ph-ee-env-labs/tree/master/helm/payment-hub-med](https://github.com/openMF/ph-ee-env-labs/tree/master/helm/payment-hub-med), installing the dependencies with `helm dep up`, and executing the command `helm install <release-name> .`, where release name is freely chosen, eg. `ph-ee-med`, in this case.
 
 Upgrading an installation with changed or updated configuration parameters is possible with executing the command `helm upgrade <release-name>`.
 
@@ -56,10 +105,11 @@ tenants=([bb-dfsp]="tn03 tn04" [med-dfsp]="tn05 tn06" [large-dfsp]="tn01 tn02")
 PREV="DFSPID"
 for lab in large-dfsp; do 
     echo "using env $lab"
-  kubectx $lab
-  svc=`kubectl get pods | grep zeebe-zeebe-gateway | awk '{ print $1 }'`
-  kubectl port-forward $svc 26500:26500 &
-  sleep 1
+    kubectx $lab
+    svc=`kubectl get pods | grep zeebe-zeebe-gateway | awk '{ print $1 }'`
+    kubectl port-forward $svc 26500:26500 &
+    forward_pid=$!
+    sleep 1
     for tenant in ${tenants[$lab]}; do 
         for bpmn in ./orchestration/feel/*.bpmn; do
             echo "processing bpmn: $(basename $bpmn) tenant: ${tenant} currently_replacing: ${PREV}"
@@ -73,7 +123,7 @@ for lab in large-dfsp; do
     done
     PREV=${tenants[$lab]:5:4}
     echo "--- DONE environment ${lab} ---"
-    killall kubectl
+    kill -9 $forward_pid
 done
 ```