Merge Geddes user guide

docs/userguides/geddes/access.md

@@ -0,0 +1,47 @@
+---
+tags:
+  - Geddes
+authors:
+  - jin456
+  - goughes
+search:
+  boost: 2
+---
+
+# Access
+
+Access to the Geddes Composable Platform is handled via the RCAC web portal. When access is purchased, a Rancher project with your research group's name will be created and managers will be able to click to give users access, similar to how access is managed for community clusters. Links to access Geddes via the Rancher UI and the command line (`kubectl`) are below.
+
+## Rancher
+
+### Logging in to Rancher
+
+To access the Geddes user interface, you must be on a Purdue campus network or connected through [VPN](https://it.purdue.edu/services/vpn.php).
+
+Once connected to a Purdue network, the Geddes Rancher interface can be accessed via a web browser at [geddes.rcac.purdue.edu](https://geddes.rcac.purdue.edu). Log in by choosing "log in with shibboleth" and using Purdue Login at the login screen.
+
+## Kubectl
+
+### Configuring local kubectl access with a Kubeconfig file
+
+**kubectl** can be installed and run on your local machine to perform various actions against the Kubernetes cluster using the API server.
+
+These tools authenticate to Kubernetes using information stored in a [**kubeconfig**](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) file.
+
+!!! note
+    A file that is used to configure access to a cluster is sometimes called a *kubeconfig* file. This is a generic way of referring to configuration files. It does not mean that there is a file named **kubeconfig**.
+
+To begin accessing Geddes via **kubectl** you must first gather your rancher generated **Kubeconfig** file and set up your local `.kube` directory.
+
+1. From anywhere in the Rancher UI navigate to the top right and click on either **Download KubeConfig** or **Copy KubeConfig to Clipboard**
+   * Create a directory in your home directory (`$HOME`) called `.kube`
+   * Change into the newly created directory and copy the file or contents of **KubeConfig** from earlier into a file called **config**
+2. Test connections to the Geddes cluster
+   * To look at the current config settings we just set use `kubectl config view`
+   * Now let’s list the available resource types present in the API with `kubectl api-resources`
+
+To see more options of kubectl, review the [Kubernetes' kubectl cheatsheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/).
+
+### Accessing kubectl in the Rancher web UI
+
+You can launch a kubectl command window from within the Rancher UI by selecting the **Kubectl Shell** button at the top right or using the hotkey (`` CTRL + ` ``). This will deploy a container in the cluster with kubectl installed and give you an interactive window to use the command from.

docs/userguides/geddes/biography.md

@@ -0,0 +1,28 @@
+---
+tags:
+  - Geddes
+authors:
+  - jin456
+  - goughes
+search:
+  boost: 2
+---
+
+# Biography of Lanelle Geddes
+![Portrait of Lanelle Geddes](/assets/images/userguides/geddes/bio_geddes.jpeg){ align=right width="260" }
+
+LaNelle E. (Nerger) Geddes was born on September 15, 1935 in Houston, Texas to Carl O. and Evelyn Nerger. She received a B.S. in Nursing from the University of Houston in 1957, and earned a PhD in Biophysics there in 1970. After receiving her PhD, Geddes taught at the Texas Women's University and in the Department of Physiology at Baylor College of Medicine in Houston.
+
+Geddes joined the faculty at Purdue in 1975 where her husband, Leslie A. Geddes, was the head of the Department of Biomedical Engineering. Lanelle started in the School of Nursing as the Assistant Head of the Department. In 1980, she was promoted to the Head of the Department and served as Head until 1991. While at Purdue, Geddes challenged traditional perceptions of nurses as merely doctors' assistants who were wrongly believed to have no expertise or skill for diagnosis and treatment. In addition, Geddes was also instrumental in instituting a four-year nursing baccalaureate program and starting the Freshman Scholars, a program that provided scholarships to outstanding incoming freshman.
+
+Geddes' research was focused on cardiovascular physiology. Her teaching emphasized the impact of human pathophysiologic alterations and their influence on nursing and medical care. Her inclusion of pathophysiology encouraged her students to make better clinical judgments and to be stronger patient advocates. From 1996-2003, Geddes also taught pathophysiology to IU School of Medicine students at Purdue University. Geddes retired as a professor emeritus in 2003.
+
+Geddes' research and teaching had far-reaching impacts, and she received many awards over the course of her career. She was an AMOCO Foundation (Murphy) Award winner, a fellow of the University Teaching Academy, and a Helen B Schleman Gold Medallion Awardee. She also received the Lafayette YWCA Salute to Women Award and the Westminster Village Lifetime Service Award for her work within the community. Geddes passed away on January 25, 2016.
+
+## Citations
+
+Archives and Special Collections. (2021, May 19). Geddes, Lanelle E., September 15, 1935 - January 25, 2016. Purdue University. Retrieved from: <https://archives.lib.purdue.edu/agents/people/802>
+
+<https://earchives.lib.purdue.edu/digital/collection/oralhist/id/31>
+
+[**Back to Geddes User Guide**](index.md)

docs/userguides/geddes/concepts.md

@@ -0,0 +1,56 @@
+---
+tags:
+  - Geddes
+authors:
+  - jin456
+  - goughes
+search:
+  boost: 2
+---
+
+# Concepts
+
+## Containers & Images
+
+**Image** - An image is a simple text file that defines the source code of an application you want to run as well as the libraries, dependencies, and tools required for the successful execution of the application. Images are immutable meaning they do not hold state or application data. Images represent a software environment at a specific point of time and provide an easy way to share applications across various environments. Images can be built from scratch or downloaded from various repositories on the internet, additionally many software vendors are now providing containers alongside traditional installation packages like Windows .exe and Linux rpm/deb.
+
+**Container** - A container is the run-time environment constructed from an image when it is executed or run in a container runtime. Containers allow the user to attach various resources such as network and volumes in order to move and store data. Containers are similar to virtual machines in that they can be attached to when a process is running and have arbitrary commands executed that affect the running instance. However, unlike virtual machines, containers are more lightweight and portable allowing for easy sharing and collaboration as they run identically in all environments.
+
+**Tags** - Tags are a way of organizing similar image files together for ease of use. You might see several versions of an image represented using various tags. For example, we might be building a new container to serve web pages using our favorite web server: nginx. If we search for the nginx container on Docker Hub image repository we see many options or tags are available for the official nginx container.
+
+The most common you will see are typically `:latest` and `:number` where *number* refers to the most recent few versions of the software releases. In this example we can see several tags refer to the same image: `1.21.1, mainline, 1, 1.21,` and `latest` all reference the same image while the `1.20.1, stable, 1.20` tags all reference a common but different image. In this case we likely want the nginx image with either the `latest` or `1.21.1` tag represented as `nginx:latest` and `nginx:1.21.1` respectively.
+
+**Container Security** - Containers enable fast developer velocity and ease compatibility through great portability, but the speed and ease of use come at some costs. In particular it is important that folks utilizing container driver development practices have a well established plan on how to approach container and environment security.
+
+**Container Registries** - Container registries act as large repositories of images, containers, tools and surrounding software to enable easy use of pre-made containers software bundles. Container registries can be public or private and several can be used together for projects. Docker Hub is one of the largest public repositories available, and you will find many official software images present on it. You need a user account to avoid being rate limited by Docker Hub. A private container registry based on Harbor is available to use; see the [Container Registry](registry.md) page.
+
+**Docker Hub** - Docker Hub is one of the largest container image registries that exists and is well known and widely used in the container community, it serves as an official location of many popular software container images. Container image repositories serve as a way to facilitate sharing of pre-made container images that are “ready for use.” Be careful to always pay attention to who is publishing particular images and verify that you are utilizing containers built only from reliable sources.
+
+**Harbor** - Harbor is an open source registry for Kubernetes artifacts, it provides private image storage and enforces container security by vulnerability scanning as well as providing RBAC or role based access control to assist with user permissions. Harbor is a registry similar to Docker Hub, however it gives users the ability to create private repositories. You can use this to store your private images as well as keeping copies of common resources like base OS images from Docker Hub and ensure your containers are reasonably secure from common known vulnerabilities.
+
+## Container Runtime Concepts
+
+**Docker Desktop** - Docker Desktop is an application for your Mac / Windows machine that will allow you to build and run containers on your local computer. Docker desktop serves as a container environment and enables much of the functionality of containers on whatever machine you are currently using. This allows for great flexibility, you can develop and test containers directly on your laptop and deploy them directly with little to no modifications.
+
+**Volumes** - Volumes provide us with a method to create persistent data that is generated and consumed by one or more containers. For docker this might be a folder on your laptop while on a large Kubernetes cluster this might be many SSD drives and spinning disk trays. Any data that is collected and manipulated by a container that we want to keep between container restarts needs to be written to a volume in order to remain around and be available for later use.
+
+## Container Orchestration Concepts
+
+**Container Orchestration** - Container orchestration broadly means the automation of much of the lifecycle management procedures surrounding the usage of containers. Specifically it refers to the software being used to manage those procedures. As containers have seen mass adoption and development in the last decade, they are now being used to power massive environments and several options have emerged to manage the lifecycle of containers. One of the industry leading options is Kubernetes, a software project that has descended from a container orchestrator at Google that was open sourced in 2015.
+
+**Kubernetes (K8s)** - Kubernetes (often abbreviated as "K8s") is a platform providing container orchestration functionality. It was open sourced by Google around a decade ago and has seen widespread adoption and development in the ensuing years. K8s is the software that provides the core functionality of the Geddes Composable Platform by managing the complete lifecycle of containers. Additionally it provides the following functions: service discovery and load balancing, storage orchestration, secret and configuration management. The Kubernetes cluster can be accessed via the Rancher UI or the kubectl command line tool.
+
+**Rancher** - Rancher is a “complete software stack for teams adopting containers” as described by its website. It can be thought of as a wrapper around Kubernetes, providing an additional set of tools to help operate the K8s cluster efficiently and additional functionality that does not exist in Kubernetes itself. Two examples of the added functionality is the Rancher UI that provides an easy to use GUI interface in a browser and Rancher projects, a concept that allows for multi-tenancy within the cluster. Users can interact directly with Rancher using either the Rancher UI or Rancher CLI to deploy and manage workloads on the Geddes Composable Platform.
+
+**Rancher UI** - The Rancher UI is a web based graphical interface to use the Geddes Composable Platform from anywhere.
+
+**Rancher CLI** - The Rancher CLI provides a convenient text based toolkit to interact with the cluster. The binary can be downloaded from the link on the right hand side of the footer in the Rancher UI. After you download the Rancher CLI, you need to make a few configurations Rancher CLI requires:
+
+- Your Rancher Server URL, which is used to connect to Rancher Server.
+- An API Bearer Token, which is used to authenticate with Rancher. See Creating an API Key.
+
+After setting up the Rancher CLI you can issue `rancher --help` to view the full range of options available.
+
+**Kubectl** - Kubectl is a text based tool for working with the underlying Geddes Kubernetes cluster. In order to take advantage of kubectl you will either need to set up a Kubeconfig File or use the built in kubectl shell in the Rancher UI. You can learn more about kubectl and how to download the kubectl file on the [Kubectl](access.md#kubectl) page.
+
+**Storage** - Storage is utilized to provide persistent data storage between container deployments. The **Ceph** filesystem provides access to Block, Object and shared file systems. File storage provides an interface to access data in a file and folder hierarchy similar to NTFS or NFS. Block storage is a flexible type of storage that allows for snapshotting and is good for database workloads and generic container storage. Object storage is also provided by Ceph, this features a REST based bucket file system providing S3 and Swift compatibility.

docs/userguides/geddes/examples/database.md

@@ -0,0 +1,75 @@
+---
+tags:
+  - Geddes
+authors:
+  - jin456
+  - goughes
+search:
+  boost: 2
+---
+
+# Database
+
+## Deploy a postgis Database
+
+1. Select your **Project** from the top right dropdown
+2. Using the far left menu, select **Workload**
+3. Click **Create** at the top right
+4. Select the appropriate **Deployment Type** for your use case, here we will select and use **Deployment**
+5. Fill out the form
+    * Select **Namespace**
+    * Give an arbitrary **Name**
+    * Set **Container Image** to the postgis Docker image: `geddes-registry.rcac.purdue.edu/docker-hub-cache/postgis/postgis:latest`
+    * Set the postgres user password
+        + Select the **Add Variable** button under the **Environment Variables** section
+        + Fill in the fields **Variable Name** and **Value** so that we have a variable `POSTGRES_PASSWORD = <some password>`
+    * Create a persistent volume for your database
+        + Select the **Storage** tab from within the current form on the left hand side
+        + Select **Add Volume** and choose **Create Persistent Volume Claim**
+        + Give an arbitrary **Name**
+        + Select **Single-Node Read/Write**
+        + Select an appropriate **Storage Class** from the dropdown and give **Capacity** in GiB **e.g** 5
+        + Provide the default postgres data directory as a **Mount Point** for the persistent volume `/var/lib/postgresql/data`
+        + Set **Sub Path** to `data`
+    * Set resource CPU limitations
+        + Select **Resources** tab on the left within the current form
+        + Under the **CPU Reservation** box fill in `2000`. This ensures that Kubernetes will only schedule your workload to nodes that have that resource amount available, guaranteeing your application has 2 CPU cores to utilize
+        + Under the **CPU Limit** box also fill in `2000`. This ensures that your workload cannot exceed or utilize more than 2 CPU cores. This helps resource quota management on the project level.
+    * Setup Pod Label
+        + Select **Labels & Annotations** on the left side of the current form
+        + Select **Add Label** under the **Pod Labels** section
+        + Give an arbitrary unique key and value you can remember later when creating Services and other resources **e.g** **Key:** `my-db` **Value:** `postgis`
+    * Select **Create** to launch the postgis database
+
+Wait a couple minutes while your persistent volume is created and the postgis container is deployed. The "does not have minimum availability" message is expected. But, waiting more than 5 minutes for your workload to deploy typically indicates a problem. You can check for errors by clicking your workload name (i.e. "mydb"), then the lower button on the right side of your deployed pod and selecting **View Logs**. If all goes well, you will see an Active status for your deployment.
+
+## Expose the Database to external clients
+
+Use a **LoadBalancer** service to automatically assign an IP address on a private Purdue network and open the postgres port (5432). A DNS name will automatically be configured for your service as `<servicename>.<namespace>.geddes.rcac.purdue.edu`.
+
+1. Using the far left menu navigate to **Service Discovery** > **Services**
+2. Select **Create** at the top right
+3. Select **Load Balancer**
+4. Fill out the form
+    * Ensure to select the **namespace** where you deployed the postgis database
+    * Give a **Name** to your **Service**. Remember that your final DNS name when the service creates will be in the format of `<servicename>.<namespace>.geddes.rcac.purdue.edu`
+    * Fill in **Listening Port** and **Target Port** with the postgis default port **5432**
+    * Select the **Selectors** tab within the current form
+        + Fill in **Key** and **Value** with the label values you created during the **Setup Pod Label** step from earlier **e.g** **Key:** `my-db` **Value:** `postgis`
+        + IMPORTANT: The yellow bar will turn green if your key-value pair matches the pod label you set during the "Setup Pod Label" deployment step above. If you don't see a green bar with a matching Pod, your LoadBalancer will not work.
+    * Select the **Labels & Annotations** tab within the current form
+        + Select **Add Annotation**
+        + To deploy to a **Purdue Private Address Range** fill in **Key:** `metallb.universe.tf/address-pool` **Value:** `geddes-private-pool`
+        + To deploy to a **Public Address Range** fill in **Key:** `metallb.universe.tf/address-pool` **Value:** `geddes-public-pool`
+
+Kubernetes will now automatically assign you an IP address from the Geddes private IP pool. You can check the IP address by hovering over the "5432/tcp" link on the Service Discovery page or by viewing your service via kubectl on a terminal.
+
+```
+$ kubectl -n <namespace> get services
+```
+
+Verify your DNS record was created:
+
+```
+$ host <servicename>.<namespace>.geddes.rcac.purdue.edu
+```

docs/userguides/geddes/examples/index.md

@@ -0,0 +1,17 @@
+---
+tags:
+  - Geddes
+authors:
+  - jin456
+  - goughes
+search:
+  boost: 2
+---
+
+# Examples
+
+Examples of deploying a database with persistent storage and making it available on the network and deploying a webserver using a self-assigned URL.
+
+- [**Database**](database.md)
+- [**Web Server**](webserver.md)
+- [**R Shiny**](r-shiny.md)