Merge pull request #1314 from craddm/add-webapp-access-docs

Add webapp access docs

docs/deployment/deploy_sre_apache_guacamole.md

@@ -248,6 +248,10 @@ If you see an error like the following when attempting to log in, it is likely t
   - This should open a web browser inside the remote desktop
   - Log in with the short-form `username` of a user in the `SG <SRE ID> Research Users` security group.
 
+````{error}
+Should there be any issues using the web apps (e.g. unable to log in, or log in page not appearing) you can inspect the build log and access the console for the relevant VMs following the guide for {ref}`System Managers <administrator_manage_webapps>`
+````
+
 ### {{fire}} Run smoke tests on SRD
 
 ```{include} snippets/14_run_smoke_tests.partial.md

docs/deployment/deploy_sre_microsoft_rds.md

@@ -305,6 +305,10 @@ If you get multiple MFA requests with no change in the `Opening ports` message,
 - Alternatively, this can happen if the NPS secret stored in the Key Vault is too long. We found that a 20 character secret caused problems but the (default) 12 character secret works.
 ```
 
+```{error}
+Should there be any issues using the web apps (e.g. unable to log in, or log in page not appearing) you can inspect the build log and access the console for the relevant VMs following the guide for {ref}`System Managers <administrator_manage_webapps>`
+````
+
 ## 8. {{baseball}} Deploy databases
 
 ```{include} snippets/08_databases.partial.md

docs/roles/system_manager/index.md

@@ -9,6 +9,7 @@ manage_users.md
 manage_data.md
 manage_costs.md
 migrate_an_shm.md
+manage_webapps.md
 manage_deployments.md
 ```
 
@@ -27,5 +28,8 @@ Typically these might be members of an institutional IT team.
 [Migrating an existing SHM](migrate_an_shm.md)
 : How to migrate the contents of a previously-deployed SHM to a new one (advanced).
 
+[Managing web applications](manage_webapps.md)
+: How to access virtual machines hosting web applications
+
 [Removing deployed components](manage_deployments.md)
 : Removing an SRE or a complete, deployment Data Safe Haven as an administrator.

docs/roles/system_manager/manage_webapps.md

@@ -0,0 +1,56 @@
+(administrator_manage_webapps)=
+
+# Managing web applications
+
+```{important}
+This document assumes that you already have access to a {ref}`Safe Haven Management (SHM) environment <deploy_shm>` and one or more {ref}`Secure Research Environments (SREs) <deploy_sre>` that are linked to it.
+```
+
+During deployment of an SRE, distinct virtual machines are created to host each of the three standard web applications - `CoCalc`, `CodiMD`, and `Gitlab`.
+
+In principle, these should require no further direct interaction. Researchers using Secure Research Desktops will be able to interact with the servers through a web interface. `CoCalc` allows users to create their own user accounts, while `CodiMD` and `Gitlab` authenticate with the domain controller via LDAP.
+
+However, it is possible for the virtual machine hosting the web app servers to successfully start without the web app servers themselves actually running. For example, Researchers using an `SRD` may find that the web apps are unavailable, or do not successfully authenticate log-in attempts. In such cases, command line access to the virtual machines hosting the web app servers may help to diagnose and resolve problems.
+
+In the rest of this document, `<SHM ID>` is the {ref}`Secure Management Environment ID <roles_deployer_shm_id>` for the SHM, and `<SRE ID>` is the {ref}`Secure Research Environment ID <roles_deployer_sre_id>` for the SRE.
+
+## Checking build logs
+
+An initial step could be to check the build logs of the virtual machine to ascertain whether any clear errors occurred during the process (e.g. the installation of the server software may have failed).
+
+- From the `Azure` portal, navigate to the web app resource group `RG_SHM_<SHM ID>_SRE_<SRE ID>_WEBAPPS`.
+- Click on the relevant VM (e.g. `COCALC-SRE-<SRE ID>`)
+- From the menu on the left, scroll down to the `Help` section and select `Boot diagnostics`
+- Click `Serial log` to access a full text log of the booting up of the VM.
+
+From the log, you may be able to determine whether and why part of the build process failed. In some cases it may be sufficient to delete and rebuild the VM.
+
+- From the menu on the left, click `Overview`
+- Click `Delete`
+- Redeploy the web app servers using `Powershell` locally
+
+![Powershell: five minutes](https://img.shields.io/static/v1?style=for-the-badge&logo=powershell&label=local&color=blue&message=five%20minutes) at {{file_folder}} `./deployment/secure_research_environment/setup`
+
+```powershell
+PS> ./Setup_SRE_WebApp_Servers.ps1
+```
+
+If the reason for failure is less clear, accessing the command line interface directly may help.
+
+## Accessing the VM console
+
+Console access to the web app VMs can be achieved through the `Azure` portal. All VMs share the same `<admin username>`, but each has its own `<admin password>`, which will need to be retrieved from the `SRE` key vault before accessing the console.
+
+- From the `Azure` portal, navigate to the Resource Group `RG_SHM_<SHM ID>_SRE_<SRE ID>_SECRETS`
+- Click on the `SRE` keyvault `kv-<SHM ID>_SRE_<SRE ID>`
+- From the menu on the left, select `Secrets` from the `Objects` section.
+- All web app VMs share the same `<admin username>`, found in the `sre-<SRE ID>-vm-admin-username` secret.
+- Each web app has its own `<admin password>`, found in the `sre-<SRE ID>-vm-admin-password-<WEB APP>` secret.
+
+Once you have the `<admin username>` and `<admin password>`, you will be able to log in to the VM console as follows:
+
+- From the `Azure` portal, navigate to the web app resource group `RG_SHM_<SHM ID>_SRE_<SRE ID>_WEBAPPS`.
+- Click on the relevant VM (e.g. `COCALC-SRE-<SRE ID>`)
+- From the menu on the left, scroll down to the `Help` section and select `Serial console`
+- After a short time, you will be shown the console for the VM. You may need to press a key to be shown the login prompt.
+- Log in with the details you retrieved earlier to be given root access to the VM.