Merge pull request #44 from ASFOpenSARlab/dev

Add MFA docs and make various environment updates
ASFOpenSARlab · Feb 9, 2024 · d1c5e56 · d1c5e56
2 parents 24278a8 + 2f3c296
commit d1c5e56
Show file tree

Hide file tree

Showing 49 changed files with 759 additions and 335 deletions.
diff --git a/.github/workflows/deploy_to_github_io.yml b/.github/workflows/deploy_to_github_io.yml
@@ -10,18 +10,18 @@ jobs:
     name: Build site and deploy
     runs-on: "ubuntu-latest"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           path: opensarlab-docs
 
-      - uses: conda-incubator/setup-miniconda@v2
+      - uses: conda-incubator/setup-miniconda@v3
         with:
           auto-update-conda: true
-          python-version: 3.8
+          python-version: 3.9
           activate-environment: opensarlab-docs
           environment-file: opensarlab-docs/environment.yml
 
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           repository: ASFOpenSARlab/ASFOpenSARlab.github.io
           path: ASFOpenSARlab.github.io

diff --git a/.github/workflows/deploy_to_github_io_dev.yml b/.github/workflows/deploy_to_github_io_dev.yml
@@ -10,14 +10,14 @@ jobs:
     name: Build site and deploy
     runs-on: "ubuntu-latest"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           path: opensarlab-docs
 
-      - uses: conda-incubator/setup-miniconda@v2
+      - uses: conda-incubator/setup-miniconda@v3
         with:
           auto-update-conda: true
-          python-version: 3.8
+          python-version: 3.9
           activate-environment: opensarlab-docs
           environment-file: opensarlab-docs/environment.yml
 

diff --git a/docs/assets/code_cell.gif b/docs/assets/code_cell.gif
diff --git a/docs/assets/create_conda_env.gif b/docs/assets/create_conda_env.gif
diff --git a/docs/assets/hide_all_cells.gif b/docs/assets/hide_all_cells.gif
diff --git a/docs/assets/hide_one_cell.gif b/docs/assets/hide_one_cell.gif
diff --git a/docs/assets/kernel_restart.PNG b/docs/assets/kernel_restart.PNG
diff --git a/docs/assets/kernel_usage.PNG b/docs/assets/kernel_usage.PNG
diff --git a/docs/assets/magic_capture.PNG b/docs/assets/magic_capture.PNG
diff --git a/docs/assets/magic_df.PNG b/docs/assets/magic_df.PNG
diff --git a/docs/assets/magic_excl.PNG b/docs/assets/magic_excl.PNG
diff --git a/docs/assets/magic_inline.PNG b/docs/assets/magic_inline.PNG
diff --git a/docs/assets/magic_js.PNG b/docs/assets/magic_js.PNG
diff --git a/docs/assets/magic_widget.PNG b/docs/assets/magic_widget.PNG
diff --git a/docs/assets/markdown_cell_edit_mode.gif b/docs/assets/markdown_cell_edit_mode.gif
diff --git a/docs/assets/markdown_run.gif b/docs/assets/markdown_run.gif
diff --git a/docs/assets/multi_download.gif b/docs/assets/multi_download.gif
diff --git a/docs/assets/open_terminal.gif b/docs/assets/open_terminal.gif
diff --git a/docs/assets/opensciencelab.PNG b/docs/assets/opensciencelab.PNG
diff --git a/docs/assets/restart_option.PNG b/docs/assets/restart_option.PNG
diff --git a/docs/assets/run_above.gif b/docs/assets/run_above.gif
diff --git a/docs/assets/run_cell.gif b/docs/assets/run_cell.gif
diff --git a/docs/assets/run_in_batch.gif b/docs/assets/run_in_batch.gif
diff --git a/docs/assets/running_multi.PNG b/docs/assets/running_multi.PNG
diff --git a/docs/assets/running_once.PNG b/docs/assets/running_once.PNG
diff --git a/docs/assets/select_cell.gif b/docs/assets/select_cell.gif
diff --git a/docs/assets/select_cell_non_edit_mode.gif b/docs/assets/select_cell_non_edit_mode.gif
diff --git a/docs/assets/select_kernel.gif b/docs/assets/select_kernel.gif
diff --git a/docs/assets/select_mult_cells.gif b/docs/assets/select_mult_cells.gif
diff --git a/docs/assets/single_sign_on.PNG b/docs/assets/single_sign_on.PNG
diff --git a/docs/assets/user_request.PNG b/docs/assets/user_request.PNG
diff --git a/docs/release-notes/release_02-2023.md b/docs/release-notes/release_02-2023.md
@@ -0,0 +1,79 @@
+# Welcome to the February 2023 OpenScienceLab Update!
+
+### Changes:
+- [OpenScienceLab](#opensciencelab)
+- [Single Sign On](#single-sign-on)
+- [Automatic Authentication](#automatic-authentication)
+- [User Access](#user-access)
+- [IP Filter](#ip-filter)
+- [User Request]()
+- [Multi Download](#multi-download)
+- [Kernel Usage](#kernel-usage)
+- [Recommended Jupyter Notebook Changes](#recommended-jupyter-notebook-changes)
+
+---
+
+## **OpenScienceLab**
+
+- OpenSARLab is now a part of OpenScienceLab with significant changes. Users can access different courses from a single page.
+
+![opensciencelab front page](../assets/opensciencelab.PNG)
+
+## **Single Sign On**
+
+- New single sign-on (SSO) to simplify the logging-in process. SSO eliminates the burden of the sign-on process by listing all accounts on a single web page with additional layers of security.
+
+![sso page](../assets/single_sign_on.PNG)
+
+## **Automatic Authentication**
+- Users who sign up to the OpenScienceLab no longer need admins to activate their accounts.
+
+## **User Access**
+- Admins can easily give users access to different profiles from a single page. Admins can toggle access lists based on various deployments.
+
+## **IP Filter**
+
+- OpenScienceLab will prevent users in one of NASA’s [designated countries list](https://www.nasa.gov/sites/default/files/atoms/files/designated_country_list_6.10.2022.pdf) from creating an account so that we are compliant with NASA’s security protocol.
+
+## **User Request**
+- Users can send a request to the OpenScienceLab team from the portal. 
+
+![user request](../assets/user_request.PNG)
+
+
+## **Multi Download**
+- Users can download multiple files at once through OpenScienceLab.
+- **NB**: Downloading multiple directories requires users to compress the directories beforehand.
+
+![multi download](../assets/multi_download.gif)
+
+## **Kernel Usage**
+- The latest update of JupyterLab has a built-in kernel monitor that tracks detailed resource usage, such as:
+  - Kernel Host
+  - Memory consumption and availability
+  - CPU usage
+
+
+![kernel usage](../assets/kernel_usage.PNG)
+
+## **Recommended Jupyter Notebook Changes**
+
+The following bullet points cover code changes you may need to make to your notebooks for them to work in JupyterLab:
+
+- MintPy Update:
+
+    Due to the recent MintPy update, import syntax for version 1.4.1+ differs from previous versions. As a result, some notebooks may be incompatible with the latest version of MintPy. Below are examples of how to import MintPy depending on which versions you have:
+
+    ``` python
+    # version 1.4.0 and below:
+    import mintpy.view as view
+    import mintpy.tsview as tsview
+    .
+    .
+    .
+
+    # version 1.4.1+
+    from mintpy.cli import view, tsview, ...        
+    ```
+
+For additional backward compatibility changes, please refer to the previous release notes.
diff --git a/docs/release-notes/release_02-2024.md b/docs/release-notes/release_02-2024.md
@@ -0,0 +1,14 @@
+# Welcome to the February 2024 OpenScienceLab Update!
+
+### Changes:
+
+- [Multi-Factor Authentication](#multi-factor-authentication)
+
+---
+
+## **Multi-Factor Authentication**
+
+- OpenScienceLab now requires users to set up Multi-Factor Authentication (MFA)
+to access OpenScienceLab resources. Directions on how to do so, as well as
+troubleshooting recommendations, can be found on the new
+[MFA documentation page](../user-guides/mfa.md)
diff --git a/docs/release_notes.md b/docs/release_notes.md
@@ -1,3 +1,5 @@
 1. [June 2021](release-notes/release_06-2021.md)
 1. [October 2021](release-notes/release_10-2021.md)
 1. [February 2022](release-notes/release_02-2022.md)
+1. [February 2023](release-notes/release_02-2023.md)
+1. [February 2024](release-notes/release_02-2024.md)
diff --git a/docs/user-guides/OpenSARlab_environment.md b/docs/user-guides/OpenSARlab_environment.md
@@ -1,35 +1,49 @@
 [Return to Table of Contents](../user.md)
 
-# The OpenSARlab Environment and Account Lifecycle
-## Account Lifecycle
+# **The OpenScienceLab Environment and the Account Lifecycle**
+
+## **Account Lifecycle**
 - Accounts will be deactivated on the **46th** day of inactivity.
-- Warning emails are sent to inactive users after **30**, **37**, **41**, **43**, and **45** days.
+- Warning emails are sent to inactive users after **30**, **35**, **40**, **44**, and **45** days.
 - The user volume and snapshot are **permanently destroyed** upon account deactivation.
 
+**NB**: _While the above is valid for the **OpenSARLab** deployment, each deployment's lifecycle period may differ. Since the **OpenSARLab** is the most commonly used deployment, the information listed on this page will mainly focus on the **OpenSARLab** deployment._
+
 ---
 
-## OpenSARlab Environment
-Every OpenSARlab user has access to an Amazon AWS EC2 instance. Individual instances are shared among groups of 1 - 3 users, depending on demand.
+## **OpenSARLab Environment**
+Every OpenSARLab user has access to an Amazon AWS EC2 instance. Depending on demand, the individual user shares their resources with up to 3 users.
+
+### **Operating System**
 
-#### Operating System
 - Ubuntu 20.04.3 LTS
 
-<!--  should we include EBS snapshot -->
-#### Volume (storage)
-OpenSARlab uses [Amazon AWS EBS volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes.html), which are mounted on user servers' home directories for storage. A [snapshot](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSSnapshots.html) of each volume is taken everyday at 10:00 UTC. Only the most recent snapshot is retained. Any volumes unused for two days are destroyed, with the latest snapshot retained as a backup. 
+### **Volume (storage)**
+
+- *500GB of EBS volume storage per user. 
 
-**If a volume has been destroyed, a new EBS volume is created upon the next login, and it is populated with data from the snapshot.** While the volume is created and becomes usable very quickly, populating it with data from the snapshot can take some time (tens of minutes) and users may notice that notebooks load slowly during this period. 
+*_Volume size subject to change_.
 
-The important takeaway is that user storage is persistent; you will not lose saved work unless your account is deactivated after 46 days of non-use.
+OpenSARLab uses [Amazon AWS EBS volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes.html) mounted on user servers' home directories for storage. Since volumes are costly to maintain, any inactive accounts will have their volumes destroyed and replaced with the latest [snapshot](#snapshot-backup) as a backup within a few days.
 
-It is users' responsibility to manage their storage. Using up all your storage space will prevent you from logging into OpenSARlab. Please contact an [OpenSARlab administrator](mailto:[email protected]) if this occurs. 
+#### _**Important Notes about Volume**_
 
-- 500GB Amazon AWS EBS volume (volume size subject to change) allocated to each user. 
+- **If your volume has been destroyed, the latest snapshot will regenerate a new EBS volume upon the next login. Upon successful login, your account should be identical from your previous session.**
+- When regenerating the volume from the snapshot, it can take some time (10+ minutes) to restore all the data. Notebooks may load slower than usual during this period.
+- If users occupy more space than allocated, it will trigger the `out-of-storage exception` that will prevent users from logging in.
+    - It is the users' responsibility to manage their storage. Please contact an [OpenScienceLab administrator](mailto:[email protected]) if you need help logging in.
 
-#### Memory (RAM)
-EC2 instances are shared among users. This happens behind the scenes and is generally not noticeable when using OpenSARlab, with the exception of memory availability. The amount of memory available to each user depends on overall use of an instance, and may vary from 6GB to 16GB.
+### **Snapshot (Backup)**
+
+A [snapshot](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSSnapshots.html) is a backup copy of users' volume. The snapshot of each volume is taken every day at 10:00 UTC. Only the most recent snapshot is retained. 
+
+**The user storage is persistent; you will only lose saved work if your account is inactive for 46 days.**
+
+### **Memory (RAM)**
 
 - RAM allocated per user: 6GB - 16GB 
 
-#### Privileges
-- Users do not have root privileges (*i.e.* no `sudo`).
+The amount of memory available to each user depends on the overall instance and may vary from 6 GB to 16 GB. The number of users on the same instance determines the amount of usable memory.
+
+### **Privileges**
+- Users do not have `root` (i.e., `sudo`) privileges.
diff --git a/docs/user-guides/OpenSARlab_terminal.md b/docs/user-guides/OpenSARlab_terminal.md
@@ -1,34 +1,39 @@
 [Return to Table of Contents](../user.md)
 
-# Using the Terminal in OpenSARlab
+# **Using the Terminal in OpenSARlab**
 
-## Open a Terminal
+## Overview
+---
+
+Users sometimes need to use an interactive shell to organize their accounts. With OpenSceinceLab’s built-in terminal, users can use an interactive shell to accomplish their tasks.
 
-### In JupyterLab
+## **How to Open a Terminal**
+---
 
-1. If there is no `Launcher` tab in you workspace, open one by clicking the blue `+` button at the upper left of the screen.
+1. If there is no `Launcher` tab in your workspace, open one by clicking the blue `+` button at the upper left of the screen.
 
 ![If there is no Launcher tab in you workspace, open one by clicking the blue + button at the upper left of the screen](../assets/launcher.png)
 
-1. Click the `Terminal` button in a `Launcher` tab.
+1. Click the `Terminal` button in the `Launcher` tab.
 
 ![Click the Terminal button in a `Launcher` tab.](../assets/jlab_terminal.png)
 
-### In Jupyter Notebook
-![Opening a terminal with the "New" menu in the JupyterHub GUI file manager.](../assets/open_terminal.png)
+*Live Example*:
 
-*Select **Terminal** from the **New** menu in the JupyterHub file manager*
+![open terminal live](../assets/open_terminal.gif)
 
 ---
 
-## Use the Terminal
-![An open terminal window.](../assets/terminal.png)
+## **How to Use the Terminal**
 
-*Use the command line as you would in any other Linux terminal*
+Use the command line as you would in any other `Unix-like` terminal.
+
+![An open terminal window.](../assets/terminal.png)
 
 ---
 
-## No Root Privileges
-![An open terminal window with unsuccessful attempt to use sudo.](../assets/no_sudo.png)
+## **No Root Privileges**
+
+Because the `jovyan` does not have a password, OpenScienceLab users cannot use the `sudo` command.
 
-*OpenSARlab users do not have `sudo` privileges (`jovyan` does not have a password).*
+![An open terminal window with unsuccessful attempt to use sudo.](../assets/no_sudo.png)
diff --git a/docs/user-guides/conda_environments.md b/docs/user-guides/conda_environments.md
@@ -2,19 +2,31 @@
 
 # Creating and Using Conda Environments in OpenSARlab
 
-OpenSARlab comes with a default base conda environment with a minimum amount of software installed. Users must create their own conda environments to run Jupyter Notebooks or Python scripts.
+OpenScienceLab comes with a default `base` conda environment with a minimum amount of software installed. Users must create their own conda environments to run Jupyter Notebooks or Python scripts.
 
-The following 5 conda environments are provided by ASF to run the notebooks in our library:
+The following conda environments are by ASF to run the notebooks in our library:
 
-1. rtc_analysis
-1. insar_analysis
-1. train
-1. hydrosar
-1. machine learning
+- `rtc_analysis`
+- `insar_analysis`
+- `train`
+- `hydrosar`
+- `machine learning`
+- `autorift`
+- `nisar_se`
+- `unavco`
 
-However, these environments are not pre-built and must be created by each user. We have provided a notebook to help install conda environments located at the following path: `/home/jovyan/conda_environments/Create_OSL_Conda_Environments.ipynb`
+However, these environments are not pre-built; users must create the desired conda environments. We have provided a notebook to help install conda environments located at the following path:
+`/home/jovyan/conda_environments/Create_OSL_Conda_Environments.ipynb`
 
-Users can also create their own custom conda environments in OpenSARlab and use them to run Jupyter Notebooks. Use the notebook located here to complete the process: `/home/jovyan/opensarlab_docs/OpenSARlab_supplements/Jupyter_Conda_Environments.ipynb`
+Here is a live demonstration on how to build the conda environment.
+
+![Create Conda Env](../assets/create_conda_env.gif)
+
+Your environment will be ready after running the last cell.
+
+**NB**: It may take a while to generate your conda environment.
+
+<!-- Users can also create their own custom conda environments in OpenSARlab and use them to run Jupyter Notebooks. Use the notebook located here to complete the process: `/home/jovyan/opensarlab_docs/OpenSARlab_supplements/Jupyter_Conda_Environments.ipynb` -->
 
 <!-- conda env create -f environment.yml