Merge pull request #369 from alan-turing-institute/DSSG-SUMMER2019

DSSG deployment and troubleshooting changes

Author: martintoreilly

CONTRIBUTING.md

@@ -175,23 +175,25 @@ The following people have access to the project:
 | Name               | GitHub ID | Email |
 | ------------------ | --- | --- |
 | Diego Arenas       | [@darenasc](https://github.com/darenasc)| <darenasc@gmail.com> |
-| Jonathan Atkins     | [@jon-atkins](https://github.com/jon-atkins)| <jatkins@turing.ac.uk> |
-| Ayman Boustati      | [@aboustati](https://github.com/aboustati)| <aboustati@turing.ac.uk> |
-| Ian Carter          | [@getcarter21](https://github.com/getcarter21)| <icarter@turing.ac.uk> |
-| Rob Clarke          | [@RobC-CTL](https://github.com/RobC-CTL)| <rob.clarke@coriniumtech.com> |
-| Giovanni Colavizza  | [@Giovanni1085](https://github.com/Giovanni1085)| <gcolavizza@turing.ac.uk> |
-| Christine Foster    | [@ChristineFoster](https://github.com/ChristineFoster)| <cfoster@turing.ac.uk> |
-| Evelina Gabasova    | [@evelinag](https://github.com/evelinag)| <egabasova@turing.ac.uk> |
-| James Geddes        | [@triangle-man](https://github.com/triangle-man)| <jgeddes@turing.ac.uk> |
-| Andreas Grammenos   | [@andylamp](https://github.com/andylamp) | <axor@turing.ac.uk> |
-| Nicolas Guernion    | | <nguernion@turing.ac.uk> |
-| James Heatherington | [@jamespjh](https://github.com/jamespjh) | <jhetherington@turing.ac.uk> |
+| Jonathan Atkins    | [@jon-atkins](https://github.com/jon-atkins)| <jatkins@turing.ac.uk> |
+| Ayman Boustati     | [@aboustati](https://github.com/aboustati)| <aboustati@turing.ac.uk> |
+| Ian Carter         | [@getcarter21](https://github.com/getcarter21)| <icarter@turing.ac.uk> |
+| Rob Clarke         | [@RobC-CTL](https://github.com/RobC-CTL)| <rob.clarke@coriniumtech.com> |
+| Giovanni Colavizza | [@Giovanni1085](https://github.com/Giovanni1085)| <gcolavizza@turing.ac.uk> |
+| Christine Foster   | [@ChristineFoster](https://github.com/ChristineFoster)| <cfoster@turing.ac.uk> |
+| Evelina Gabasova   | [@evelinag](https://github.com/evelinag)| <egabasova@turing.ac.uk> |
+| James Geddes       | [@triangle-man](https://github.com/triangle-man)| <jgeddes@turing.ac.uk> |
+| Andreas Grammenos  | [@andylamp](https://github.com/andylamp) | <axor@turing.ac.uk> |
+| Nicolas Guernion   | | <nguernion@turing.ac.uk> |
+| James Hetherington | [@jamespjh](https://github.com/jamespjh) | <jhetherington@turing.ac.uk> |
 | Franz Kiraly       | [@fkiraly](https://github.com/fkiraly)| <fkiraly@turing.ac.uk> |
 | Catherine Lawrence | [@cathiest](https://github.com/cathiest) | <clawrence@turing.ac.uk> |
 | Martin O'Reilly    | [@martintoreilly](https://github.com/martintoreilly)| <moreilly@turing.ac.uk> |
 | Kenji Takeda       | [@ktakeda1](https://github.com/ktakeda1)| <ktakeda@turing.ac.uk> |
 | Sebastian Vollmer  | [@vollmersj](https://github.com/vollmersj)| <svollmer@turing.ac.uk> |
 | Kirstie Whitaker   | [@KirstieJane](https://github.com/KirstieJane)| <kwhitaker@turing.ac.uk> |
+| James Robinson     | [@jemrobinson](https://github.com/jemrobinson) | <jrobinson@turing.ac.uk> |
+
 
 ### Making a change with a pull request
 
@@ -268,4 +270,4 @@ You're awesome. :wave::smiley:
 [safehaven-labels]: https://github.com/alan-turing-institute/data-safe-haven/labels
 [safehaven-repo]: https://github.com/alan-turing-institute/data-safe-haven
 [safehaven-wiki]: https://github.com/alan-turing-institute/data-safe-haven/wiki
-[scrum-dailyscrum]: https://en.wikipedia.org/wiki/Scrum_(software_development)#Daily_Scrum
+[scrum-dailyscrum]: https://en.wikipedia.org/wiki/Scrum_(software_development)#Daily_Scrum

README.md

@@ -1 +1,10 @@
-# data-safe-haven
+# Data Safe Haven
+This repository contains the code necessary to deploy an instance of the Alan Turing Institute's Data Safe Haven.
+
+## Prerequisites
+- `Powershell`
+    - needed to deploy infrastructure
+- `bash`
+    - needed to deploy infrastructure
+- `Microsoft Azure` account
+    - target for infrastructure deployment

docs/README.md

@@ -0,0 +1,9 @@
+# Safe Haven User Guide
+
+- [Markdown version](safe_haven_user_guide.md) (always up to date)
+- [PDF version](safe_haven_user_guide.pdf) (requires manual regeneration)
+
+## Creating an updated PDF version
+- Install [Pandoc](https://pandoc.org/installing.html)
+- Install [XeLaTex](http://xetex.sourceforge.net/), generally by installing a full LaTeX environment such as [Tex Live](http://www.tug.org/texlive/) (Windows / Linux) or [MacTex](http://www.tug.org/mactex/) (MacOS).
+- Create PDF using `pandoc safe_haven_user_guide.md --pdf-engine=xelatex -o safe_haven_user_guide.pdf -V geometry:margin=1.2in`

docs/merge1.png docs/images/merge1.pngdocs/merge1.png renamed to docs/images/merge1.png

@@ -23,6 +23,7 @@
   * [Section 4.10: Outputs from the week](#section-410-outputs-from-the-week)
 * [Appendix A: Migrating to a new data science VM post package update](#appendix-a-migrating-to-a-new-data-science-vm-post-package-update)
 * [Appendix B: Gitlab tutorial notes](#appendix-b-Gitlab-tutorial-notes)
+* [Appendix C: Troubleshooting](#appendix-c-troubleshooting)
 
 ## Section 1: Support for bugs and reports
 
@@ -673,7 +674,7 @@ In Git, when you copy a project you say you “clone” it. To work on a git pro
 
 When you are on your Dashboard, click on the project that you’d like to clone. To work in the project, you can copy a link to the Git repository through a SSH or a HTTPS protocol. SSH is easier to use after it’s been set up, [you can find the details here](https://docs.gitlab.com/ee/gitlab-basics/create-your-ssh-keys.html). While you are at the Project tab, select HTTPS or SSH from the dropdown menu and copy the link using the Copy URL to clipboard button (you’ll have to paste it on your shell in the next step).
 
-![](project_clone_url.png)
+![](images/project_clone_url.png)
 
 Go to your computer’s shell and type the following command with your SSH or HTTPS URL:
 ```
@@ -805,12 +806,34 @@ Merge requests are useful to integrate separate changes that you’ve made to a
 3. Click on New merge request on the right side of the screen.
 4. From there on, you have the option to select the source branch and the target branch you’d like to compare to. The default target project is the upstream repository, but you can choose to compare across any of its forks.
 
-   ![](merge1.png)
+   ![](images/merge1.png)
 
 5. When ready, click on the Compare branches and continue button.
 6. At a minimum, add a title and a description to your merge request. Optionally, select a user to review your merge request and to accept or close it. You may also select a milestone and labels.
 
-   ![](merge2.png)
+   ![](images/merge2.png)
 
 7. When ready, click on the Submit merge request button.
 Your merge request will be ready to be approved and merged.
+
+## Appendix C: Troubleshooting
+
+### Unexpected certificate error
+
+#### Symptom
+- You can successfully log into the RDS webclient at `https://rds.dsgroupX.co.uk/RDWeb/weblient`
+- When you try and launch an app, you receive an error saying "Your session ended because an unexpected server authentication certificate was received from the remote PC."
+- When you click on the padlock icon in the address bar and view the SSL certificate, the "SHA-1 Fingerprint" in the certificate matches the "SHA-1 Thumbprint" in the error message.  
+
+  ![](images/unexpected_certificate_error.png)
+
+### Cause
+The SSL certificate protecting your connection to the RDS webclient expires every three months and is renewed every two months.
+The new SSL certificate is seamlessly picked up by your browser when connecting to `https://rds.dsgroupX.co.uk/RDWeb/weblient`.
+However, the webclient downloads a separate copy of the certificate for its own use to validate connections to the apps it serves.
+This downloaded certificate is cached by your browser, which means that the old certificate will continue to be used by the web app when the browser is allowed to load things from its cache.
+
+### Solution
+Get your browser to do a [hard reload](https://www.getfilecloud.com/blog/2015/03/tech-tip-how-to-do-hard-refresh-in-browsers/) of the page at `https://rds.dsgroupX.co.uk/RDWeb/weblient` (instructions vary by browser and operating system).
+This hard reload will reload items in the cache and so retrieve a copy of the new certificate.
+