additional updates to install & troubleshooting docs

Author: dsajdak

coldfront/README.md

@@ -36,21 +36,23 @@ For more options on allowing permissions for various types of staff access, see
 
 
 ### Activate the allocation request  
-At part of the database seeding we did at the start of the tutorial, we activated and set attributes on the allocations requested on the `cgray` project.  Let's look at that allocation and how it was setup.  
-- Login using local account username: `hpcadmin` password: `ilovelinux` 
-- Navigate to the `Admin` menu and click on the `All Allocations` option  
-- Click on the allocation number next to the allocation for the `HPC cluster` resource.  
-- Scroll down to look at the allocation attributes set.  Notice that allocation status is `Renewal Requested` and there is a start and end date associated with it.  
+
+- Navigate to the `Admin` menu and click on `Allocation Requests`  
+Note: the project review status is a green check mark, indicating our Center Director has already approved the submitted project review.  
+
+At part of the database seeding we did at the start of the tutorial, we activated and set attributes on the allocations requested on the `cgray` project.  Let's look at that allocation and how it was setup. 
+
+- Click the `Details` button to review the Allocation Detail page.  
+- Notice that allocation status is `Renewal Requested` and there is a start and end date associated with it.  
+- Scroll down to look at the allocation attributes set. There is a slurm_account attribute as well as slurm_specs and slurm_user_specs attributes.  This is what is used by the Slurm plugin to sync with the Slurm database.  
+- Click the `Approve` button to re-activate the allocation.  This updates the status to `Active` and changes the expiration date to one year from today.  
 
 Now let's go look at and activate the allocation change request submitted by `cgray` for the storage resource.  As the HPC admin user, activate and setup the new allocation:  
 - Navigate to the `Admin` menu and click on `Allocation Change Requests`  
 - Click on the `Details` button to review and approve the allocation changes requested.  As the admin you have the ability to approve the date extension, change it to another setting or select `no extension`  You can remove the `storage_quota` request or change it.  You can add notes for the PI and users on the allocation to see.  Then you can take action such as `Approve` or `Deny` the request.  For this demo, let's click the `Approve` button.  
 
 For more information about configuring Allocation Change Requests [see here](#more-info-on-allocation-change-requests) 
 
-Next review the pending allocation requests:  
-- Navigate to the `Admin` menu and click on `Allocation Requests`  Note that the project review status is green check mark, indicating our Center Director has already approved the submitted project review.  
-- Click the `Details` button if you'd like to review the Allocation Detail page.  Otherwise, click the `Approve` button to renew the allocation for another year.  
 - Logout as the `hpcadmin` user   
 
 
@@ -72,7 +74,7 @@ _**This is because we have not synced the allocation information in ColdFront wi
 ### Run Slurm plugin to sync active allocations from ColdFront to Slurm
 - Login to the coldfront container & setup ColdFront environment  
 `ssh coldfront`  
-`cd /srv/www`
+`cd /srv/www`  
 `source venv/bin/activate`
 - Let's see what slurm access cgray currently has:  
 `sacctmgr show user cgray -s list`  

docs/docker_tips.md

@@ -46,30 +46,28 @@ $ ./hpcts start
 
 - [Docker](https://docs.docker.com)
 - [Install & Start Docker](https://docs.docker.com/engine/install/)
-- [Install Docker Compose](https://docs.docker.com/compose/install/)
-- [Linux](https://docs.docker.com/engine/install/linux-postinstall/) 
+- [Linux & WSL](https://docs.docker.com/engine/install/linux-postinstall/) 
 - [MacOS Docker Desktop](https://docs.docker.com/docker-for-mac/troubleshoot/)  
-- [Windows Docker Desktop](https://docs.docker.com/docker-for-windows/troubleshoot/)
 
 ### Helpful Docker commands
 
 ```
 # Start all HPC Toolset Containers manually
-$ docker-compose up -d
+$ docker compose up -d
 
 # Display Tutorial Container Logs
-$ docker-compose logs -f
-$ docker-compose logs -f coldfront
-$ docker-compose logs -f xdmod
+$ docker compose logs -f
+$ docker compose logs -f coldfront
+$ docker compose logs -f xdmod
 
 # Stop containers 
-$ docker-compose stop
+$ docker compose stop
 
 # Stop containers and remove them
-$ docker-compose down
+$ docker compose down
 
 # Stop containers,remove them and all volumes
-$ docker-compose down -v
+$ docker compose down -v
 
 # Display Docker processes
 $ docker ps -a
@@ -113,28 +111,6 @@ NOTE: this is only necessary on some systems so don't use it if the previous com
 
 **Sometimes restarting your operating system is the only solution.**
 
-#### Windows Errors  
-
-NOTE: Windows users should get several pop-up messages from Docker Desktop during this process asking to allow local system access to the Docker containers.  Please click the "Share it" button:
-![](windows_sharing.PNG)
-
-If you have notifications blocked, you may not see these pop-ups and the authorization will eventually time out.  If this happens, you will get this type of error message:    
-
-```
-Error response from daemon: user declined directory sharing C:\Users\path_to_my_folder
-```
-Open Docker Desktop, navigate to Settings - Resources, and click on File Sharing.  Then add the directory where you've cloned the HPC Toolset Tutorial and click "Apply & Restart"
-
-Re-run:  
-```
-./hpcts start  
-```
-
-If this doesn't work, please run:  
-```
-./hpcts cleanup  
-./hpcts start  
-```
 
 #### Deleting Docker containers/images/volumes manually
 

docs/getting_started.md

@@ -12,13 +12,8 @@ If you haven't already installed and tested the required packages, please refer
 
 ## Getting started
 
-You will need to clone the tutorial repo and then run the helper script.  The initial clone of the repo may take 5-10 minutes.  The first time running the helper script, you'll be downloading all the containers from Docker Hub.  This can take quite a long time depending on your network speed.  The images total approximately 13GB in size.  Once the containers are downloaded, they are started and the services launched.  For point of reference: on a recent test from a home fiber optic network with client connected over wifi this download and container startup process took 12 minutes.  
+You will need to clone the tutorial repo and then run the helper script.  The initial clone of the repo may take 5-10 minutes.  The first time running the helper script, you'll be downloading all the containers from Docker Hub.  This can take quite a long time depending on your network speed.  The images total approximately 20GB in size.  Once the containers are downloaded, they are started and the services launched.  For point of reference: on a recent test from a home fiber optic network with client connected over wifi this download and container startup process took 12 minutes.  
 
-NOTE: For Windows, if you haven't already done so, you will need to configure git not to convert line endings into Windows format.  Run this command using the git-bash shell application before cloning the tutorial repo:
-
-```
-git config --global core.autocrlf input
-```
 
 ### Clone Repo and Start Containers
 
@@ -84,28 +79,7 @@ Starting HPC Toolset Cluster..
 
 **NOTE:  Despite seeing this output with URLs, the processes on these containers may not be fully running yet.  Depending on the speed of your computer, starting up the processes may take a few minutes (or even up to 10 minutes).  Use the command below to check the docker logs if the websites are not yet displaying.**
 
-### Windows Errors  
-
-NOTE: Windows users should get several pop-up messages from Docker Desktop during this process asking to allow local system access to the Docker containers.  Please click the "Share it" button:
-![](windows_sharing.PNG)
 
-If you have notifications blocked, you may not see these pop-ups and the authorization will eventually time out.  If this happens, you will get this type of error message:    
-
-```
-Error response from daemon: user declined directory sharing C:\Users\path_to_my_folder
-```
-Open Docker Desktop, navigate to Settings - Resources, and click on File Sharing.  Then add the directory where you've cloned the HPC Toolset Tutorial and click "Apply & Restart"
-
-Re-run:  
-```
-./hpcts start  
-```
-
-If this doesn't work, please run:  
-```
-./hpcts destroy  
-./hpcts start  
-```
 
 ### Docker Logs
 

docs/requirements.md

@@ -1,17 +1,11 @@
 ## Requirements
 
-For this tutorial you will need to have **20GB of free disk space** and git, docker, docker-compose and a web browser installed on your local machine.  This tutorial has been tested on various versions of Linux, MacOS, and Windows 10/11 with the following package versions:
+For this tutorial you will need to have **20GB of free disk space** and git, docker, docker-compose and a web browser installed on your local machine.  This tutorial has been tested on various versions of Linux, MacOS, and Windows 10/11 (using Windows subsystem for Linux) with the following package versions:
 
-- git 2.17+ (Windows users we recommend:  https://gitforwindows.org/)
+- git 2.17+ 
 - docker engine version 20.10.12+
 - docker compose 2.6.0+ (this is distributed with newer versions of docker and not necessary to install separately)  
 
-NOTE: For Windows, if you haven't already done so, you will need to configure git not to convert line endings into Windows format.  Run this command using the git-bash shell application before cloning the tutorial repo:
-
-```
-git config --global core.autocrlf input
-```
-
 The following ports must be open and available:
 
 - 2443
@@ -27,7 +21,9 @@ If they are not you might see an error like:
 
 https://docs.docker.com/engine/install/
 
-**NOTE: You'll need to make sure the account you're running docker with is in the 'docker' group**
+**NOTE: Make sure the account you're running docker with is in the 'docker' group**
+
+**Windows users:** We do NOT recommend using Docker Desktop with this container environment.  Instead, use Windows subsystem for Linux (WSL) and install Docker within an Ubuntu virtual machine.  [This site](https://nickjanetakis.com/blog/install-docker-in-wsl-2-without-docker-desktop) provides useful information on this method, except docker-compose no longer needs to be installed separately.  Using WSL allows you to follow the docker installation instructions for Linux and this is what is tested by the HPC Toolset Tutorial team.  
 
 ### Verify working Docker
 
@@ -38,28 +34,6 @@ docker info
 **This should display your system info along with Docker-specific info.  If there are any errors, stop/start Docker.  Do NOT proceed with the tutorial until you are sure you have a working Docker setup**
 
 
-### Error when running 'docker info' or when starting up tutorial containers
-
-If you get this error when starting the tutorial   
-
-```
-ERROR: Couldn't connect to Docker daemon at http+docker://localunixsocket - is it running?
-
-or  
-
-ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running?
-```
-
-Try stopping and starting Docker (restart doesn't usually fix the problem).  Commands for this differ depending on operating system.
-
-If the error persists, try:  
-
-```
-export DOCKER_HOST=127.0.0.1
-```
-
-NOTE: this is only necessary on some systems so don't use it if the previous command works
-
 ## Docker Tips
 
 Some useful info on installing Docker, navigating this tutorial and learning a bit about docker-compose