feat(module): added support for private container registries

docs/client.md

@@ -1,3 +1,8 @@
+# Skaha Client
+
+The `skaha.client` module provides a client for the Skaha server. The client is based of the
+`Requests` library and provides a simple interface to the Skaha server. The client configures the
+authorization headers for user authentication and container registry access.
 
 ::: skaha.client.SkahaClient
     handler: python
@@ -10,4 +15,4 @@
     rendering:
       show_root_heading: true
       show_source: true
-      heading_level: 2
+      heading_level: 2

docs/examples.md

@@ -2,14 +2,17 @@
 
 ## Session API
 
-The bread and butter of Skaha is the Session API. This API allows you to create, destroy, and get information about your sessions on the Skaha platform.
+The bread and butter of Skaha is the Session API. This API allows you to create, destroy, and get information about your sessions on the CANFAR Science Platform.
 
 ### Creating a Session
 
 ```python title="Create a session"
 from skaha.session import Session
 
 session = Session()
+```
+
+```python title="Spawn a session"
 session_id = session.create(
     name="test",
     image="images.canfar.net/chimefrb/testing:keep",
@@ -30,6 +33,21 @@ print(session_id)
 ["mrjdtbn9", "ov6doae7", "ayv4553m"]
 ```
 
+!!! note "Container Replicas"
+    When spawning sessions with the Skaha API, it adds two additional environment variables to each container:
+        - `REPLICA_COUNT`: An integer representing the total number of replicas spawned, e.g. 2.
+        - `REPLICA_ID`: An integer representing the ID of the replica, e.g. 0, 1, 2.
+
+!!! note "Container Registry Access"
+    If you are using a private container image from the CANFAR Harbor Registry, you need to provide your harbor `username` and the `CLI Secret` through a `ContainerRegistry` object.
+    ```python
+    from skaha.models import ContainerRegistry
+    from skaha.session import Session
+
+    registry = ContainerRegistry(username="username", password="sUp3rS3cr3t")
+    session = Session(registry=registry)
+    ```
+
 ### Getting Session Information
 
 ```python title="Get session information"
@@ -90,7 +108,8 @@ session.destroy(session_id)
 
 ## Image API
 
-The Image API allows you to get information about the images available on the Skaha platform. Nominally, 
+The Image API allows you to get information about the **publicly available** images on the CANFAR Science Platform through
+the CANFAR Harbor Registry.
 
 ### Getting Image Information
 

docs/get-started.md

@@ -1,79 +1,60 @@
 # Get Started
 
-### Installation (Quick Start)
+## Installation (Quick Start)
 
 !!! note ""
 
-    Skaha requires Python 3.7 or higher.
+    Skaha requires Python 3.8+.
 
 !!! code ""
 
     ```bash
     pip install skaha
     ```
 
-### Before you start
+## Before you Begin
 
-Before you can use skaha, you need to have a valid CANFAR account and have access to the Skaha Science Platform.
-If you don't have a CANFAR account, you can register for one [here](https://canfar.net). Once you have a CANFAR account,
-you can request access to the Skaha Science Platform from CANFAR Personel.
+Before you can use the Skaha python package, you need a valid CANFAR account and access to the Skaha Science Platform.
+To create a new account, you can register [here](https://canfar.net).
 
 ### Authentication
 
-Skaha uses a X509 security certificate for interactions with the CANFAR Science Platform. You need to have a valid certificate
-in order to use skaha.
+Skaha uses a X509 security certificate for interactions with the CANFAR Science Platform.
+You need to have a valid certificate in order to authenticate with the platform.
 
 #### Generating a certificate
 
-When you install skaha, a command line tool called `cadc-get-cert` is also installed. This tool can be used to generate
-a certificate for you. You can run the following command to generate a certificate:
+Installing the skaha package will also install a command line tool called `cadc-get-cert`.
+This tool can be used to generate a certificate with the following command:
 
-```bash title="Generate a certificate"
-cadc-get-cert -u <your-username>
-Password: <your-password>
+    ```bash
+    cadc-get-cert -u <your-username>
+    Password: <your-password>
 
-DONE. 10 day certificate saved in /home/<your-username>/.ssl/cadcproxy.pem
-```
+    DONE. 10 day certificate saved in /home/<your-username>/.ssl/cadcproxy.pem
+    ```
 
 This will generate a certificate for you and store it in `~/.ssl/cadcproxy.pem`. 
 
-By default, skaha will only look at the `$HOME/.ssl/cadcproxy.pem` location for your certificate. 
-If you want to use a different location, you can pass the path to the certificate to any Skaha Object when you create it.
-
-```python title="Using a different certificate location"
-from skaha.session import Session
-
-session = Session(certificate="/path/to/certificate.pem")
-```
-
-### Contributing
+By default, skaha looks at the location `$HOME/.ssl/cadcproxy.pem` for your certificate. 
+Alternatively, you can specify the location of your certificate when creating a new session.
 
-We use [poetry](https://python-poetry.org/) to manage our dependencies. To install poetry, run the following command:
+    ```python
+    from skaha.session import Session
 
-```bash title="Install poetry"
-pip install poetry>=1.2.2
-```
-
-Now you can get started to contribute to skaha:
-
-```bash title="Clone the repository and run tests"
-git clone https://github.com/chimefrb/skaha.git
-cd skaha
-poetry install
-poetry run pytest
-```
+    session = Session(certificate="/path/to/certificate.pem")
+    ```
 
-!!! Note "Note"
-    To run tests, you need a valid CANFAR security certificate and access to the Skaha Science Platform.
+### Container Registry Access
 
-#### Pre-commit
+In order to access private container images from the CANFAR Harbor Registry, you need to provide your harbor `username` and the `CLI Secret` through a `ContainerRegistry` object.
 
-We have a configuration file for [pre-commit](https://pre-commit.com/) that will run a series of checks on your code before
-you commit it. To install pre-commit, run the following command:
+    ```python
+    from skaha.models import ContainerRegistry
+    from skaha.session import Session
 
-```bash title="Install pre-commit"
-poetry run pre-commit install
-```
+    registry = ContainerRegistry(username="username", password="sUp3rS3cr3t")
+    session = Session(registry=registry)
+    ```
 
-### Licensing
-This code is licensed under the [MIT License](https://en.wikipedia.org/wiki/MIT_License). See the [LICENSE](https://github.com/CHIMEFRB/skaha/blob/main/LICENSE) file for more information.
+Passing the `ContainerRegistry` object passes the base64 encoded `username:secret` to the Skaha server for authentication under the `X-Skaha-Registry-Auth` header.

docs/index.md

@@ -1,7 +1,20 @@
 # Skaha
 
 !!! note ""
-    A lightweight pythonic interface to the CANFAR Science Platform.
+
+    A lightweight python interface to the CANFAR Science Platform.
+
+??? Tip "Support for Private Container Images on Harbor"
+
+    Starting October 2024, to create a session with a private container image from the [CANFAR Harbor Registry](https://images.canfar.net/), you will need to provide your harbor `username` and the `CLI Secret` through a `ContainerRegistry` object. 
+
+    ```python
+    from skaha.models import ContainerRegistry
+    from skaha.session import Session
+
+    registry = ContainerRegistry(username="username", password="sUp3rS3cr3t")
+    session = Session(registry=registry)
+    ```
 
 !!! example "Example"
 
@@ -11,13 +24,13 @@
     session = Session()
     session_id = session.create(
         name="test",
-        image="images.canfar.net/chimefrb/alpine:keep",
+        image="images.canfar.net/skaha/base-notebook:latest",
         cores=2,
         ram=8,
         gpu=1,
         kind="headless",
         cmd="env",
-        env={"TEST": "test"},
+        env={"KEY": "VALUE"},
         replicas=3,
     )
     ```