Merge pull request #88 from stakater/update-for-developers-to-divio

[for-developers] update docs to divio

content/for-developers/how-to-guides/add-a-new-environment-to-apps-gitops/add-a-new-environment-to-application.md

@@ -2,15 +2,17 @@
 
 Lets see how can we add an environment to an application in a tenant. Lets say, we have added a production cluster and want to add a new environment in application for it to be deployed on production.
 
-Objectives:
+## Objectives
 
 - Deploy your application to a new environment
 
-Key Results:
+## Key Results
 
 - ArgoCD apps pointing to application environment created
 - Helm chart with production configuration deployed
 
+## Guide
+
 1. Create a folder named `production` at `<tenant-name>/<app-name>` which corresponds to the production environment. Suppose `gabbar` as tenant name, `stakater-nordmart-review` as application name, `production` as cluster name, `prod` as environment name.
 
    ```bash

content/for-developers/how-to-guides/build-and-push-your-image/build-and-push-your-image.md

@@ -0,0 +1,70 @@
+# Build and Push your Image to Nexus
+
+## Objectives
+
+- Push artifacts to Nexus Registry hosted on Stakater App Agility Platform (SAAP).
+
+## Key Results
+
+- Image built and pushed to image repository
+
+## Guide
+
+### Build the Image
+
+1. Run the following command to build the image.
+
+    ```sh
+    buildah bud --format=docker --tls-verify=false --no-cache-f ./Dockerfile -t <nexus-docker-reg-url>/<app-name>:1.0.0 .
+    ```
+
+1. Run the following command to run the image.
+
+    ```sh
+    # -p flag exposes container port 8080 on your local port8080
+    buildah run <nexus-docker-reg-url>/<app-name>:1.0.0 .
+    ```
+
+### Login to Image Registry
+
+1. Find the Image registry URL [here](../../../managed-addons/nexus/routes.md) or Navigate to the cluster Forecastle, search `nexus` using the search bar on top menu and copy the nexus url.
+
+    - `nexus-docker-reg-url`: Remove `https://` from the start and add `-docker` in URL after `nexus`. This URL points to Docker Registry referred as `nexus-docker-reg-url` in this tutorial for example `nexus-docker-stakater-nexus.apps.clustername.random123string.kubeapp.cloud`.
+
+1. Run following command to log into the registry.
+    > Make sure to get credentials from Stakater Admin.
+
+    ```sh
+    buildah login <nexus-docker-reg-url>
+    ```
+
+### Push Docker Image to Nexus
+
+1. Replace the placeholders and Run the following command inside application folder.
+
+    ```sh
+    # Buldah Bud Info : https://manpages.ubuntu.com/manpages/impish/man1/buildah-bud.1.html
+    buildah bud --format=docker --tls-verify=false --no-cache -f ./Dockerfile -t <nexus-docker-reg-url>/<app-name>:1.0.0 .
+    ```
+
+1. Lets push the image to nexus docker repo.
+
+    ```sh
+    # Buildah push Info https://manpages.ubuntu.com/manpages/impish/man1/buildah-push.1.html
+    buildah push <nexus-docker-reg-url>/<app-name>:1.0.0 docker://<nexus-docker-reg-url>/<tenant-name>/<app-name>:1.0.0
+    ```
+
+### Verify Image Available
+
+1. Open Nexus UI from Forecastle. Upon opening the link, you'll be redirected to Nexus home page.
+
+   ![`nexus-Forecastle`](../images/nexus-forecastle.png)
+   ![`nexus-homepage`](../images/nexus-homepage.png)
+
+1. Select `Browse` from the left sidebar, Click on `docker` to view your Container Image Registry.
+
+   ![`nexus-browse-docker`](../images/nexus-browse-docker.png)
+
+1. Verify that the image you pushed is present in the list.
+
+    ![`nexus-container-image`](../images/nexus-container-image.png)

content/for-developers/how-to-guides/deploy-app-with-argocd-and-helm/deploy-app-with-argocd-and-helm.md

@@ -0,0 +1,115 @@
+
+# Deploy Application with ArgoCD and Helm
+
+We will cover application deployment with Helm and ArgoCD in this section.
+
+## Deploy your Application with Helm
+
+Let's deploy a simple application using Helm. Helm charts are packaged and stored in repositories. They can be added as dependencies of other charts or used directly. Let's add a chart repository now. The chart repository stores the version history of our charts as well as the packaged tar file.
+
+We created and packaged a Helm chart to the Nexus Helm Repository available in Stakater App Agility Platform (SAAP)
+
+1. From your Terminal, add the Nexus Helm Repository using the following command. Consider the
+
+    ```bash
+    helm repo add NEXUS_HELM_REPO_NAME NEXUS_HELM_REPO_URL
+    ```
+
+1. Install a chart from this repo. Start by searching the repository to see what is available.
+
+    ```bash
+    helm search repo stakater-nordmart-review
+    ```
+
+1. Now install the latest version. Helm likes to give each install its own release.
+
+    ```bash
+    helm install RELEASE_NAME NEXUS_HELM_REPO_NAME/takater-nordmart-review --namespace ${TENANT_NAME}-dev
+    ```
+
+1. Open the application up in the browser to verify it's up and running. Here's a handy one-liner to get the URL of the app.
+
+    ```bash
+    oc project ${TENANT_NAME}-dev
+    oc get pods,svc -n ${TENANT_NAME}-dev
+    ```
+
+1. Run the following command to port forward the pod to your local machine and run curl command to verify your application is running and serving requests.
+
+     ```sh
+     # get podname with oc get
+     oc port-forward <podname> 8080:8080
+     curl localhost:8080/api/review/329199
+     ```
+
+1. You can upgrade your chart values with CLI. By default, your application has only 1 replica. You can view this using the following command.
+
+     ```bash#test
+     oc get pods -n ${TENANT_NAME}-dev
+     ```
+
+    By default, there is one replica of your application. Let's use Helm to set this to 5.
+
+    ```bash#test
+    helm upgrade RELEASE_NAME NEXUS_HELM_REPO_NAME/APP_NAME --set APP_NAME.deployment.replicas=5 --namespace ${TENANT_NAME}-dev
+    ```
+
+    Verify the deployment has scaled up to 5 replicas.
+
+    ```bash#test
+    oc get pods -n ${TENANT_NAME}-dev
+    ```
+
+1. If you're done playing with the `Nordmart Review API`. You can tidy up your work by removing the chart. To do this, run `helm uninstall` to remove your release of the chart.
+
+    ```bash#test
+    helm uninstall stakater-nord -namespace ${TENANT_NAME}-dev
+    ```
+
+    Verify the cleanup.
+
+    ```bash#test
+    oc get pods -n ${TENANT_NAME}-dev
+    ```
+
+## Deploy your Application with ArgoCD
+
+1. Log into ArgoCD UI.
+
+1. Lets deploy a sample application through the UI. In fact, let's get ArgoCD to deploy the `stakater-nordmart-review` app you manually deployed previously using Helm. On ArgoCD - click `+ NEW APP`. You should see an empty form. Let's fill it out by setting the following:
+
+      - On the **GENERAL** box
+
+         - Application Name: `<TENANT_NAME>-nordmart-review`
+         - Project: `<TENANT_NAME>` (select the project corresponding to your `<TENANT_NAME>` from the `project` dropdown)
+         - Sync Policy: `Automatic`
+
+      - On the **SOURCE** box
+
+         - Repository URL: `NEXUS_HELM_REGISTRY_URL`
+         - Select `Helm` from the right dropdown menu
+         - Chart: `stakater-nordmart-review`
+         - Version: `1.0.0`
+
+      - On the **DESTINATION** box
+
+         - Cluster URL: `https://kubernetes.default.svc`
+         - Namespace: `<TENANT_NAME>-test`
+
+    Your form should look like the follow image, if so click `Create`
+
+1. After you hit `Create`, you'll see `<TENANT_NAME>-nordmart-review` application is created and should start deploying in your `<TENANT_NAME>-test` namespace.
+
+1. If you drill down into the application you will get ArgoCD's amazing view of all k8s resources that were generated by the chart
+
+1. You can verify the application is running and behaving as expected by navigating to `Workloads` > `Pods` section in the `<TENANT_NAME-test` namespace in your `OpenShift Console`.
+
+      > Select the dropdown menu and switch to `Administrator` view in the OpenShift console if you are not already there
+
+1. Run the following command to port forward the pod to your local machine and run curl command to verify your application is running and serving requests.
+
+     ```sh
+     # get podname with oc get
+     oc port-forward <podname> 8080:8080
+     curl localhost:8080/api/review/329199
+     ```

content/for-developers/how-to-guides/package-and-push-your-chart/package-and-push-your-chart.md

@@ -0,0 +1,57 @@
+# Package and push your chart to Nexus
+
+## Objectives
+
+- Push artifacts to Nexus Registry hosted on Stakater App Agility Platform (SAAP).
+
+## Key Results
+
+- Helm chart package and pushed to Nexus.
+
+## Guide
+
+### Get Nexus Helm Registry URL
+
+## Docker Image and Helm Chart Repository hosted by Nexus
+
+> Ask admin Helm Registry Credentials for helm chart repository.
+
+Find Nexus Helm Registry URL [here](../../../managed-addons/nexus/routes.md).
+
+Alternatively, Navigate to the cluster Forecastle, search `nexus` using the search bar on top menu and copy the nexus url.
+
+- `nexus-helm-reg-url` : Add `-helm` in URL after `nexus` and append `/repository/helm-charts/`. This URL points to Helm Registry referred as `nexus-helm-reg-url` in this tutorial for example `https://nexus-helm-stakater-nexus.apps.clustername.random123string.kubeapp.cloud/repository/helm-charts/`
+
+  ![nexus-Forecastle](../images/nexus-forecastle.png)
+
+### Package and Upload the chart to Nexus
+
+1. Run the following command to package the helm chart into compressed file.
+
+   ```sh
+   # helm package [CHART_PATH]
+   helm package .
+   ```
+
+   This command packages a chart into a versioned chart archive file.
+
+1. Upload packaged chart to Nexus Helm Registry.
+
+   ```sh
+   curl -u "<helm_user>":"<helm_password>" `nexus-helm-reg-url` --upload-file "CHART_NAME-CHART_VERSION.tgz"
+   ```
+
+   > Make sure to get credentials from Stakater Admin.
+
+1. Open Nexus UI from Forecastle. Upon opening the link, you'll be redirected to Nexus home page.
+
+   ![`nexus-Forecastle`](../images/nexus-forecastle.png)
+   ![`nexus-homepage`](../images/nexus-homepage.png)
+
+1. Select `Browse` from the left sidebar, Click on `Helm Charts` to view your Helm Registry Charts.
+
+   ![`nexus-browse-helm`](../images/nexus-browse-helm.png)
+
+1. Verify that the chart you uploaded is present in the list.
+
+    ![`nexus-helm-charts`](../images/nexus-helm-charts.png)

content/for-developers/tutorials/inner-loop/00-prepare-environment/prepare-env.md

@@ -1 +1,31 @@
 # Prepare local environment
+
+## Objectives
+
+Enable developers to start developing and testing applications on test clusters.
+
+## Key Results
+
+- Install the CLIs required for interacting with cluster
+
+## PreRequisites
+
+- Working laptop or desktop computer with functional Operating System.
+
+## Tutorial
+
+### Setting up CLI
+
+Following CLI tools are required for working with Stakater App Agility Platform.
+
+- [OpenShift CLI (oc)](https://docs.openshift.com/container-platform/4.12/cli_reference/openshift_cli/getting-started-cli.html#installing-openshift-cli) With the OpenShift command-line interface (CLI), the oc command, you can create applications and manage OpenShift Container Platform projects from a terminal.
+
+- [kubectl](https://kubernetes.io/docs/tasks/tools/) The Kubernetes command-line tool, kubectl, allows you to run commands against Kubernetes clusters. You can use kubectl to deploy applications, inspect and manage cluster resources, and view logs.
+
+- [helm](https://helm.sh/docs/intro/install/) helm helps you manage Kubernetes applications — Helm Charts help you define, install, and upgrade even the most complex Kubernetes application.
+
+- [docker](https://docs.docker.com/get-docker/) Docker is an open platform for developing, shipping, and running applications. Docker enables you to separate your applications from your infrastructure, so you can deliver software quickly. With Docker, you can manage your infrastructure in the same ways you manage your applications.
+
+- [buildah](https://github.com/containers/buildah/blob/main/install.md) buildah is an open source, Linux-based tool that can build Docker- and Kubernetes-compatible images, and is easy to incorporate into scripts and build pipelines. It runs without a container runtime or daemon compared to docker.
+
+- [tilt](https://docs.tilt.dev/install.html) Tilt powers microservice development and makes sure they behave! Run tilt up to work in a complete dev environment configured for your team. Tilt automates all the steps from a code change to a new process: watching files, building container images, and bringing your environment up-to-date. Think docker build && kubectl apply or docker-compose up.

content/for-developers/tutorials/inner-loop/02-containerize-app/containerize-app.md → content/for-developers/tutorials/inner-loop/01-containerize-app/containerize-app.md

@@ -1,18 +1,23 @@
 # Containerize the Application
 
-Prerequisites:
+Running workloads in Kubernetes/OpenShift requires the application to be containerized. Typically, this includes taking a relevant base image, installing application dependencies if not available, copying & building the code and command to run your application executed at runtime.
 
-- Developed application.
-- docker cli.
-- Application is part of tenant.
+## Objectives
 
-Running workloads in Kubernetes/OpenShift requires the application to be containerized. Typically, this includes taking a relevant base image, installing application dependencies if not available, copying & building the code and command to run your application executed at runtime.
+- Containerize your application for deployment on Stakater App Agility Platform (SAAP).
+
+## Key Results
 
-Consider the [`stakater-nordmart-review`](https://github.com/stakater-lab/stakater-nordmart-review) application we discussed in the previous section.
+- Dockerfile created.
+- Image built and pushed to image repository
+
+## Tutorials
+
+Consider the [`stakater-nordmart-review-api`](https://github.com/stakater-lab/stakater-nordmart-review-api) application.
 
 ```sh
-git clone https://github.com/stakater-lab/stakater-nordmart-review-ui
-cd stakter-nordmart-review-ui
+git clone https://github.com/stakater-lab/stakater-nordmart-review-api
+cd stakter-nordmart-review-api
 ```
 
 Lets create a Dockerfile inside the repository folder and delete any existing file.
@@ -75,15 +80,15 @@ Lets create a Dockerfile inside the repository folder and delete any existing fi
   1. Run the following command to build the image.
 
         ```sh
-        buildah bud --format=docker --tls-verify=false --no-cache -f ./Dockerfile -t <nexus-docker-reg-url>/<tenant-name>/<app-name>:1.0.0 .
+        buildah bud --format=docker --tls-verify=false --no-cache -f ./Dockerfile -t <app-name>:1.0.0 .
 
         ```
 
   1. Run the following command to run the image.
 
         ```sh
         # -p flag exposes container port 8080 on your local port 8080
-        buildah run <nexus-docker-reg-url>/<tenant-name>/<app-name>:1.0.0 .
+        buildah run <app-name>:1.0.0 .
         ```
 
   1. Run a curl command to verify that image is running.
@@ -99,35 +104,3 @@ Read the following articles for more information:
 - [Containerize Your Application With Docker](https://towardsdatascience.com/containerize-your-application-with-docker-b0608557441f)
 - [Dockerizing a Node.js web app](https://nodejs.org/en/docs/guides/nodejs-docker-webapp)
 - [Dockerizing a Django app](https://blog.logrocket.com/dockerizing-django-app)
-
-## Login to Image Registry
-
-Find the Image registry URL [here](../../../../managed-addons/nexus/routes.md) or Navigate to the cluster Forecastle, search `nexus` using the search bar on top menu and copy the nexus url.
-
-- `nexus-docker-reg-url`: Remove `https://` from the start and add `-docker` in URL after `nexus`. This URL points to Docker Registry referred as `nexus-docker-reg-url` in this tutorial for example `nexus-docker-stakater-nexus.apps.clustername.random123string.kubeapp.cloud`.
-
-Run following command to log into the registry. Specify admin provided username and password to login.
-
-```sh
-buildah login <nexus-docker-reg-url>
-```
-
-## Push Docker Image to Nexus
-
-Replace the placeholders and Run the following command inside application folder.
-
-```sh
-# Buldah Bud Info : https://manpages.ubuntu.com/manpages/impish/man1/buildah-bud.1.html
-buildah bud --format=docker --tls-verify=false --no-cache -f ./Dockerfile -t <nexus-docker-reg-url>/<tenant-name>/<app-name>:1.0.0 .
-```
-
-Lets push the image to nexus docker repo. Make sure to get credentials from Stakater Admin.
-
-```sh
-# Buildah push Info https://manpages.ubuntu.com/manpages/impish/man1/buildah-push.1.html
-buildah push <nexus-docker-reg-url>/<tenant-name>/stakater-nordmart-review:1.0.0 docker://<nexus-docker-reg-url>/<tenant-name>/stakater-nordmart-review:1.0.0
-```
-
-## Verify Image Available
-
-Login to Nexus and Verify that the image is available on the cluster.