alan-turing-institute · jemrobinson · Aug 14, 2024 · Aug 9, 2024 · Aug 9, 2024 · Aug 9, 2024
diff --git a/.lychee.toml b/.lychee.toml
@@ -92,7 +92,9 @@ glob_ignore_case = false
 exclude = [
   'doi\.org',  # 403
   'entra.microsoft\.com',  # Requires authentication (403)
+  'example\.org',  # domain used for examples only
   'github\.com',  # Requires authentication (403)
+  'hedgedoc\.org',  # 403
   'ipaddressguide\.com',  # 403
   'opensource\.org',  # 403
   'portal\.azure\.com',  # 403

diff --git a/docs/source/deployment/deploy_shm.md b/docs/source/deployment/deploy_shm.md
@@ -57,7 +57,7 @@ Before deploying the Safe Haven Management (SHM) infrastructure you need to deci
 : Domain name that your TRE users will belong to.
 
   :::{hint}
-  Use a domain that you own! If you use _e.g._ `bakerst.london` here your users will be given usernames like `sherlock.holmes@bakerst.london`
+  Use a domain that you own! If you use _e.g._ `example.org` here your users will be given usernames like `ada.lovelace@example.org`
   :::
 
 **location**

diff --git a/docs/source/management/index.md b/docs/source/management/index.md
@@ -18,8 +18,8 @@ You will need a full name, phone number, email address and country for each user
 
 :::{code} text
 GivenName;Surname;Phone;Email;CountryCode
-Sherlock;Holmes;+44800456456;sherlock@holmes.me;GB
-John;Watson;+18005550100;john.watson@nhs.uk;GB
+Ada;Lovelace;+44800456456;ada@lovelace.me;GB
+Grace;Hopper;+18005550100;grace@nasa.gov;US
 :::
 ::::
 
@@ -47,10 +47,10 @@ $ dsh users add PATH_TO_MY_CSV_FILE
     ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
     ┃ username                     ┃ Entra ID ┃ SRE YOUR_SRE_NAME ┃
     ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
-    │ ada.lovelace                 │ x        │                   │
-    │ grace.hopper                 │ x        │                   │
-    │ sherlock.holmes              │ x        │ x                 │
-    │ john.watson                  │ x        │ x                 │
+    │ ada.lovelace                 │ x        │ x                 │
+    │ grace.hopper                 │ x        │ x                 │
+    │ ursula.franklin              │ x        │                   │
+    │ joan.clarke                  │ x        │                   │
     └──────────────────────────────┴──────────┴───────────────────┘
     ```
 

diff --git a/docs/source/roles/investigator/index.md b/docs/source/roles/investigator/index.md
@@ -23,5 +23,5 @@ The **Investigator** must be able and willing to accept responsibility for the c
 [Data egress](data_egress.md)
 : What an **Investigator** needs to know about bringing data or software out of the environment.
 
-{ref}`User guide <role_researcher_user_guide_guacamole>`
+{ref}`Researcher guide <role_researcher>`
 : Step-by-step instructions for using an existing Safe Haven.
diff --git a/docs/source/roles/researcher/accessing_the_sre.md b/docs/source/roles/researcher/accessing_the_sre.md
@@ -0,0 +1,179 @@
+(roles_researcher_access_sre)=
+
+# Accessing the Secure Research Environment
+
+## {{seedling}} Prerequisites
+
+After going through the account setup procedure, you should have access to:
+
+- Your **username**
+- Your **password**
+- The {ref}`SRE URL <roles_researcher_sre_url>`
+- {ref}`Multifactor authentication <roles_researcher_password_and_mfa>`
+
+:::{tip}
+If you aren't sure about any of these then please return to the **{ref}`Set up your account <roles_researcher_setup_your_account>`** section.
+:::
+
+## {{unlock}} Log into the research environment
+
+::::{admonition} 1. Browse to the SRE URL
+:class: dropdown note
+
+- Open a **private/incognito** browser session, so that you don't pick up any existing Microsoft logins
+
+- Go to the {ref}`SRE URL <roles_researcher_sre_url>` given by your {ref}`System Manager <role_system_manager>`.
+
+    :::{note}
+    Our example user, Ada Lovelace, participating in the **sandbox** project, would navigate to **https://sandbox.projects.example.org**.
+    :::
+
+::::
+
+::::{admonition} 2. Enter your username and password at the prompt
+:class: dropdown note
+
+- At the login prompt enter your **{ref}`long-form username <roles_researcher_username>`** and click on the **{guilabel}`Next`** button
+
+    :::{image} images/guacamole_oauth_login.png
+    :alt: Research environment log in
+    :align: center
+    :width: 90%
+    ::::
+
+    ::::{tip}
+    Our example user, Ada Lovelace, would use **ada.lovelace@projects.example.org** here.
+    :::
+
+- Enter your password at the prompt and click on the **{guilabel}`Next`** button
+
+::::
+
+::::{admonition} 3. Login with MFA
+:class: dropdown note
+
+- You will now **receive a call or mobile app notification** to authenticate using multifactor authentication (MFA).
+
+    :::{image} images/guacamole_mfa.png
+    :alt: MFA trigger
+    :align: center
+    :width: 90%
+    :::
+
+  {{telephone_receiver}} For the call, you may have to move to an area with good reception and/or press the hash (**#**) key multiple times in-call.
+
+  {{iphone}} For the app you will see a notification saying **"You have received a sign in verification request"**. Go to the app to approve the request.
+
+    :::{caution}
+    If you don't respond to the MFA request quickly enough, or if it fails, you may get an error. If this happens, please retry
+    :::
+
+::::
+
+You should now be able to see the SRE dashboard screen which will look like the following
+
+:::{image} images/guacamole_dashboard.png
+:alt: Research environment dashboard
+:align: center
+:width: 90%
+:::
+
+## {{house}} Log into a workspace
+
+On the SRE dashboard, you should see multiple different workspaces that you can access either via an interactive desktop environment (**Desktop**) or a terminal environment (**SSH**).
+
+:::{important}
+If you do not see any available workspaces please contact your {ref}`System Manager <role_system_manager>`.
+:::
+
+Each of these is a computer[^footnote-vm] with a wide variety of data analysis applications and programming languages pre-installed.
+You can use them to analyse the sensitive data belonging to your project while remaining isolated from the wider internet.
+
+[^footnote-vm]: Actually a virtual machine
+
+::::{admonition} 1. Select a workspace
+:class: dropdown note
+
+- Click on one of the **Desktop** connections from the list in **All Connections**
+
+    :::{note}
+    Each workspace should have an annotation which indicates its available resources:
+    - CPUs
+    - GPUs
+    - RAM
+    :::
+
+    :::{caution}
+    These workspaces are shared between everyone on your project. Talk to your collaborators to ensure that you're not all using the same one.
+    :::
+
+::::
+
+:::::{admonition} 2. Login with your user credentials
+:class: dropdown note
+
+- Enter your **{ref}`short-form username <roles_researcher_username>`** and **password** at the prompt.
+
+  :::{image} images/workspace_login_screen.png
+  :alt: Workspace login screen
+  :align: center
+  :width: 90%
+  :::
+
+  :::{note}
+  Our example user, Ada Lovelace, would enter **ada.lovelace** and her password.
+  :::
+
+  ::::{error}
+  If you enter your username and/or password incorrectly you will see a warning like the one below.
+  If this happens, please try again, entering your username and password carefully.
+
+  :::{image} images/workspace_login_failure.png
+  :alt: Workspace login failure
+  :align: center
+  :width: 90%
+  :::
+
+  If you want to reset your password, follow the steps defined in the {ref}`Password and MFA <roles_researcher_password_and_mfa>` section.
+  ::::
+:::::
+
+You should now be able to see the SRE dashboard screen which will look like the following
+
+:::{image} images/workspace_xfce_initial.png
+:alt: Research environment dashboard
+:align: center
+:width: 90%
+:::
+
+Welcome to the Data Safe Haven SRE! {{wave}}
+
+## {{unlock}} Access additional workspaces
+
+Your project might make use of further workspaces in addition to the main shared desktop.
+Usually this is because of a requirement for a different type of computing resource, such as access to one or more GPUs (graphics processing units).
+
+You will access this machine in a similar way to the main shared desktop, by selecting a different **Desktop** connection.
+
+::::{admonition} Selecting a different workspace
+:class: dropdown note
+
+- Our example user, Ada Lovelace, participating in the **sandbox** project, might select **Workspace 2** instead of **Workspace 1** since it has additional CPUs and RAM.
+
+    :::{image} images/guacamole_dashboard_multiple_workspaces.png
+    :alt: Research environment dashboard
+    :align: center
+    :width: 90%
+    :::
+
+- This will bring her to the normal login screen, where she will use the short-form username **ada.lovelace** and her password as before.
+
+::::
+
+:::{tip}
+When you are connected to a workspace, you may switch to another by bringing up the [Guacamole menu](https://guacamole.apache.org/doc/gug/using-guacamole.html#the-guacamole-menu) with **{kbd}`Ctrl+Alt+Shift`** and navigating to the [home screen](https://guacamole.apache.org/doc/gug/using-guacamole.html#client-user-menu).
+:::
+
+:::{tip}
+Any files in the **/output/**, **/home/** or **/shared** folders on other workspaces will be available in this workspace too.
+:::
diff --git a/docs/source/roles/researcher/images/account_setup_captcha.png b/docs/source/roles/researcher/images/account_setup_captcha.png
diff --git a/docs/source/roles/researcher/images/account_setup_forgotten_password.png b/docs/source/roles/researcher/images/account_setup_forgotten_password.png
diff --git a/...count_setup_mfa_add_authenticator_app.png → ...count_setup_mfa_add_authenticator_app.png b/...count_setup_mfa_add_authenticator_app.png → ...count_setup_mfa_add_authenticator_app.png
diff --git a/..._mfa_additional_security_verification.png → ..._mfa_additional_security_verification.png b/..._mfa_additional_security_verification.png → ..._mfa_additional_security_verification.png
diff --git a/...account_setup_mfa_allow_notifications.png → ...account_setup_mfa_allow_notifications.png b/...account_setup_mfa_allow_notifications.png → ...account_setup_mfa_allow_notifications.png
diff --git a/...er_guide/account_setup_mfa_app_qrcode.png → ...r/images/account_setup_mfa_app_qrcode.png b/...er_guide/account_setup_mfa_app_qrcode.png → ...r/images/account_setup_mfa_app_qrcode.png
diff --git a/..._setup_mfa_authenticator_app_approved.png → ..._setup_mfa_authenticator_app_approved.png b/..._setup_mfa_authenticator_app_approved.png → ..._setup_mfa_authenticator_app_approved.png
diff --git a/...ount_setup_mfa_authenticator_app_test.png → ...ount_setup_mfa_authenticator_app_test.png b/...ount_setup_mfa_authenticator_app_test.png → ...ount_setup_mfa_authenticator_app_test.png
diff --git a/...ccount_setup_mfa_dashboard_phone_only.png → ...ccount_setup_mfa_dashboard_phone_only.png b/...ccount_setup_mfa_dashboard_phone_only.png → ...ccount_setup_mfa_dashboard_phone_only.png
diff --git a/...count_setup_mfa_dashboard_two_methods.png → ...count_setup_mfa_dashboard_two_methods.png b/...count_setup_mfa_dashboard_two_methods.png → ...count_setup_mfa_dashboard_two_methods.png
diff --git a/..._setup_mfa_download_authenticator_app.png → ..._setup_mfa_download_authenticator_app.png b/..._setup_mfa_download_authenticator_app.png → ..._setup_mfa_download_authenticator_app.png
diff --git a/...de/account_setup_mfa_registered_phone.png → ...es/account_setup_mfa_registered_phone.png b/...de/account_setup_mfa_registered_phone.png → ...es/account_setup_mfa_registered_phone.png
diff --git a/...uide/account_setup_mfa_verified_phone.png → ...ages/account_setup_mfa_verified_phone.png b/...uide/account_setup_mfa_verified_phone.png → ...ages/account_setup_mfa_verified_phone.png
diff --git a/...ide/account_setup_mfa_verifying_phone.png → ...ges/account_setup_mfa_verifying_phone.png b/...ide/account_setup_mfa_verifying_phone.png → ...ges/account_setup_mfa_verifying_phone.png
diff --git a/...count_setup_more_information_required.png → ...count_setup_more_information_required.png b/...count_setup_more_information_required.png → ...count_setup_more_information_required.png
diff --git a/...user_guide/account_setup_new_password.png → ...her/images/account_setup_new_password.png b/...user_guide/account_setup_new_password.png → ...her/images/account_setup_new_password.png
diff --git a/...de/account_setup_new_password_sign_in.png → ...es/account_setup_new_password_sign_in.png b/...de/account_setup_new_password_sign_in.png → ...es/account_setup_new_password_sign_in.png
diff --git a/...user_guide/account_setup_verify_phone.png → ...her/images/account_setup_verify_phone.png b/...user_guide/account_setup_verify_phone.png → ...her/images/account_setup_verify_phone.png
diff --git a/docs/source/roles/researcher/images/db_dbeaver_connect_mssql.png b/docs/source/roles/researcher/images/db_dbeaver_connect_mssql.png
diff --git a/docs/source/roles/researcher/images/db_dbeaver_connect_postgresql.png b/docs/source/roles/researcher/images/db_dbeaver_connect_postgresql.png
diff --git a/.../user_guide/db_dbeaver_mssql_download.png → ...her/images/db_dbeaver_driver_download.png b/.../user_guide/db_dbeaver_mssql_download.png → ...her/images/db_dbeaver_driver_download.png
diff --git a/docs/source/roles/researcher/images/db_dbeaver_select_mssql.png b/docs/source/roles/researcher/images/db_dbeaver_select_mssql.png
diff --git a/docs/source/roles/researcher/images/db_dbeaver_select_postgresql.png b/docs/source/roles/researcher/images/db_dbeaver_select_postgresql.png
diff --git a/docs/source/roles/researcher/images/firefox_not_responding.png b/docs/source/roles/researcher/images/firefox_not_responding.png
diff --git a/docs/source/roles/researcher/images/gitea_dashboard.png b/docs/source/roles/researcher/images/gitea_dashboard.png
diff --git a/docs/source/roles/researcher/images/gitea_explore.png b/docs/source/roles/researcher/images/gitea_explore.png
diff --git a/docs/source/roles/researcher/images/gitea_homepage.png b/docs/source/roles/researcher/images/gitea_homepage.png
diff --git a/docs/source/roles/researcher/images/gitea_login.png b/docs/source/roles/researcher/images/gitea_login.png
diff --git a/docs/source/roles/researcher/images/gitea_new_repository.png b/docs/source/roles/researcher/images/gitea_new_repository.png
diff --git a/docs/source/roles/researcher/images/gitea_pull_request_diff.png b/docs/source/roles/researcher/images/gitea_pull_request_diff.png
diff --git a/docs/source/roles/researcher/images/gitea_pull_request_finish.png b/docs/source/roles/researcher/images/gitea_pull_request_finish.png
diff --git a/docs/source/roles/researcher/images/gitea_pull_request_start.png b/docs/source/roles/researcher/images/gitea_pull_request_start.png
diff --git a/docs/source/roles/researcher/images/gitea_repository_view.png b/docs/source/roles/researcher/images/gitea_repository_view.png
diff --git a/docs/source/roles/researcher/images/guacamole_dashboard.png b/docs/source/roles/researcher/images/guacamole_dashboard.png
diff --git a/docs/source/roles/researcher/images/guacamole_dashboard_multiple_workspaces.png b/docs/source/roles/researcher/images/guacamole_dashboard_multiple_workspaces.png
diff --git a/...s/researcher/user_guide/guacamole_mfa.png → ...roles/researcher/images/guacamole_mfa.png b/...s/researcher/user_guide/guacamole_mfa.png → ...roles/researcher/images/guacamole_mfa.png
diff --git a/...earcher/user_guide/guacamole_ms_login.png → ...searcher/images/guacamole_oauth_login.png b/...earcher/user_guide/guacamole_ms_login.png → ...searcher/images/guacamole_oauth_login.png
diff --git a/docs/source/roles/researcher/images/hedgedoc_access_options.png b/docs/source/roles/researcher/images/hedgedoc_access_options.png
diff --git a/docs/source/roles/researcher/images/hedgedoc_homepage.png b/docs/source/roles/researcher/images/hedgedoc_homepage.png
diff --git a/docs/source/roles/researcher/images/hedgedoc_login.png b/docs/source/roles/researcher/images/hedgedoc_login.png
diff --git a/docs/source/roles/researcher/images/hedgedoc_publish.png b/docs/source/roles/researcher/images/hedgedoc_publish.png
diff --git a/docs/source/roles/researcher/images/workspace_desktop_applications.png b/docs/source/roles/researcher/images/workspace_desktop_applications.png
diff --git a/docs/source/roles/researcher/images/workspace_desktop_pycharm.png b/docs/source/roles/researcher/images/workspace_desktop_pycharm.png
diff --git a/docs/source/roles/researcher/images/workspace_desktop_rstudio.png b/docs/source/roles/researcher/images/workspace_desktop_rstudio.png
diff --git a/docs/source/roles/researcher/images/workspace_desktop_vscodium.png b/docs/source/roles/researcher/images/workspace_desktop_vscodium.png
diff --git a/docs/source/roles/researcher/images/workspace_login_failure.png b/docs/source/roles/researcher/images/workspace_login_failure.png
diff --git a/docs/source/roles/researcher/images/workspace_login_screen.png b/docs/source/roles/researcher/images/workspace_login_screen.png
diff --git a/docs/source/roles/researcher/images/workspace_terminal_python.png b/docs/source/roles/researcher/images/workspace_terminal_python.png
diff --git a/docs/source/roles/researcher/images/workspace_terminal_r.png b/docs/source/roles/researcher/images/workspace_terminal_r.png
diff --git a/docs/source/roles/researcher/images/workspace_xfce_initial.png b/docs/source/roles/researcher/images/workspace_xfce_initial.png
diff --git a/docs/source/roles/researcher/index.md b/docs/source/roles/researcher/index.md
@@ -5,16 +5,28 @@
 :::{toctree}
 :hidden:
 
-user_guide.md
+new_user_setup.md
+accessing_the_sre.md
+using_the_sre.md
+troubleshooting.md
 available_software.md
 :::
 
 A project member, who analyses data to produce results.
 We reserve the capitalised term **Researcher** for this role in our user model.
 We use the lower case term when considering the population of researchers more widely.
 
-[User guide](user_guide.md)
-: Step-by-step instructions for **Researchers** who want to start using an existing Data Safe Haven.
+[New user setup](new_user_setup.md)
+: Step-by-step instructions for new **Researchers** who want to setup their Data Safe Haven account.
+
+[Accessing the SRE](accessing_the_sre.md)
+: Instructions for **Researchers** on how to connect to their Secure Research Environment.
+
+[Using the SRE](using_the_sre.md)
+: Instructions on how to use the tools available in a Secure Research Environment.
+
+[Troubleshooting](troubleshooting.md)
+: Instructions on how to fix some common problems encountered in a Secure Research Environment.
 
 [Available software](available_software.md)
-: List of the software available in the secure research environment.
+: Overview of the software available in a Secure Research Environment.