Basic deployment docs

docs/source/deployment/deploy_context.md

@@ -0,0 +1,44 @@
+(deploy_context)=
+
+# Deploy the Data Safe Haven Context
+
+The 'Context' is a collection of infrastructure, which _is not_ part of your TRE, but which is used to deploy and manage your TRE.
+It contains, for example, storage for synchronising persistent configuration information.
+
+:::{important}
+The Context **must** be deployed before any other TRE components.
+:::
+
+## Configuration
+
+A local context configuration file (`context.yaml`) holds the information necessary to find and access a context.
+
+:::{note}
+You can specify the directory where your context configuration (context.yaml) is stored by setting the environment variable `DSH_CONFIG_DIRECTORY`.
+:::
+
+## Creating a context
+
+- You will need to provide some options to set up your DSH context. You can see what these are by running the following:
+
+```{code} shell
+$ dsh context add --help
+```
+
+- Run a command like the following to create your local context file.
+
+```{code} shell
+$ dsh context add <KEY> --admin-group <group name> --location <location> --name <human friendly name> --subscription <Azure subscription name>
+```
+
+:::{note}
+If you have multiple contexts defined, you can select which context you want to use with `dsh context switch <KEY>`.
+:::
+
+## Deployment
+
+- Now create the necessary infrastructure with
+
+```{code} shell
+$ dsh context create
+```

docs/source/deployment/deploy_shm.md

@@ -0,0 +1,55 @@
+(deploy_shm)=
+
+# Deploy a Safe Haven Management Environment (SHM)
+
+These instructions will deploy a new Safe Haven Management Environment (SHM).
+This is required to manage your Secure Research Environments (SREs) and **must be** deployed before you create any SREs.
+
+:::{note}
+A single SHM can manage all your SREs.
+However, you may choose to use multiple SHMs if, for example, you want to separate production and development environments.
+:::
+
+## Configuration
+
+- Create a configuration file
+
+```console
+> dsh config template --file config.yaml
+```
+
+- Edit this file in your favourite text editor, replacing the placeholder text with appropriate values for your setup.
+
+```yaml
+- azure
+  - tenant id # your deployment account's home tenant `az account show`
+  - subscription id # the subscription you will deploy to
+-  shm
+  - aad_tenant id # the tenant id **of the Entra ID used to manage TRE users**
+```
+
+## Upload the configuration file
+
+- Upload the config to Azure. This will validate your file and report any problems.
+
+```{code} shell
+$ dsh config upload config.yaml
+```
+
+## Deployment
+
+- Next deploy the Safe Haven Management (SHM) infrastructure [approx 30 minutes]:
+
+```{code} shell
+$ dsh deploy shm
+```
+
+Run `dsh deploy shm -h` to see the necessary command line flags and provide them as arguments.
+
+:::{important}
+You may be asked to delegate your domain name to Azure. To do this, you'll need to know details about the parent domain. For example, if you are deploying to `dsh.example.com` then the parent name is `example.com`.
+
+- Follow [this tutorial](https://learn.microsoft.com/en-us/azure/dns/dns-delegate-domain-azure-dns#delegate-the-domain) if the parent domain is hosted outside Azure
+- Follow [this tutorial](https://learn.microsoft.com/en-us/azure/dns/tutorial-public-dns-zones-child#verify-the-child-dns-zone) if the parent domain is hosted in Azure
+
+:::

docs/source/deployment/deploy_sre.md

@@ -0,0 +1,32 @@
+(deploy_sre)=
+
+# Deploy a Secure Research Environment (SRE)
+
+## Configuration
+
+Each project will have its own dedicated Secure Research Environment (SRE).
+
+Make sure that your config file contains one or more SRE sections.
+
+:::{tip}
+You can check this by running: `dsh config show` and looking at the `sres` section.
+:::
+
+## Requirements
+
+:::{important}
+As private endpoints for flexible PostgreSQL are still in preview, the following command is currently needed:
+
+```{code} shell
+$ az feature register --name "enablePrivateEndpoint" --namespace "Microsoft.DBforPostgreSQL"
+```
+
+:::
+
+## Deployment
+
+- Deploy each SRE individually [approx 30 minutes]:
+
+```{code} shell
+$ dsh deploy sre <name of your SRE>
+```

docs/source/deployment/index.md

@@ -0,0 +1,51 @@
+# Deployment
+
+```{toctree}
+:hidden:
+
+deploy_context.md
+deploy_shm.md
+deploy_sre.md
+```
+
+Deploying an instance of the Data Safe Haven involves the following steps:
+
+- Deploying the context used to host the Pulumi backend infrastructure
+- Deploying the Safe Haven management component
+- Deploying a Secure Research Environment for each project
+
+## Requirements
+
+Install the following requirements before starting
+
+- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
+- [Hatch](https://hatch.pypa.io/1.9/install/)
+- [Pulumi](https://www.pulumi.com/docs/get-started/install/)
+
+:::{important}
+You will also need an account with `Global Administrator` privileges on a Microsoft Entra tenant.
+:::
+
+:::{hint}
+We suggest creating a new Entra tenant for your DSH deployment, but this is not a requirement.
+If you want to do so, follow the instructions [here](https://learn.microsoft.com/en-us/entra/fundamentals/create-new-tenant).
+:::
+
+## Install the project
+
+Download or checkout this code from GitHub.
+
+:::{important}
+**{sub-ref}`today`**: you should use the `develop` branch as no stable v5 release has been tagged.
+Please contact the development team in case of any problems.
+:::
+
+Enter the base directory and run:
+
+```{code} shell
+$ hatch shell
+```
+
+:::{hint}
+Using a hatch environment this way ensures that you are using the intended version of Data Safe Haven with the correct set of dependencies.
+:::

docs/source/index.md

@@ -7,6 +7,7 @@
 overview/index.md
 design/index.md
 deployment/index.md
+management/index.md
 roles/index.md
 contributing/index.md
 ```
@@ -39,6 +40,8 @@ You can read them through in order or simply jump to the section that you are mo
     - If you want details about the technical design of the Data Safe Haven.
 - [**Deployment**](deployment/index.md)
     - If you want to deploy your own Data Safe Haven.
+- [**Management**](management/index.md)
+    - If you want to manage a Data Safe Haven that you (or someone else) has deployed.
 - [**Roles**](roles/index.md)
     - Information about the different user roles in the Data Safe Haven.
     - Instructions and advice for the actions of different user roles.