more infra docs

docs/Dockerfile

@@ -4,6 +4,7 @@ WORKDIR /docs
 
 RUN ["cargo", "install", "mdbook", "--vers", "^0.4", "--locked"]
 RUN ["cargo", "install", "mdbook-alerts"]
+RUN ["cargo", "install", "mdbook-toc"]
 
 COPY . .
 VOLUME ["/docs"]

docs/book.toml

@@ -11,3 +11,7 @@ git-repository-url = "https://github.com/asuc-octo/berkeleytime/tree/gql/docs"
 edit-url-template = "https://github.com/asuc-octo/berkeleytime/tree/gql/docs/{path}"
 
 [preprocessor.alerts]
+
+[preprocessor.toc]
+command = "mdbook-toc"
+renderer = ["html"]

docs/src/README.md

@@ -20,26 +20,29 @@ Using Docker allows us to build the docs without downloading dependencies on our
 # Ensure you are on the latest commit
 git pull
 
-# Build the container
+# Build the container (only needed once every time docs/Dockerfile changes!)
 docker build --target docs-dev --tag="docs:dev" ./docs
 
 # Run the container
 docker run --publish 3000:3000 --volume ./docs:/docs "docs:dev"
 ```
 
-The docs should be available at `http://localhost:3000/`. To change the port to port `XXXX`, modify the last command:
+The docs should be available at `http://localhost:3000/` with live reload. To change the port to port `XXXX`, modify the last command:
 ```sh
 # Run the container and publish the docs to http://localhost:XXXX/
 docker run --publish XXXX:3000 --volume ./docs:/docs "docs:dev"
 ```
 
+To kill the container, you can use the Docker Desktop UI or run `docker kill [container id]`. You can find the container ID from `docker ps`.
+
 #### Without Containerization
 
-To build and view the docs locally, `mdBook` must be installed by following the guide [here](https://rust-lang.github.io/mdBook/guide/installation.html#build-from-source-using-rust). It is necessary to install Rust locally as there is a dependency that is installed with `cargo`. Thus, it is highly recommended to [build mdbook from Rust](https://rust-lang.github.io/mdBook/guide/installation.html#build-from-source-using-rust).
+To build and view the docs locally, `mdBook` must be installed by following the guide [here](https://rust-lang.github.io/mdBook/guide/installation.html#build-from-source-using-rust). It is necessary to install Rust locally as there are dependencies that are installed with `cargo`. Thus, it is highly recommended to [build mdbook from Rust](https://rust-lang.github.io/mdBook/guide/installation.html#build-from-source-using-rust).
 
 ```sh
-# Install mdbook-alerts dependency with cargo
+# Install mdbook preprocessors with cargo
 cargo install mdbook-alerts
+cargo install mdbook-toc
 
 # ./berkeleytime
 # Ensure you are on the latest commit

docs/src/SUMMARY.md

@@ -21,9 +21,8 @@
 
 - [Infrastructure](./core/infrastructure/README.md)
     - [Onboarding](./core/infrastructure/onboarding.md)
-    - [Architecture](./core/infrastructure/architecture.md)
-    - [Kubernetes & Helm](./core/infrastructure/kubernetes-helm.md)
-    - [CI/CD](./core/infrastructure/cicd.md)
+    - [CI/CD Workflow](./core/infrastructure/cicd-workflow.md)
+    - [Runbooks](./core/infrastructure/runbooks.md)
 
 ---
 

docs/src/core/infrastructure/onboarding.md

@@ -1,7 +1,11 @@
 # Onboarding
 
+<!-- toc -->
+
+## SSH Setup
+
 > [!WARNING]
-> Running commands in `hozer-51` can break production! Please continue with caution.
+> This onboarding step is not necessary for local development. As running commands in `hozer-51` can break production, please continue with caution.
 
 The Berkeleytime website is hosted on a machine supplied by [the OCF](https://www.ocf.berkeley.edu/). This machine will be referenced as `hozer-51` in these docs. SSH allows us to connect to `hozer-51` with a shell terminal, allowing us to infra-related tasks.
 
@@ -36,3 +40,105 @@ This guide assumes basic experience with SSH.
     ssh hozer-51
     # as opposed to [email protected]
     ```
+
+## Architecture
+
+Berkeleytime uses a fairly simple microservices architecture—we decouple only a few application components into separate services. Below is a high-level diagram of the current architecture (switch to a light viewing mode to see arrows).
+<p align="center">
+    <img
+        src="./assets/architecture-diagram.svg"
+        alt="berkeleytime architecture design"
+        width="75%" />
+</p>
+
+Note that, other than the application services developed by us, all other services are well-known and have large communities. These services have many tutorials, guides, and issues already created online, streamlining the setup and debugging processes.
+
+### An HTTP Request's Life
+
+To better understand the roles of each component in the Berkeleytime architecture, we describe the lifecycle of an HTTP request from a user's action.
+
+1. An HTTP request starts from a user's browser. For example, when a user visits `https://berkeleytime.com`, a `GET` request is sent to `hozer-51`.[^1]
+
+2. Once the request reaches `hozer-51`, it is first encountered by `hozer-51`'s Kubernetes cluster load balancer, a [MetalLB](https://metallb.io/) instance, which balances external traffic into the cluster across nodes.[^2]
+
+3. Next, the request reaches the [reverse proxy](https://www.cloudflare.com/learning/cdn/glossary/reverse-proxy/), an [nginx](https://nginx.org/) instance, which forwards HTTP requests to either a [backend](../backend) or [frontend](../frontend/) service based on the URL of the request
+    - Requests with URLs matching `https://berkeleytime.com/api/*` are forwarded to the backend service.
+    - All other requests are forwarded to the frontend service.
+
+    The nginx instance is also responsible for load balancing between the backend/frontend replicas. Currently, there are two of each in all deployment environments.
+
+4. The request is processed by one of the services.
+    - The backend service may interact with the MongoDB database or the Redis cache while processing the request.[^3]
+
+5. Finally, an HTTP response is sent back through the system to the user's machine.
+
+
+[^1]: More specifically, the user's machine first requests a DNS record of `berkeleytime.com` from a DNS server, which should return `hozer-51`'s IP address. After the user's machine knows the `hozer-51` IP address, the `GET` request is sent.
+
+[^2]: Currently, we only have one node: `hozer-51`.
+
+[^3]: Requests sent from the backend to the database or cache are *not* necessarily HTTP requests.
+
+## Kubernetes & Helm
+
+[Kubernetes](https://kubernetes.io/) is a container orchestrator that serves as the foundation of our infrastructure. It provides a simple deployment interface. To get started with Kubernetes, here are a few resources:
+- The [concepts page](https://kubernetes.io/docs/concepts/) is a good place to start.
+- The [glossary](https://kubernetes.io/docs/reference/glossary/?core-object=true&fundamental=true&networking=true) is also a good place to glance over common jargon.
+
+[Helm](https://helm.sh/) is a package manager for Kubernetes that provides an abstraction over the Kubernetes interface for deploying groups of components called "charts". In addition, it allows us to install pre-made charts, useful for deploying services that we don't develop.
+
+### Useful Commands
+
+This is an uncomprehensive list of commands that can be executed in `hozer-51`, useful for debugging.
+
+> [!TIP]
+> On `hozer-51`, `k` is an alias for `kubectl` and `h` is an alias for `helm`.
+
+> [!IMPORTANT]
+> The default namespace has been set as `bt`.
+
+#### Pods
+
+- `k get pods`
+
+    View all running pods.
+
+- `k get pods -l env=[dev|stage|prod]`
+
+    View all running pods in a specified environment.
+
+- `k logs [pod name]`
+
+    View logs of a pod. You can get a pod's name with `k get pods`. Include a `-f` flag to follow logs, which will stream logs into your terminal.
+
+- `k describe pod [pod name]`
+
+    View a description of a pod. Useful for when pod is failing to startup, thus not showing any logs.
+
+- `k exec -it [pod name] -- [command]`
+
+    Execute a command inside a pod. The command can be `bash`, which will start a shell inside the pod and allow for more commands.
+
+#### Deployments
+
+- `k get deploy`
+
+    View all running deployments.
+
+- `k get deploy -l env=[dev|stage|prod]`
+
+    View all running deployments in a specified environment.
+
+- `k describe deploy [deploy name]`
+
+    View a description of a deploy. Useful for when the deploy's pods are failing to startup, thus not showing any logs.
+
+- `k rollout restart deploy/[deploy name]`
+
+    Manually restart a deployment.
+
+#### Helm Charts
+
+- `h list`
+
+    List helm chart releases. A release is an installed instance of a chart.