Merge pull request #4 from jnywong/docs

Initial docs

Author: jnywong

.gitignore

@@ -1 +1,3 @@
-**/__pycache__
+**/__pycache__
+# MyST build outputs
+_build

CONTRIBUTING.md

@@ -57,4 +57,8 @@ This will set up the hooks defined in `.pre-commit-config.yaml` to run automatic
 
 ## Chartpress
 
-Helm charts are automatically published with [Chartpress](https://github.com/jupyterhub/chartpress) and hosted at [2i2c.org/jupyterhub-cost-monitoring](https://2i2c.org/jupyterhub-cost-monitoring/). Images are hosted at [Quay.io](https://quay.io/repository/2i2c/jupyterhub-cost-monitoring).
+Helm charts are automatically published with [Chartpress](https://github.com/jupyterhub/chartpress) and hosted at [2i2c.org/jupyterhub-cost-monitoring](https://2i2c.org/jupyterhub-cost-monitoring/).
+
+Images are hosted at [Quay.io](https://quay.io/repository/2i2c/jupyterhub-cost-monitoring).
+
+See the configuration in the [`chartpress.yaml`](https://github.com/2i2c-org/jupyterhub-cost-monitoring/blob/main/chartpress.yaml) file for more details.

docs/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing
+
+Please refer to [Project Jupyter's Code of Conduct](https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md) for guidelines on fostering a friendly and collaborative environment.
+
+## Setting up a local development environment
+
+This project uses the Python package manager `uv`. Below are the steps to set up a local development environment.
+
+1. Clone this repository
+
+  ```bash
+  git clone https://github.com/2i2c-org/jupyterhub-cost-monitoring.git
+  ```
+
+1. Install `uv`
+
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+1. Install project dependencies and source the `.venv` environment
+
+   ```bash
+   uv sync
+   source .venv/bin/activate
+   ```
+
+1. Authenticate with [AWS credentials](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html) (requires [AWS CLI installation](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)). This example uses a [session token](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) from an MFA code associated with an MFA device:
+
+  ```bash
+  export AWS_PROFILE=<aws-profile-name>
+  export CLUSTER_NAME=<cluster-name>
+  export MFA_DEVICE_ID=<mfa-device-id>
+  aws sts get-session-token --serial-number $MFA_DEVICE_ID --profile $AWS_PROFILE --token-code ******
+  ```
+
+1. Run the Flask web server
+
+   ```bash
+   cd src/jupyterhub_cost_monitoring
+   flask run --port=8080
+   ```
+
+1. Visit [http://127.0.0.1:8080](http://127.0.0.1:8080) to view the application.
+
+If you need to add or update dependencies, follow the guidance in [Working on projects | uv](https://docs.astral.sh/uv/guides/projects/#managing-dependencies)
+
+## Pre-commit
+
+This project uses [pre-commit](https://pre-commit.com/) to manage pre-commit hooks. To install the pre-commit hooks, run:
+
+```bash
+pre-commit install
+```
+
+This will set up the hooks defined in `.pre-commit-config.yaml` to run automatically on `git commit`.
+
+## Chartpress
+
+Helm charts are automatically published with [Chartpress](https://github.com/jupyterhub/chartpress) and hosted at [2i2c.org/jupyterhub-cost-monitoring](https://2i2c.org/jupyterhub-cost-monitoring/).
+
+Images are hosted at [Quay.io](https://quay.io/repository/2i2c/jupyterhub-cost-monitoring).
+
+See the configuration in the [`chartpress.yaml`](https://github.com/2i2c-org/jupyterhub-cost-monitoring/blob/main/chartpress.yaml) file for more details.

docs/README.md

@@ -0,0 +1,49 @@
+# jupyterhub-cost-monitoring
+
+Cloud cost monitoring is moving beyond just preventing runaway cost explosions – it’s about empowering JupyterHub administrators with the guardrails they need to run efficient, transparent, and sustainable infrastructures. A cloud cost bill can show a broad view of services and machines provisioned, but how can we provide granular insights into each user and the value they are deriving from the hub on an application level?  
+
+This tool provides a per-user cost reporting system for JupyterHubs running on AWS, enabling hub administrators to monitor and report the costs associated with each user. This approach delivers cloud observability and cost transparency that can be reliably deployed using Kubernetes and integrated with Zero to JupyterHub distributions.
+
+## Features
+
+1. Metric Collection – Prometheus collects resource usage metrics (including CPU, memory, and storage) from individual user pods via standard and custom exporters.
+2. Cost Estimation – Usage is correlated with AWS cost data to estimate per-user costs.
+3. Visualization – Grafana dashboards display rich, interactive views of usage and cost data, making it easy to monitor trends, identify high-cost workloads, and generate reports for funders and decision-makers.
+
+## Installation
+
+This project is designed to be compatible with Zero to JupyterHub distributions, making it easy to deploy in the cloud with Kubernetes.
+
+Add this project as a subchart of the z2jh `Chart.yaml` file with
+
+```yaml
+dependencies:
+  - name: jupyterhub-cost-monitoring
+    version: "<version-number>"
+    repository: "https://2i2c.org/jupyterhub-cost-monitoring/"
+    condition: jupyterhub-cost-monitoring.enabled
+```
+
+In the values file, enable the cost monitoring chart for your Kubernetes cluster:
+
+```yaml
+jupyterhub-cost-monitoring:
+  enabled: true
+  extraEnv:
+    - name: CLUSTER_NAME
+      value: "<name-of-cluster>"
+```
+
+## Contributing
+
+Contributions to the `jupyterhub-cost-monitoring` project are welcome! Please follow the standard GitHub workflow:
+
+1. Fork the repository.
+2. Create a feature branch.
+3. Submit a pull request.
+
+Please refer to [`CONTRIUBUTING.md`](CONTRIBUTING.md) for more details.
+
+## License
+
+This project is licensed under the [BSD 3-Clause License](LICENSE).

docs/architecture.md

@@ -0,0 +1,22 @@
+# Architecture
+
+This document outlines the architecture of the project, including its dependencies, their interactions, and the overall design principles.
+
+## Overview
+
+![images/diagram.jpg](images/diagram.jpg)
+
+:::{note}
+The diagram above is a temporary placeholder. The highlighted arrow indicates the key usage metrics pulled from the Prometheus server for the [per-user cost weightings](https://hackmd.io/@jnywong/HJB8ewSree#Compute-component).
+:::
+
+Cost data is exposed with `jupyterhub-cost-monitoring` via a Flask web application that serves as an endpoint for other applications in the cluster. The following endpoints are available:
+
+- `/index`: Returns all available endpoints.
+- `/ready`: Returns a 200 OK response if the application is ready to serve requests.
+- `hub_names`: Returns a list of all JupyterHub names in the cluster.
+- `total_costs`: Returns daily total costs and divided into two types:
+  - *Account*: The total costs as reported by the cloud provider.
+  - *Attributable*: The total costs that can be attributed by the `jupyterhub-cost-monitoring` application. For example, the act of querying the totals costs reported by cloud provider incurs a cost and is not included in *attributable* costs but is included in *account* costs.
+- `total_costs_per_hub`: Returns the daily total costs per hub listed in `hub_names`.
+- `total_costs_per_component`: Returns the daily total costs per cloud component.

docs/images/diagram.jpg

@@ -0,0 +1,15 @@
+# See docs at: https://mystmd.org/guide/frontmatter
+version: 1
+project:
+  id: e3df9ec3-12eb-4ef1-a8e6-0c4b4d8de40f
+  # title:
+  # description:
+  # keywords: []
+  # authors: []
+  github: https://github.com/2i2c-org/jupyterhub-cost-monitoring
+  # To autogenerate a Table of Contents, run "myst init --write-toc"
+site:
+  template: book-theme
+  # options:
+  #   favicon: favicon.ico
+  #   logo: site_logo.png

docs/myst.yml

@@ -11,5 +11,6 @@ dependencies = [
 
 [dependency-groups]
 dev = [
+    "mystmd>=1.6.0",
     "ruff>=0.12.5",
 ]