Installation, Upgrades and Uninstallation (#1)

* Installation outline initial draft

* added install, upgrade and uninstall steps

* more detailed upgrade instructions

* updated CLI instructions for upgrdes and removal

* fixes after review by Jason F

* updates for v1.0 GA release

.gitignore

@@ -106,3 +106,6 @@ dist
 
 # Local VSCode settings
 .vscode/settings*
+
+# macOS dotfiles
+.DS_Store

antora.yml

@@ -3,5 +3,4 @@ title: Red Hat Developer Hub Administration
 version: 1
 nav:
 - modules/ROOT/nav.adoc
-- modules/chapter1/nav.adoc
-- modules/chapter2/nav.adoc
+- modules/chapter1/nav.adoc

modules/ROOT/pages/index.adoc

@@ -3,4 +3,43 @@
 
 == Introduction
 
-This course covers the installation, updates and uninstallation process for Red Hat Developer Hub (RHDH). You also learn about the basics of configuration in RHDH, and how to configure authentication using a GitHub or GitLab backend along with single sign-on functionality using Keycloak.
+Welcome to this quick course on the _Red Hat Developer Hub Administration_.
+This course is the `second` in a series of `three` courses about Red Hat Developer Hub:
+
+1. https://redhatquickcourses.github.io/devhub-intro[Introduction to Red Hat Developer Hub^]
+2. Red Hat Developer Hub Administration  (_This course_)
+3. Building Developer Portals with Red Hat Developer Hub (Under Development)
+
+This course covers the installation, updates and uninstallation process for Red Hat Developer Hub (RHDH). You also learn about the basics of configuration in RHDH, and how to configure authentication using a GitHub or GitLab backend along with single sign-on functionality using Keycloak.
+
+== Contributors
+
+The PTL team acknowledges the valuable contributions of the following Red Hat associates:
+
+* Ravi Srinivasan
+* Jason Froehlich
+* Hans-Peter Grahsl
+* Rafael Soares
+
+== Classroom Environment
+
+Use the https://demo.redhat.com/catalog?item=babylon-catalog-prod/openshift-cnv.ocp413-single-node-cnv.prod&utm_source=webapp&utm_medium=share-link[OpenShift 4.13 Single Node Workshop^] catalog item from Red Hat Demo Platform (RHDP).
+
+This classroom does *NOT* have RHDH pre-installed. You install and configure a basic RHDH instance, and then continue using this instance with other courses in the learning path.
+
+== Prerequisites
+
+* Basic knowledge of OpenShift (or Kubernetes) administration
+* Knowledge of building Docker or Podman containers.
+* Deploying container images on OpenShift or Kubernetes
+* OpenShift or Kubernetes User and Role administration
+
+== Objectives
+
+The overall objectives of this course include:
+
+* Install, Upgrade and Uninstall Red Hat Developer Hub on OpenShift
+* Perform basic configuration of RHDH
+* Configure single sign-on and user authentication for Red Hat Developer Hub using:
+** GitHub or GitLab
+** Keycloak

modules/chapter1/nav.adoc

@@ -1,4 +1,4 @@
 * xref:index.adoc[]
-** xref:section1.adoc[]
-** xref:section2.adoc[]
-** xref:section3.adoc[]
+** xref:install.adoc[]
+** xref:upgrade.adoc[]
+** xref:uninstall.adoc[]

modules/chapter1/pages/index.adoc

@@ -1,3 +1,10 @@
-= Chapter 1
+= Installation, Upgrades and Uninstallation
+:navtitle: Installation
 
-This is the home page of _Chapter_ 1 in the *hello* quick course...
+In this chapter, you will learn how to install Red Hat Developer Hub (RHDH) on OpenShift using different methods:
+
+* Installation using Helm charts
+* Installation using the Red Hat Developer Hub Operator
+* Installation using the CLI
+
+You will also learn how to upgrade and uninstall RHDH.

modules/chapter1/pages/install.adoc

@@ -0,0 +1,210 @@
+= Red Hat Developer Hub Installation
+:navtitle: Installing RHDH
+
+Red Hat builds and ships RHDH as a container image that is based on the _Red Hat Enterprise Linux Universal Base Image_ (**RHEL UBI**).
+
+There are several ways to install RHDH on OpenShift.
+
+== Installation Using the RHDH Operator
+
+RHDH can be installed from within the OpenShift web console just like any other operator from `OperatorHub`.
+
+Refer to the instructions https://docs.openshift.com/container-platform/4.13/operators/admin/olm-adding-operators-to-cluster.html[here^] to install the RHDH operator on OpenShift.
+
+NOTE: At the time of writing (Jan 2024), the operator is not yet available on *OperatorHub*. Watch this space for install instructions in the near future when the operator becomes generally available (ETA: Q1 2024).
+
+== Installation Using Helm Charts
+
+The Red Hat Developer Hub helm chart is available in the `Helm Catalog` in Openshift, and on https://artifacthub.io[ArtifactHUB^] (A repository of Helm Charts).
+
+A short refresher on how to work with Helm Charts on OpenShift is https://access.redhat.com/documentation/en-us/openshift_container_platform/4.13/html/building_applications/working-with-helm-charts[here^].
+
+The source code, templates, and the `values.yaml` file for the helm chart are available https://github.com/janus-idp/helm-backstage/tree/main[here^] for inspection.
+The chart contains an opinionated default configuration of Backstage with a pre-integrated set of useful plugins, and it also uses a PostgreSQL database to persist the configuration state of RHDH.
+
+The Helm chart option is the most up to date and recommended method of installation currently. In this course, you will use the `Red Hat Developer Hub` helm chart to install RHDH.
+
+== Lab: Installation using Helm Charts
+
+=== Pre-requisites
+
+. Order the https://demo.redhat.com/catalog?item=babylon-catalog-prod/openshift-cnv.ocp413-single-node-cnv.prod&utm_source=webapp&utm_medium=share-link[OpenShift 4.13 Single Node Workshop^] catalog item from Red Hat Demo Platform (RHDP). It should take an hour approximately for the classroom to be fully provisioned. You will receive an email with the details on how to access the OpenShift cluster. Verify that you can log in to the OpenShift web console as a cluster administrator.
+
+=== Create a Project for RHDH
+
+1. Log in to your OpenShift web console as the cluster administrator user (usually username is `admin`). The username and password details for your OpenShift cluster are accessible in the RHDP `Services` dashboard. You should have also received an email with the details of your OpenShift cluster.
++
+image::03-rhdp-cluster-details.png[title=RHDP OpenShift Cluster Details]
++
+[NOTE]
+====
+You can install the RHDH Helm chart as a regular, non-cluster administrator user, but this is not recommended. Many organizations have strict policies on who can install operators and charts in the OpenShift cluster.
+====
+
+2. Click on `Projects` (Ensure you are in the `Administrator` perspective of the OpenShift console). Create a new OpenShift project named `devhub`.
++
+image::new-ocp-project.png[title=Create a new OpenShift Project]
+
+=== Install the RHDH Helm Chart
+
+. Switch to the `Developer` perspective in the OpenShift console.
++
+image::switch-dev-perspective.png[title=Switch to the Developer Perspective]
+
+. Click `+Add` in the left side navigation bar of the `Developer` perspective, and then select `Helm Chart`
++
+image::add-helm-chart.png[title=Add Helm Chart]
+
+. Search for `"developer hub"` in the search field on this page, and then select the `Red Hat Developer Hub` chart.
++
+image::search-devhub-chart.png[title=Search for RHDH Helm Chart]
+
+. In the `Red Hat Developer Hub` chart page, click `Create`. You will see the `Create Helm Release` page with some fields that need to be edited.
+
+.. Change the `Release Name` to `rhdh`. Ensure that the latest helm chart is selected in the `Chart version` drop-down (As of Dec 2023, latest RHDH version is 0.2).
+
+.. Expand `Root Schema > global` and change the first field value from `apps.example.com` to the wildcard domain name of your OpenShift cluster. In RHDP, it is in the format `apps.cluster-<guid>.dynamic.opentlc.com`, where `<guid>` is unique to your provisioned OpenShift cluster.
+
+.. The final screen should look like the following:
++
+image::edit-helm-chart-values.png[title=Edit Helm Chart Details]
+
+.. Click `Create` to deploy the helm chart.
+
+. Wait for 10-15 minutes while the helm chart is deployed. The `PostgreSQL` and `Red Hat Developer Hub` should be fully started.
+Click the `Open URL` link to access Red Hat Developer Hub.
++
+image::rhdh-installed.png[title=RHDH Topology View]
+
+. You should now see the Red Hat Developer Hub log in page.
++
+image::rhdh-homepage.png[title=RHDH Log in Page]
+
+. Click `ENTER` in the `Guest` card to log in as a guest user. You will configure RHDH to authenticate against GitHub and other identity providers in later chapters of this course.
++
+image::rhdh-guest-user.png[title=Log in as a guest user]
++
+You have now successfully installed Red Hat Developer Hub on your OpenShift cluster.
+
+== Installation using Helm CLI
+
+You will need to install the `helm` CLI. You can download the *helm* and other CLI tools from the OpenShift web console by clicking the *"?"* icon on the top right navigation bar.
+
+image::cli-tools.png[title=Download CLI Tools]
+
+=== CLI Install Steps
+
+. Add the OpenShift helm chart repository
++
+```bash
+$ helm repo add openshift-helm-charts https://charts.openshift.io/
+```
+
+. Download the default *values.yaml* file for the RHDH helm chart
++
+```bash
+$ helm show values openshift-helm-charts/redhat-developer-hub > values.yaml
+```
+
+. Change the value of the *global.clusterRouterBase* attribute to the wildcard OpenShift DNS name, and also edit the *upstream.nameOverride* to *rhdh*.
++
+[subs=+quotes]
+----
+global:
+  clusterRouterBase: *apps.cluster-<guid>.dynamic.redhatworkshops.io*
+  host: ""
+
+upstream:
+  nameOverride: *rhdh*
+  backstage:
+...
+----
+
+. Log in to the OpenShift cluster as the cluster administrator. Ensure that you switch to the *devhub* project.
++
+```bash
+$ oc login -u admin https://api.cluster-<your_guid>.dynamic.redhatworkshops.io:6443
+$ oc project devhub
+```
+
+. Install the RHDH helm chart with the updated *values.yaml* file
++
+[subs=+quotes]
+----
+$ *helm upgrade -i rhdh -f values.yaml openshift-helm-charts/redhat-developer-hub*
+
+Release "rhdh" does not exist. Installing it now.
+...
+NAME: rhdh
+LAST DEPLOYED: Tue Dec  5 18:17:39 2023
+NAMESPACE: devhub
+STATUS: deployed
+REVISION: 1
+----
++
+You may sometimes see the following error during install. These messages can be safely ignored.
++
+```
+1.26.9+636f2be is greater than or equal to 1.14-0 ERROR CWNAKNVCIEJVOEJVJO
+```
+
+. Wait for 10-15 minutes while the helm chart is installed. Verify that the *rhdh-devhub* and *rhdh-postgresql* pods are in *Running* state.
++
+[subs=+quotes]
+----
+$ *oc get pods*
+NAME                    READY   STATUS    RESTARTS        AGE
+rhdh-5d9f68456d-2c4kq   1/1     Running   2 (6m12s ago)   6m23s
+rhdh-postgresql-0       1/1     Running   0               6m22s
+----
+
+. Fetch the OpenShift route for RHDH and open the URL in a browser to navigate to the RHDH home page.
++
+[subs=+quotes]
+----
+$ *oc get route rhdh-developer-hub --output jsonpath={.spec.host}*
+rhdh-developer-hub-devhub.apps.cluster-<guid>.dynamic.redhatworkshops.io
+----
+
+A short refresher on working with helm charts on OpenShift is available https://access.redhat.com/documentation/en-us/openshift_container_platform/4.13/html/building_applications/working-with-helm-charts[here^].
+
+More details about the RHDH helm chart are available at https://artifacthub.io/packages/helm/openshift/developer-hub.
+
+== RHDH PostgreSQL Database
+
+[WARNING] 
+====
+The default installation of RHDH (for both Helm Charts and Operator based installs) deploys a single PostgreSQL 15 database pod. This is a potential single point of failure and could prevent RHDH from being highly available.
+
+You should deploy a cluster of PostgreSQL instances using a suitable operator that provides high availability. Refer to https://www.crunchydata.com/products/crunchy-postgresql-for-openshift[crunchydata^], https://portworx.com/blog/run-ha-postgresql-red-hat-openshift[portworx^], and https://www.enterprisedb.com/docs/postgres_for_kubernetes/latest/openshift[EnterpriseDB^] for high availability PostgreSQL database options on OpenShift.
+
+You should follow the installation instructions and install the default single instance PostgreSQL to complete the install. You can then configure the RHDH container to integrate with a clustered PostgreSQL database instance, and delete the default PostgreSQL instance. The details of the configuration are covered in _Chapter 2_ of this course.
+====
+
+== Installation Troubleshooting
+
+The following are some problems you could see during installation, and the potential fix for them.
+
+. *Problem*: The `rhdh-developer-hub` pod is stuck in a `CrashLoopBackOff` error with the following seen in the logs:
++
+```
+Loaded config from app-config-from-configmap.yaml, env
+...
+2023-07-24T19:44:46.223Z auth info Configuring "database" as KeyStore provider
+type=plugin
+Backend failed to start up Error: Missing required config value at
+'backend.database.client'
+```
++
+*Solution*: This is happening because the configuration files are not being appropriately accessed by the RHDH container. You may have edited the helm chart values before installation, and one or more attributes are missing or configured incorrectly. It is recommended to keep the default values (except for the wildcard DNS name of the OpenShift cluster) during installation. 
++
+You can always edit and update the RHDH configuration after the installation is completed successfully.
+
+. *Problem*: I see the following error when installing the RHDH helm chart using the *helm* CLI:
++
+[subs=+quotes]
+----
+Error: query: failed to query with labels: secrets is forbidden: User "system:anonymous" cannot list resource "secrets" in API group "" in the namespace "devhub"
+----
++
+*Solution*: Ensure that you are logged in to the OpenShift cluster as a cluster administrator before installing, removing or upgrading the RHDH helm chart. Also ensure that you are in the correct OpenShift project so that the resources are created in it.

modules/chapter1/pages/uninstall.adoc

@@ -0,0 +1,41 @@
+= Red Hat Developer Hub Uninstallation
+:navtitle: Uninstalling RHDH
+
+IMPORTANT: Before you uninstall RHDH, verify if you need to back up the data in the RHDH PostgreSQL database!. Follow the instructions in the previous section to back up the PostgreSQL database.
+
+== Uninstalling the RHDH Helm Chart
+
+You can uninstall RHDH using the OpenShift web console.
+
+. Ensure that you are in the *Developer* perspective of the OpenShift console. Click on `Helm` to view the installed releases in the `Helm Releases` tab.
+
+. Expand the hamburger menu on the right of the `rhdh` release and click `Delete Helm Release`.
++
+image::helm-release-delete.png[title=Delete Helm Release]
+
+. Type the release name `rhdh` into the dialog that pops up and click `Delete` to delete the resources created by the helm chart.
+
+== Uninstalling the RHDH Helm Chart using the CLI
+
+You can uninstall RHDH using the *helm* CLI.
+
+. Log in to the OpenShift cluster as the cluster administrator. Ensure that you switch to the *devhub* project.
++
+```bash
+$ oc login -u admin https://api.cluster-<your_guid>.dynamic.redhatworkshops.io:6443
+$ oc project devhub
+```
+
+. Run the following command to uninstall RHDH
++
+[subs=+quotes]
+----
+$ *helm uninstall rhdh*
+release "rhdh" uninstalled
+----
+
+== Uninstalling the RHDH Operator
+
+NOTE: The operator is not yet available publicly (ETA: Q1 2024). Watch this section for updates once the operator is GA.
+
+You can refer to the instructions https://docs.openshift.com/container-platform/4.13/operators/admin/olm-deleting-operators-from-cluster.html[here^] to uninstall the RHDH operator.