Merge pull request #23 from aisingapore/0.3.0-local-docs

0.3.0 local docs
aisingapore · Feb 22, 2024 · 0610e33 · 0610e33
2 parents 947b329 + f82d5db
commit 0610e33
Show file tree

Hide file tree

Showing 13 changed files with 539 additions and 201 deletions.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -43,8 +43,8 @@ theme:
 
 # Page Tree
 nav:
-  - Home: index.md
   - User Guide:
+    - Overview: index.md
     - Prerequisites: guide-for-user/01-prerequisites.md
     - Preface: guide-for-user/02-preface.md
     - MLOps Components & Platform: guide-for-user/03-mlops-components-platform.md

diff --git a/...kiecutter.repo_name}}/aisg-context/guide-site/docs/guide-for-user/02-preface.md b/...kiecutter.repo_name}}/aisg-context/guide-site/docs/guide-for-user/02-preface.md
@@ -27,13 +27,13 @@ After creating the remote repository, retrieve the remote URL and push
 the local repository to remote:
 
 ```bash
-$ git init
-$ git remote add origin <REMOTE_URL>
-$ git add .
-$ git config user.email "<YOUR_AISG_EMAIL>"
-$ git config user.name "<YOUR_NAME>"
-$ git commit -m "Initial commit."
-$ git push -u origin main
+git init
+git remote add origin <REMOTE_URL>
+git add .
+git config user.email "<YOUR_AISG_EMAIL>"
+git config user.name "<YOUR_NAME>"
+git commit -m "Initial commit."
+git push -u origin main
 ```
 
 Go to [this section][gitlab-page] for more information on interacting 

diff --git a/...e}}/aisg-context/guide-site/docs/guide-for-user/03-mlops-components-platform.md b/...e}}/aisg-context/guide-site/docs/guide-for-user/03-mlops-components-platform.md
@@ -54,9 +54,9 @@ A simple command to authorise access:
 
 ```bash
 # For authorisation with user account
-$ gcloud auth login
+gcloud auth login
 # For authorisation with service account
-$ gcloud auth login --cred-file=/path/to/service-account-key.json
+gcloud auth login --cred-file=/path/to/service-account-key.json
 ```
 
 With your user account, you should have access to the following GCP
@@ -544,23 +544,33 @@ for authentication. We first have to download the CLI.
 
 To verify your installation, you may run the following command:
 
- ```bash
- $ runai version
- Version: 2.XX.XX
- BuildDate: YYYY-MM-DDThh:mm:ssZ
- GitCommit: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- GoVersion: goX.XX.X
- Compiler: gc
- ```
+```bash
+runai version
+```
+
+You should see an output similar to this:
+
+```
+Version: 2.XX.XX
+BuildDate: YYYY-MM-DDThh:mm:ssZ
+GitCommit: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+GoVersion: goX.XX.X
+Compiler: gc
+```
 
 Now that the CLI has been successfully installed, you can use it to
 authenticate with the Run:ai cluster.
 
 === "Linux/macOS"
 
     ```bash
-    $ export KUBECONFIG=/path/to/provided/kubeconfig
-    $ runai login
+    export KUBECONFIG=/path/to/provided/kubeconfig
+    runai login
+    ```
+
+    You should see an interactive prompt similar to this:
+
+    ```
     Go to the following link in your browser:
             https://app.run.ai/auth/realms/aisingapore/protocol/openid-connect/auth?access_type=offline&client_id=runai-cli&redirect_uri=https%3A%2F%2Faisingapore.run.ai%2Foauth-code&response_type=code&scope=email+openid+offline_access&state=xxxxxxx
     Enter verification code:
@@ -570,8 +580,13 @@ authenticate with the Run:ai cluster.
 === "Windows PowerShell"
 
     ```powershell
-    $ $KUBECONFIG='/path/to/provided/kubeconfig'
-    $ runai login
+    $Env:KUBECONFIG='/path/to/provided/kubeconfig'
+    runai login
+    ```
+
+    You should see an interactive prompt similar to this:
+
+    ```
     Go to the following link in your browser:
             https://app.run.ai/auth/realms/aisingapore/protocol/openid-connect/auth?access_type=offline&client_id=runai-cli&redirect_uri=https%3A%2F%2Faisingapore.run.ai%2Foauth-code&response_type=code&scope=email+openid+offline_access&state=xxxxxxx
     Enter verification code:
@@ -618,7 +633,12 @@ While Harbor has its own front-end interface, one may use the Docker CLI
 to interact with the registry.
 
 ```bash
-$ docker login registry.aisingapore.net
+docker login registry.aisingapore.net
+```
+
+You should have an interactive prompt similar to this:
+
+```
 Username: <YOUR_USERNAME_HERE>
 Password:
 Login Succeeded!
@@ -729,7 +749,12 @@ To list the buckets that a profile as access to, you may run a command
 similar to the following:
 
 ```bash
-$ aws --profile profile-1 --endpoint-url="https://necs.nus.edu.sg" s3 ls
+aws --profile profile-1 --endpoint-url="https://necs.nus.edu.sg" s3 ls
+```
+
+With a similar output to this:
+
+```
 YYYY-MM-DD hh:mm:ss bucket-1
 YYYY-MM-DD hh:mm:ss bucket-2
 ```
@@ -773,15 +798,15 @@ used to store and version our Docker images. Following authorisation to
 `gcloud`, you can view the image repositories of your project's registry 
 like so:
 ```bash
-$ gcloud container images list --repository={{cookiecutter.registry_project_path}}
+gcloud container images list --repository={{cookiecutter.registry_project_path}}
 ```
 
 To push or pull images to/from Artifact Registry, you would need to
 authenticate with the Google Cloud project that the registry is
 associated with. You can do so by running the following command:
 
 ```bash
-$ gcloud auth configure-docker asia-southeast1-docker.pkg.dev
+gcloud auth configure-docker asia-southeast1-docker.pkg.dev
 ```
 
 The command above will populate your Docker configuration file with
@@ -816,7 +841,7 @@ may list the contents of a bucket like so:
     team. The team is reachable at `[email protected]`.
 
 ```bash
-$ gsutil ls -p <GCP_PROJECT_ID> gs://<GCS_BUCKET_NAME>
+gsutil ls -p <GCP_PROJECT_ID> gs://<GCS_BUCKET_NAME>
 ```
 
 ??? info "Reference Link(s)"
@@ -876,27 +901,27 @@ MLflow Tracking server.
 === "Linux/macOS"
 
     ```bash
-    $ conda create -n mlflow-test python=3.11.7
-    $ conda activate mlflow-test
-    $ pip install mlflow==2.9.2
+    conda create -n mlflow-test python=3.11.7
+    conda activate mlflow-test
+    pip install mlflow==2.9.2
     # Install boto3 or google-cloud-storage packages if 
     # custom object storage is used
-    $ export MLFLOW_TRACKING_USERNAME=<MLFLOW_TRACKING_USERNAME>
-    $ export MLFLOW_TRACKING_PASSWORD=<MLFLOW_TRACKING_PASSWORD>
-    $ python src/mlflow_test.py <MLFLOW_TRACKING_URI> <NAME_OF_DEFAULT_MLFLOW_EXPERIMENT>
+    export MLFLOW_TRACKING_USERNAME=<MLFLOW_TRACKING_USERNAME>
+    export MLFLOW_TRACKING_PASSWORD=<MLFLOW_TRACKING_PASSWORD>
+    python src/mlflow_test.py <MLFLOW_TRACKING_URI> <NAME_OF_DEFAULT_MLFLOW_EXPERIMENT>
     ```
 
 === "Windows PowerShell"
 
     ```powershell
-    $ conda create -n mlflow-test python=3.11.7
-    $ conda activate mlflow-test
-    $ pip install mlflow==2.9.2
+    conda create -n mlflow-test python=3.11.7
+    conda activate mlflow-test
+    pip install mlflow==2.9.2
     # Install boto3 or google-cloud-storage packages if 
     # custom object storage is used
-    $ $MLFLOW_TRACKING_USERNAME=<MLFLOW_TRACKING_USERNAME>
-    $ $MLFLOW_TRACKING_PASSWORD=<MLFLOW_TRACKING_PASSWORD>
-    $ python src/mlflow_test.py <MLFLOW_TRACKING_URI> <NAME_OF_DEFAULT_MLFLOW_EXPERIMENT>
+    $MLFLOW_TRACKING_USERNAME=<MLFLOW_TRACKING_USERNAME>
+    $MLFLOW_TRACKING_PASSWORD=<MLFLOW_TRACKING_PASSWORD>
+    python src/mlflow_test.py <MLFLOW_TRACKING_URI> <NAME_OF_DEFAULT_MLFLOW_EXPERIMENT>
     ```
 
 A successful run of the script would present you with an experiment
@@ -907,15 +932,3 @@ run that looks similar to the following:
 ??? info "Reference Link(s)"
 
     - [MLflow Docs - MLflow Tracking](https://www.mlflow.org/docs/latest/tracking.html)
-
-## Local Virtual Environments
-
-While we will be making use of AI Singapore's remote infrastructure
-to carry out some workflows, we can still make use of our local
-machine to execute some of the steps of the end-to-end machine learning
-workflow. Hence, we can begin by creating a virtual environment that
-will contain all the dependencies required for this guide.
-
-```bash
-$ conda env create -f {{cookiecutter.repo_name}}-conda-env.yaml
-```
diff --git a/...iecutter.repo_name}}/aisg-context/guide-site/docs/guide-for-user/04-dev-wksp.md b/...iecutter.repo_name}}/aisg-context/guide-site/docs/guide-for-user/04-dev-wksp.md
@@ -147,7 +147,12 @@ either method to gain access to a remote VSCode developer workspace.
     === "Linux/macOS/Windows PowerShell"
 
         ```bash
-        $ runai exec <YOUR_HYPHENATED_NAME>-vscode -p {{cookiecutter.proj_name}} -- cat /home/coder/.config/code-server/config.yaml
+        runai exec <YOUR_HYPHENATED_NAME>-vscode -p {{cookiecutter.proj_name}} -- cat /home/coder/.config/code-server/config.yaml
+        ```
+        
+        Output should be similar to this:
+
+        ```
         bind-addr: 127.0.0.1:8080
         auth: password
         password: xxxxxxxxxxxxxxxxxxxxxxxx
@@ -189,7 +194,7 @@ for the PVC:
 === "VSCode Server Terminal"
 
     ```bash
-    $ ls -la / | grep "pvc"
+    ls -la / | grep "pvc"
     ```
 
 If there's no result, check with the MLOps team about this.
@@ -202,8 +207,8 @@ be persisted.
 === "VSCode Server Terminal"
 
     ```bash
-    $ cd /<PVC_LOCATION>/workspaces
-    $ mkdir <YOUR_HYPHENATED_NAME>
+    cd /<PVC_LOCATION>/workspaces
+    mkdir <YOUR_HYPHENATED_NAME>
     ```
 
 ### Git from VSCode
@@ -223,9 +228,9 @@ Now, let's clone your repository from the remote:
 === "VSCode Server Terminal"
 
     ```bash
-    $ cd /<PVC_LOCATION>/workspaces/<YOUR_HYPHENATED_NAME>
-    $ git clone <REMOTE_URL_HTTPS>
-    $ cd {{cookiecutter.repo_name}}
+    cd /<PVC_LOCATION>/workspaces/<YOUR_HYPHENATED_NAME>
+    git clone <REMOTE_URL_HTTPS>
+    cd {{cookiecutter.repo_name}}
     ```
 
 === "Run:ai YAML"
@@ -289,26 +294,26 @@ custom image:
 === "Linux/macOS"
 
     ```bash
-    $ docker build \
+    docker build \
         -t {{cookiecutter.registry_project_path}}/vscode-server-custom:0.1.0 \
         -f docker/vscode-server/vscode-server.Dockerfile \
         --platform linux/amd64 .
-    $ docker push {{cookiecutter.registry_project_path}}/vscode-server-custom:0.1.0
+    docker push {{cookiecutter.registry_project_path}}/vscode-server-custom:0.1.0
     ```
 
 === "Windows PowerShell"
 
     ```powershell
-    $ docker build `
+    docker build `
         -t {{cookiecutter.registry_project_path}}/vscode-server-custom:0.1.0 `
         -f docker/vscode-server/vscode-server.Dockerfile `
         --platform linux/amd64 .
-    $ docker push {{cookiecutter.registry_project_path}}/vscode-server-custom:0.1.0
+    docker push {{cookiecutter.registry_project_path}}/vscode-server-custom:0.1.0
     ```
 
 ## JupyterLab
 
-!!! attention
+!!! warning "Attention"
     Setting up of a JupyterLab server is optional and not needed
     as a VSCode server is sufficient as a developer workspace.
     Resources are limited so use only what you need.
@@ -378,7 +383,12 @@ following command:
 === "Linux/macOS"
 
     ```bash
-    $ runai logs <YOUR_HYPHENATED_NAME>-jupyterlab -p  {{cookiecutter.proj_name}} | grep "lab?token"
+    runai logs <YOUR_HYPHENATED_NAME>-jupyterlab -p  {{cookiecutter.proj_name}} | grep "lab?token"
+    ```
+
+    Output should be similar to this:
+
+    ```
     [I YYYY-MM-DD hh:mm:ss ServerApp] http://<NAME_OF_WORKSPACE>-X-X:8888/lab?token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
     [I YYYY-MM-DD hh:mm:ss ServerApp]     http://127.0.0.1:8888/lab?token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
             http://<NAME_OF_WORKSPACE>-X-X:8888/lab?token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
@@ -388,7 +398,12 @@ following command:
 === "Windows PowerShell"
 
     ```powershell
-    $ runai logs <YOUR_HYPHENATED_NAME>-jupyterlab -p  {{cookiecutter.proj_name}} | Where-Object{$_ -match "lab?token"}
+    runai logs <YOUR_HYPHENATED_NAME>-jupyterlab -p  {{cookiecutter.proj_name}} | Where-Object{$_ -match "lab?token"}
+    ```
+
+    Output should be similar to this:
+
+    ```
     [I YYYY-MM-DD hh:mm:ss ServerApp] http://<NAME_OF_WORKSPACE>-X-X:8888/lab?token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
     [I YYYY-MM-DD hh:mm:ss ServerApp]     http://127.0.0.1:8888/lab?token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
             http://<NAME_OF_WORKSPACE>-X-X:8888/lab?token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
@@ -420,21 +435,21 @@ server as well as any associated files can be found under
 === "Linux/macOS"
 
     ```bash
-    $ docker build \
+    docker build \
         -t {{cookiecutter.registry_project_path}}/jupyterlab-server-custom:0.1.0 \
         -f docker/jupyterlab-server/jupyterlab-server.Dockerfile \
         --platform linux/amd64 .
-    $ docker push {{cookiecutter.registry_project_path}}/jupyterlab-server-custom:0.1.0
+    docker push {{cookiecutter.registry_project_path}}/jupyterlab-server-custom:0.1.0
     ```
 
 === "Windows PowerShell"
 
     ```powershell
-    $ docker build `
+    docker build `
         -t {{cookiecutter.registry_project_path}}/jupyterlab-server-custom:0.1.0 `
         -f docker/jupyterlab-server/jupyterlab-server.Dockerfile `
         --platform linux/amd64 .
-    $ docker push {{cookiecutter.registry_project_path}}/jupyterlab-server-custom:0.1.0
+    docker push {{cookiecutter.registry_project_path}}/jupyterlab-server-custom:0.1.0
     ```
 
 ## Using Docker within Kubernetes