docs: update and extend instructions

The instructions could use a little refactor to include some of the
missing steps which are required to successfully run the E2E tests for
Developer Sandbox.

Author: MikelAlejoBR

CRC.adoc

@@ -1,80 +1,160 @@
 :imagesdir: doc/images
 
-==== Step by Step Guide - CRC (CodeReady Containers)
+== Step-by-step guide — CRC (CodeReady Containers)
 
-IMPORTANT: CodeReady Containers includes an embedded system bundle that contains certificates which expire 30 days after the release.  Because of this it is very important to always run the latest release of CRC.
+IMPORTANT: CodeReady Containers includes an embedded system bundle that contains certificates which expire 30 days
+after the release.  Because of this it is very important to always run the latest release of CRC.
 
-CodeReady Containers is a distribution of OpenShift designed to be run on a development PC, and while some features have been disabled by default it is still quite demanding in terms of system resources, and for this reason it is recommended that it be installed on a machine that has at least 32GB of memory.
+CodeReady Containers is a distribution of OpenShift designed to be run on a development PC, and while some features
+have been disabled by default it is still quite demanding in terms of system resources, and for this reason it is
+recommended that it be installed on a machine that has at least 32GB of memory.
 
-This guide will walk through the steps of downloading and install CRC, and running the e2e tests against local Codeready Toolchain host-operator and member-operator repositories.
+This guide will walk through the steps of downloading and install CRC, and running the e2e tests against local
+Codeready Toolchain host-operator and member-operator repositories.
 
-1. Download CodeReady Containers from https://developers.redhat.com/products/codeready-containers/overview[developers.redhat.com].
-You will need to login using your Red Hat SSO account, after which you may click on the `Install OpenShift on your laptop` button which will take you to the download page for CRC.  From here, select your OS before clicking `Download CodeReady Containers`.  You will also need to download your pull secret, and keep that in a safe place.
+=== Download and install CRC
+Download CodeReady Containers from https://developers.redhat.com/products/codeready-containers/overview[developers.redhat.com].
+You will need to login using your Red Hat SSO account, after which you may click on the `Install OpenShift on your
+laptop` button which will take you to the download page for CRC. From here, select your OS before clicking `Download
+CodeReady Containers`. You will also need to download your pull secret, and keep that in a safe place.
 +
 image::download.png[align="center"]
 
-2. Extract the downloaded file into a directory of your choice.
-+
+Extract the downloaded file into a directory of your choice:
+
+```[source,bash]
+tar -xvf crc-linux-amd64.tar.xz
+```
+
 image::extract_crc.png[align="center"]
-+
-You may also wish to add this directory to your path so that you can run the `crc` command from anywhere.
 
-3. Enable Cluster Monitoring, which is required for tests to pass by running the following command:
-+
-`crc config set enable-cluster-monitoring true`
+Give execution permissions to the binary and move it to a directory on your path or `/usr/local/bin`:
 
-4. Since cluster monitoring requires at least 14GB of virtual machine memory, you also need to increase the default by running the following command - the value here is sufficient but you may make it higher if desired:
-+
-`crc config set memory 14500`
+```[source,bash]
+chmod u+x crc
+sudo mv crc /usr/local/bin
+```
 
-5. Set the `QUAY_NAMESPACE` environment variable to your quay username:
-+
-`export QUAY_NAMESPACE=<quay-username>`
+=== Enable or tweak the cluster's settings
+
+In order to run the tests seamlessly and without any problems, there is a set of settings you are advised to change.
+
+```[source,bash]
+# Cluster monitoring is required for the tests to pass
+crc config set enable-cluster-monitoring true
+
+# A minimum of 14Gb of virtual machine memory are required to run by default, so it is recommended to change that
+# setting. Tweaking the CPUs and disk size is optional, but also recommended to avoid having issues down the line.
+crc config set cpus 8
+crc config set disk-size 50
+crc config set memory 14500 # or 20000 for 20Gb
+```
+
+=== Start the cluster
+
+The first time you will need to set it up and provide the pull request secret you were presented with in the CRC
+download page — if you didn't grab it you can come back and copy it. Then, run the following commands:
+
+```[source,bash]
+expot QUAY_NAMESPACE=${YOUR_QUAY_USERNAME}
+crc setup
+crc start
+```
+
+While CRC boots, prepare the necessary projects, operators and images.
+
+=== Prepare the projects
+
+In order to run the tests, you need to have certain projects ready and the images pushed to Quay. For that, clone
+the following repositories in the same directory level as the `toolchain-e2e` project:
+
+* https://github.com/codeready-toolchain/host-operator[host-operator]
+* https://github.com/codeready-toolchain/member-operator[member-operator]
+* https://github.com/codeready-toolchain/registration-service[registration-service]
+
+On each of the repositories, build the images and push them to your Quay account:
+
+```[source,bash]
+# Expot your namespace so that the build targets tag the image with your Quay repository's name.
+export QUAY_NAMESPACE=${YOUR_QUAY_NAMESPACE}
+
+# Build the images.
+make podman-image
+
+# Push them to your Quay repositories.
+make podman-push
+```
+
+For `member-operator`, you might want to manually tag it to be able to push it to the `member-operator-webhook`
+repository:
+
+```[source,bash]
+podman tag quay.io/${YOUR_QUAY_NAMESPACE}/member-operator:${TAG} quay.io/${YOUR_QUAY_NAMESPACE}/member-operator-webhook:${TAG}
+podman push quay.io/${YOUR_QUAY_NAMESPACE}/member-operator-webhook:${TAG}
+```
+
+Once you have pushed all the images to Quay, you need to make the repositories public so that CRC can download them.
+For each of the repositories...
 
-6. Ensure that the following Quay repositories are set to public:
-+
 * host-operator
 * member-operator
 * member-operator-webhook
 * registration-service
 
-You can find these on the https://quay.io/repository/[Repository] page at quay.io:
-
-image::quay_repo.png[align=center]
-
-Click on the repository name, then click on the settings icon:
+... click on the repository name, then click on the "Settings" icon:
 
 image::quay_repo_detail.png[align=center]
 
-Scroll down to the *Repository Visibility* section, and ensure the repository is set to public:
+Then scroll down to the *Repository Visibility* section, and ensure the repository is set to public:
 
 image::quay_repo_visibility.png[align=center]
 
-7. Start the CRC container by executing `crc start`. This will take a few minutes to complete, and the output should look something like this:
+=== Final steps and running the tests
+
+After some time has passed, the CRC cluster might be ready to work with. The terminal should show an output similar to
+the following one:
 
 image::crc_start_output.png[align=center]
 
-Take note of the `oc login...` command shown in the output.
+Add the `oc` executable to your current path by running the following command:
 
-8. Execute the following command to set up the necessary environment variables:
+```[source,bash]
+eval $(crc oc-env)
+```
 
-`eval $(crc oc-env)`
+Now, log in as the *kubeadmin* user, since you need the required privileges to manage namespaces, install operators,
+clean  up resources and what not. Your login command should look something similar to this:
+
+```[source,bash]
+oc login -u kubeadmin -p ${THE_PASSWORD} ${URL_SHOWN_IN_OUTPUT}
+```
 
-9. Log into the cluster by executing the `oc login` command as shown in the resulting output from running `crc start` in the previous step.  The output should look something like this:
-+
 image::crc_oc_login.png[align=center]
 
-10. Check out the CodeReady Toolchain `host-operator` and `member-operator` repositories and ensure that they are located at the same directory level as the `toolchain-e2e` repository.
-+
-* https://github.com/codeready-toolchain/host-operator
-* https://github.com/codeready-toolchain/member-operator
-+
-11. Change into the `toolchain-e2e` directory, and execute the tests.  It is recommended that you direct console output to a text file, as the test output is of significant length and is likely to be longer than your console buffer:
-+
-`make test-e2e-local >testoutput.txt`:
-+
+Finally, run the tests with the following command while you're on the `toolchain-e2e` repository:
+
+```[source,bash]
+# It is recommended to redirect the output so that it doesn't overflow your terminal's buffer, and so that you can
+# check the entirety of the output.
+
+make test-e2e-local > testoutput.txt
+```
+
+=== Cleaning up
 
+After a run, regardless of wheter it was successful or not, you can — and it is recommended to — run the following
+target to clean up the resources in the CRC cluster:
 
+```[source,bash]
+make clean-e2e-resources
+```
 
+If for some reason the cleaning up of the resources gets stuck, you can run the following target before running the
+"clean" target again to remove the finalizers that prevent the cleanup:
 
+```[source,bash]
+make force-remove-finalizers-from-e2e-resources
 
+# Rerun the cleanup again.
+make clean-e2e-resources
+```