Doc changes to UI deployment and dev container getting started guides (…

…#137)

.devcontainer/README.md

@@ -12,37 +12,52 @@ All configuration related to the development container is in the `.devcontainer`
 ### Setup
 
 - Install Docker Desktop or Docker CE on a host machine. The host machine can be Windows, Linux, or Mac, and can run on-premises or in the cloud.
-- Recommended: If you are using Windows for the host machine, clone and open this repository on Windows Subsystem for Linux (WSL). WSL is not required, but disk IO performance in the container is better and the overall experience is more consistent when running a development container from WSL. 
-
-    > NOTE: the Windows Git Credential Manager can be configured to work from WSL. See the [documentation here](https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-git#git-credential-manager-setup). Below is the command to run for setting the Windows credential manager in WSL:
+- Clone the Mission LZ from GitHub to a local workspace on the host machine.
+  - **Recommended:** If you are using Windows for the host machine, clone and open this repository on Windows Subsystem for Linux (WSL). WSL is not required, but disk IO performance in the container is better and the overall experience is more consistent when running a development container from WSL.
+    > **NOTE:** When using Windows with WSL as the host machine, we recommend the following additional steps:
+    >
+    > - After [installing WSL for Windows](https://docs.microsoft.com/en-us/windows/wsl/install-win10), you can run your Linux distribution path right inside PowerShell, from Windows Terminal, or in the Windows command prompt by entering `wsl.exe` or `bash.exe`. These commands will switch to a display of the Linux command line, using the path for your current directory. This path will appear to be in a mounted folder, `/mnt/c`, because we're now viewing your Windows C:\ drive folder from the Linux subsystem. You can access all of your local computer's file system from within the Linux shell by using this `/mnt/c` mounted file path.
+    > - For best performance, we recommend cloning the workspace to the Linux file system. For example, from the Linux shell (as noted above), you could run:
+    >
+     ```BASH
+          cd $HOME
+          git clone https://github.com/Azure/missionlz.git
+     ```
+    >
+    > - The Windows Git Credential Manager can be configured to work from WSL to help with complex authentication patterns like two-factor authentication. See the [documentation here](https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-git#git-credential-manager-setup). Below is the command to run for setting the Windows Credential Manager in WSL:
+
+     ```BASH
+          git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-manager.exe"
+     ```
+
+- Open a command line (e.g. `wsl.exe` or `bash.exe`), change to the root folder of the local workspace for the cloned repository, and start VS Code from this root folder (not a sub folder or a parent folder).
+  > **NOTE:** If you are using WSL or BASH on Linux or Mac, you can navigate to the root folder of the project (for example, in the path `$HOME/missionlz` assuming you cloned the project to $HOME) and enter the command below to launch VS Code in correct directory. Be sure to include the trailing "." in the second command.
 
     ```BASH
-    git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-manager.exe"
+    cd $HOME/missionlz
+    code .
     ```
 
-- Install the recommended VS Code extensions found at `../vscode/extensions.json`, including the "Remote Development" extension from Microsoft.
+- Install the recommended VS Code extensions found in `.vscode/extensions.json` (relative to the root of the project folder), including the "Remote Development" extension from Microsoft.
+  > **NOTE:** When VS Code starts, it reads the file `.vscode/extensions.json` relative from the current working directory. On startup, VS Code may prompt the user to install any extensions referenced here that are not already installed.
 
 ### Step-by-Step
 
-1. Open VS Code to the root folder of the git repository (not a sub folder or a parent folder). You should see a folder named `.devcontainer` at the root of the VS Code Explorer pane.
-
-    > NOTE: If you are using WSL or BASH on Linux or Mac, you can navigate to the root folder of the git repository and enter the command below to launch VS Code and open it to the right directory. Be sure to include the trailing ".".
-
-    ```BASH
-    code .
-    ```
+1. Open VS Code from the root folder of the local workspace (not a sub folder or a parent folder). You should see a folder named `.devcontainer` at the root of the VS Code Explorer pane.
 
 1. In the VS Code command palette (Ctrl+Shift+P), run this command
 
     ```VSCODE
     Remote-Containers: Reopen in Container
     ```
 
-    The container will build on your machine. The first build may take some time; the `Reopen in Container` command will be much faster after the initial container build, and VS Code will prompt you if the container needs to be rebuilt when the `Dockerfile` or container configuration settings have changed.
+    > **NOTE:** The container will build on your machine. The first build may take several minutes; the `Reopen in Container` command will be much faster after the initial container build, and VS Code will prompt you if the container needs to be rebuilt when the `Dockerfile` or container configuration settings have changed.
 
-1. (Optional) if you'd like to interact with the devcontainer's terminal from another terminal other than VS Code's built in terminal, you can docker's `exec` command.
+    When logged into the devcontainer's terminal, the working directory changes to `vscode@missionlz-dev:/workspaces/missionlz$`
 
-    > NOTE: VS Code attaches to the container as the user named "vscode", so you have to do the same thing when attaching to a BASH session in the container by specifying the user as an argument to the `docker exec` command. If you do not specify the user then you will be connected as root, which will cause permissions issues in git (if you are launching VS Code from WSL).
+1. (*Optional*) If you'd like to interact with the devcontainer's terminal from another terminal other than VS Code's built in terminal, you can use the `docker exec` command.
+
+    > **NOTE:** VS Code attaches to the container as the user named "vscode", so you have to do the same thing when attaching to a BASH session in the container by specifying the user as an argument to the `docker exec` command. If you do not specify the user then you will be connected as root, which will cause permissions issues in git (if you are launching VS Code from WSL).
 
     ```BASH
     docker exec --interactive --tty --user vscode missionlz-dev /bin/bash
@@ -53,5 +68,3 @@ All configuration related to the development container is in the `.devcontainer`
     ```BASH
     docker exec -it -u vscode missionlz-dev /bin/bash
     ```
-
-    When you are logged into the devcontainer's terminal, you will find the working directory

src/docs/getting-started.md

@@ -20,14 +20,15 @@ The develoment container is not necessary if you want to use the Mission LZ user
 
 ## Pre-Requisites
 
-Operating system: Mac OS, Linux, or [Windows 10 with Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10) (We developed this on Windows 10/WSL running Ubuntu 20.04).
+* **Operating system:** Mac OS, Linux, or [Windows 10 with Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
+  >*We developed this on Windows 10/WSL running Ubuntu 20.04*
+* **Docker:** Docker Desktop or Docker CE
+  >*We use [Docker Desktop on Windows 10](https://docs.docker.com/docker-for-windows/install/), integrated with WSL*
+* Current version of the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli).
 
-Docker: Docker Desktop or Docker CE (We use Docker Desktop on Windows 10, integrated with WSL.)
-
-The Azure CLI.
-
-All other tools and resources are in the development container and in the user interface container. The simplest path is to deploy from one of these containers, but it is not required if you want to configure your own deployment environment. See the development container [README](../../.devcontainer/README.md) document in the `.devcontainer` folder for details, and the user interface [Dockerfile](../Dockerfile) for details on user interface pre-requisites.
+All other tools and resources are in the development container and in the user interface container. The simplest path is to deploy from one of these containers, but it is not required if you want to configure your own deployment environment.
 
 ## Step-by-step
 
-See the detailed step-by-step guides for [Command Line Deployments](command-line-deployment.md) and [User Interface Deployments](ui-deployment.md).
+* See the detailed step-by-step guides for [Command Line Deployments](command-line-deployment.md) and [User Interface Deployments](ui-deployment.md).
+* (*Optional*) For details and pre-requisites for the development container, see the [README](../../.devcontainer/README.md) document in the `.devcontainer` folder.

src/docs/ui-deployment.md

@@ -24,13 +24,37 @@ To get started, you'll need to be running from a bash/zsh environment. If you ar
 
 This process will build the user interface container image on your workstation using Docker, upload the container image to your Azure subscription, and install an instance of the container in Azure Container Instances (ACI). You'll need to have Docker installed locally, as well as the Azure Bash CLI.
 
-From the "src" directory
+Log in using the Azure CLI
 
 ```BASH
-chmod u+x ./scripts/setup_ezdeploy.sh
-./script/setup_ezdeploy.sh -d build -s <subscription_id> -t <tenant_id> -l <location> -e <tf_env_name> -m <mlz_env_name> -p port -0 <saca_subscription_id> -1 <tier0_subscription_id> -2 <tier1_subscription_id> -3 <tier2_subscription_id>"
+az login
+```
+
+> **Note:** For deployments to Azure Government, you will first need to set the cloud before logging in, such as:
+
+```BASH
+ az cloud set --name AzureUSGovernment
+ az login
 ```
 
+From the "src" directory, set the access permissions to the `setup_ezdeploy.sh` deployment script and run it (the example below assumes the local workspace root directory is at `$HOME/missionlz`)
+
+```bash
+    cd $HOME/missionlz/src    # -- your local workspace path may be different 
+
+    export TENANT_ID="<TENANT_ID>"
+    export SUBSCRIPTION_ID="<SUBSCRIPTION_ID>"
+    export TF_ENV="<TERRAFORM_ENVIRONMENT>"
+    export MLZ_ENV="<ENVIRONMENT_NAME>"
+    export LOCATION="<CLOUD_LOCATION>"
+
+    chmod u+x ./scripts/setup_ezdeploy.sh
+
+    ./scripts/setup_ezdeploy.sh -d build -s $SUBSCRIPTION_ID -t $TENANT_ID -l $LOCATION -e $TF_ENV -m $MLZ_ENV -p 80 -0 $SUBSCRIPTION_ID -1 $SUBSCRIPTION_ID -2 $SUBSCRIPTION_ID -3 $SUBSCRIPTION_ID
+```
+
+> In the command above, the *&lt;values-in-brackets&gt;* need to be replaced with actual values from your environment
+
 The final results will include a URI that you can use to access the front end running in a remote azure container instance.
 
 ### Step-by-Step Local Installation