documentation update

[lsloan]

As discussed in 7 Sept 2023 meeting, update documentation about…

• VPN must be enabled to access UDW
  • Using UDW is recommended because it speeds up the application when many courses are being updated
  • E.g., when the app is used with a large sub-account
• Mention running the app again
  • Running the app multiple times is OK
  • Subsequent runs will make the same changes as the first
  • Sometimes subsequent runs are necessary to update courses that were created very recently and weren't updated by the just previous run
• Mention Docker build/update process
  • The build/update process shouldn't take more than 2–3 minutes
  • Only runs when a new version of the app is used or new versions of its dependencies are available
  • If nothing has changed since the last time the app was run, Docker will have little or nothing to build/update before running the app
• Testing with brand new courses may need to disable warehouse
  • If testing with new courses in Canvas beta, they may not appear in UDW and will not be updated
  • It's OK to disable UDW to work with new courses
• What happens if some courses aren't changed? Wait 24–48 hours.
  • In production, this may happen if the course is relatively new and their data doesn't appear in UDW
  • Waiting 24–48 hours, depending on when the course was created, will give enough time for the course to appear in UDW
• Changes to env file required to work with different Canvas instance
  • Which env values need to be changed to work with a different instance of Canvas?
    • API_URL
    • API_KEY — maybe, e.g., if the key in the beta instance wasn't copied from the production instance
• How to interrupt the running application?
  • Pressing ^C will tell Docker to stop running the app
  • Docker will start a "graceful" shutdown of the app
  • If gracefulness isn't desired, press ^C again to force a quick stop
• The app is resumable
  • If the app doesn't complete its updates, due to any kind of interruption (e.g., user intervention, network problems, etc.) running the app again will cause it to continue where it left off
  • I.e., …
    • if the config was to change tool A to tool B in many courses and it gets interrupted, then the courses that were processed up to the moment of the interruption will have been changed from tool A to tool B
    • to update the remaining courses from tool A to tool B, simply run the app again with the same config
    • the app will examine all courses and skip those that already have tool A replaced with tool B

This issue is a rough draft of the documentation updates.

[lsloan]

@ziegler1960, tell us if you think of any other changes or additions.

[lsloan]

Resuming next part of doc updates…