Adding tips section and updating viz (#704)

docs/_static/custom.css

@@ -0,0 +1,31 @@
+:root {
+    --pst-font-size-base: none;
+    --pst-color-primary: 78, 78, 78;
+    --pst-color-secondary: 87, 154, 202;
+    --pst-color-info: var(--pst-color-secondary);
+    --pst-color-navbar-link-active: var(--pst-color-secondary);
+    --pst-color-sidebar-link-active: var(--pst-color-secondary);
+    --pst-color-link: var(--pst-color-secondary);
+}
+
+div.logo {
+    font-family: "Fira Sans";
+    text-align: center;
+    margin-top: 2em;
+}
+
+div.logo p {
+    margin: 0;
+}
+
+p.logo-main {
+    font-size: 4.5em;
+    font-weight: 700;
+    line-height: 1.1em;
+    color: rgb(var(--pst-color-primary));
+}
+
+p.logo-subtext {
+    color: rgb(var(--pst-color-secondary));
+    font-size:1.4em;
+}

docs/_templates/2i2c-logo.html

@@ -0,0 +1,6 @@
+<div class="logo">
+    <a href="{{ pathto(master_doc) }}">
+        <p class="logo-main">2i2c</p>
+        <p class="logo-subtext">Hub Engineer's Guide</p>
+    </a>
+</div>

docs/conf.py

@@ -51,15 +51,26 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
+html_favicon = "_static/favicon.png"
 html_theme = "sphinx_book_theme"
 html_theme_options = {
     "repository_url": "https://github.com/2i2c-org/pilot-hubs",
     "use_issues_button": True,
     "use_repository_button": True,
 }
+html_sidebars = {
+    "**": ["2i2c-logo.html", "sbt-sidebar-nav.html", "sbt-sidebar-footer"]
+}
+html_static_path = ["_static"]
 # Disable linkcheck for anchors because it throws false errors for any JS anchors
 linkcheck_anchors = False
 
+def setup(app):
+    app.add_css_file("custom.css")
+    app.add_css_file("https://code.cdn.mozilla.net/fonts/fira.css")
+
+
+
 # -- Custom scripts -----------------------------------------
 # Pull latest list of communities served by pilot-hubs/
 from yaml import safe_load

docs/howto/operate/manual-deploy.md

@@ -1,5 +1,5 @@
 (operate:manual-deploy)=
-# Set up and use the the deployment scripts locally
+# Manually deploy hubs
 
 While deploys generally go through our GitHub Actions workflow, sometimes you
 need to deploy from your laptop - primarily when testing changes on staging or

docs/index.md

@@ -44,6 +44,7 @@ topic/hub-templates.md
 topic/storage-layer.md
 topic/terraform.md
 topic/cluster-design.md
+topic/troubleshooting.md
 ```
 
 ## Reference

docs/topic/storage-layer.md

@@ -36,7 +36,7 @@ The NFS share creator job will be created pre-deploy, run, and cleaned up before
 
 ### Hub user mount
 
-For each hub, [a PersistentVolumeClaim(PVC) and a PersistentVolume(PV)](https://github.com/2i2c-org/pilot-hubs/blob/master/hub-templates/basehub/templates/nfs-pvc.yaml#L1) are created. This is the Kubernetes *Volume* that refers to the actual storage on the NFS server. The volume points to the hub directory created for the hub and user at `/export/home-01/homes/<hub-name>/<username>` (this name is dynamically determined as a combination of `nfs.pv.baseShareName` and the current release name). Z2jh then mounts the PVC on each user pod as a [volume named **home**](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/blob/master/jupyterhub/files/hub/jupyterhub_config.py#L277).
+For each hub, [a PersistentVolumeClaim(PVC) and a PersistentVolume(PV)](https://github.com/2i2c-org/pilot-hubs/blob/master/hub-templates/basehub/templates/nfs.yaml) are created. This is the Kubernetes *Volume* that refers to the actual storage on the NFS server. The volume points to the hub directory created for the hub and user at `/export/home-01/homes/<hub-name>/<username>` (this name is dynamically determined as a combination of `nfs.pv.baseShareName` and the current release name). Z2jh then mounts the PVC on each user pod as a [volume named **home**](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/blob/master/jupyterhub/files/hub/jupyterhub_config.py#L277).
 
 Parts of the *home* volume are mounted in different places for the users:
    * [user home directories](https://github.com/2i2c-org/pilot-hubs/blob/master/hub-templates/basehub/values.yaml#L100)

docs/topic/troubleshooting.md

@@ -0,0 +1,29 @@
+# Troubleshooting and debugging
+
+These sections describe a few common and useful tips for troubleshooting our infrastructure.
+
+## Roll back (revert) a helm deploy
+
+Sometimes it is useful to simply **revert** a Kubernetes deployment with Helm.
+For example, if you've manually deployed something via `helm upgrade`, and notice that something is wrong with our deployment.
+
+:::{note}
+Ideally, this would have happened automatically via CI/CD, but sometimes a manual deploy is still necessary!
+:::
+
+If you'd simply like to revert back to the state of the Kubernetes infrastructure from before you ran `helm install`, try the following commands:
+
+- **Get the deployment name and revision number for the latest deploy**. To do so, run this command:
+  ```bash
+  helm list --namespace {{NAMESPACE}}
+  ```
+- Roll back the deployment to the previous revision, using the information output from the above command:
+
+  ```bash
+  helm rollback --namespace {{NAMESPACE}} {{DEPLOYMENT_NAME}} {{REV_NUM - 1}}
+  ```
+
+  The {{REV_NUM - 1}} simply means "deploy the previous revision number".
+  Usually, `NAMESPACE` and `DEPLOYMENT_NAME` are identical, but always best to double check.
+
+This should revert the Helm deployment to the previous revision (the one just before you ran `helm upgrade`).