Add note in manual deployment steps about using LETSENCRYPT_DROP_ALL_RULES

CHANGELOG.md

@@ -6,7 +6,7 @@ FEATURES:
 ENHANCEMENTS:
 
 BUG FIXES:
-* Cusotm actions fail on resources with a pipline ([#3646](https://github.com/microsoft/AzureTRE/issues/3646))
+* Custom actions fail on resources with a pipeline ([#3646](https://github.com/microsoft/AzureTRE/issues/3646))
 
 ## 0.12.0 (July 27, 2023)
 

docs/tre-admins/setup-instructions/manual-deployment.md

@@ -31,6 +31,12 @@ make letsencrypt
 !!! info
     If you're using Codespaces, you'll encounter a bug when trying to run `make letsencrypt` where the incorrect IP will be whitelisted on the storage account and Codespaces won't be able to upload the test file due to a 403 error. The workaround until this is fixed is to temporarily disable the firewall on your `stweb{TRE_ID}` storage account before running the script, then re-enable afterwards.
 
+    The script can do this for you if you run it with setting a LETSENCRYPT_DROP_ALL_RULES environment variable to `1`:
+
+    ```bash
+    LETSENCRYPT_DROP_ALL_RULES=1 make letsencrypt
+    ```
+
 ## Validate the deployment
 
 ### Using curl

docs/tre-admins/upgrading-tre.md

@@ -1,33 +1,35 @@
 # Upgrading AzureTRE version
 
-This document will cover how AzureTRE is referenced and how to upgrade its version in the [AzureTRE deployment repository](https://github.com/microsoft/AzureTRE-Deployment)
+This document will cover how Azure TRE is referenced and how to upgrade its version in the [Azure TRE deployment repository](https://github.com/microsoft/AzureTRE-Deployment)
 
 ## Introduction
 
-AzureTRE referenced as an external folder in [AzureTRE deployment repository](https://github.com/microsoft/AzureTRE-Deployment) (which is used as a template for your project in the quick start guide). A specific version of AzureTRE is downloaded as part of devcontainer setup.
+Azure TRE is referenced as an external folder in the [Azure TRE deployment repository](https://github.com/Microsoft/AzureTRE-Deployment) (which is used as a template for your project in the quick start guide). A specific version of Azure TRE is downloaded as part of the devcontainer setup.
 
 A symlink is then created making it available to reference in the directory itself (it is available only for reference, any changes to it are gitignored).
 
-## How to upgrade AzureTRE version
+## How to upgrade the Azure TRE version
 
 > Please check the release notes before upgrading.
 
-- If using the [AzureTRE deployment repository](https://github.com/microsoft/AzureTRE-Deployment) directly (not one created using a Template), you need to git pull the latest version.
+- If using the [Azure TRE deployment repository](https://github.com/microsoft/AzureTRE-Deployment) directly (not one created using a Template), you need to git pull the latest version.
 
-- If using a repository created from the `AzureTRE-Deployment` template then run following git command in your own repo:
+- If using a repository created from the `AzureTRE-Deployment` template, then run the following git commands in your own repo:
 ```sh
-git remote add upstream https://github.com/microsoft/AzureTRE-Deployment
+git remote add upstream https://github.com/Microsoft/AzureTRE-Deployment
 git pull upstream main --allow-unrelated-histories
 ```
-This will pull the latest version of AzureTRE to your copy of the repository. You may need to resovle merge conflicts if you have made edits.
+This will pull the latest version of AzureTRE to your copy of the repository. You may need to resolve merge conflicts if you have made edits.
+The `git remote add` command is only necessary the first time you upgrade your TRE version. After the first time, you only need to execute the `git pull` command.
 
-Once the code is merged follow same process used to initally deploy the TRE to upgrade the TRE. This might mean running a command such as `make all`, or running your CI/CD pipeline(s).
+Once the code is merged, follow the same process used to initially deploy the TRE to upgrade the TRE. This might mean running a command such as `make all`, or running your CI/CD pipeline(s).
 
 > If running commands manually, please ensure that you build and push the container images. Running `make tre-deploy` alone will update the infrastructure but not the container images. `make all` runs all the required commands.
 
 ## Deploying a specific version of Azure TRE
 
-If you wish to upgrade or deploy a specific version, or unreleased version of Azure TRE and are using the [AzureTRE deployment repository](https://github.com/microsoft/AzureTRE-Deployment) you can change the value of `OSS_VERSION` in `.devcontainer/devcontainer.json`, for example:
+If you wish to upgrade or deploy a specific version, or unreleased version of Azure TRE and are using the [Azure TRE deployment repository](https://github.com/Microsoft/AzureTRE-Deployment) you can change the value of `OSS_VERSION` in `.devcontainer/devcontainer.json`, for example:
 
-- `"OSS_VERSION": "v0.9.0"`
-- `"OSS_VERSION": "main"`
+- `"OSS_VERSION": "v0.9.0"` (to use the specified tag; be sure to specify the complete tag name (prefixed with `v` and not the release name)
+- `"OSS_VERSION": "main"` (to use the latest code in the "main" branch)
+- `"OSS_VERSION": "1c6ff35ec9246e53b86e93b9da5b97911edc71c1"` (to use the code at the time of the commit identified by the hash)

docs/tre-templates/shared-services/nexus.md

@@ -24,11 +24,11 @@ You can use the Certs Shared Service to set one up by following these steps:
 3. Select the Certs template, then fill in the required details. *Domain prefix* should be set to `nexus` and *Cert name* should be `nexus-ssl`.
 
 !!! caution
-    If you have KeyVault Purge Protection enabled and are re-deploying your environment using the same `cert_name`, you may encounter this: `Status=409 Code=\"Conflict\" Message=\"Certificate nexus-ssl is currently in a deleted but recoverable state`. You need to either manually recover the certificate or purge it before redeploying.
+    If you have Key Vault Purge Protection enabled and are re-deploying your environment using the same `cert_name`, you may encounter this: `Status=409 Code=\"Conflict\" Message=\"Certificate nexus-ssl is currently in a deleted but recoverable state`. You need to either manually recover the certificate or purge it before redeploying.
 
-Once deployed, the certs service will use Letsencrypt to generate a certificate for the specified domain prefix followed by `-{TRE_ID}.{LOCATION}.cloudapp.azure.com`, so in our case, having entered `nexus`, this will be `nexus-{TRE_ID}.{LOCATION}.cloudapp.azure.com`, which will be the public domain for our Nexus service.
+Once deployed, the certs service will use Let's Encrypt to generate a certificate for the specified domain prefix followed by `-{TRE_ID}.{LOCATION}.cloudapp.azure.com`, so in our case, having entered `nexus`, this will be `nexus-{TRE_ID}.{LOCATION}.cloudapp.azure.com`, which will be the public domain for our Nexus service.
 
-You can verify whether this has been successful by navigating to your core keyvault (`kv-{TRE_ID}`) and looking for a certificate called `nexus-ssl` (or whatever you called it).
+You can verify whether this has been successful by navigating to your core Key Vault (`kv-{TRE_ID}`) and looking for a certificate called `nexus-ssl` (or whatever you called it).
 
 After verifying the certificate has been generated, you can deploy Nexus:
 
@@ -40,13 +40,13 @@ After verifying the certificate has been generated, you can deploy Nexus:
 
 1. Navigate back to the TRE UI, and click *Create new* again within the Shared Services page.
 
-1. Select the Nexus template then fill in the required details. The *SSL certificate name* should default to `nexus-ssl`, so there's no need to change it unless you gave it a different name in the previous step.
+1. Select the Nexus template, then fill in the required details. The *SSL certificate name* should default to `nexus-ssl`, so there's no need to change it unless you gave it a different name in the previous step.
 
 This will deploy the infrastructure required for Nexus, then start the service and configure it with the repository configurations located in the `./templates/shared_services/sonatype-nexus-vm/scripts/nexus_repos_config` folder. It will also set up HTTPS using the certificate you generated in the previous section, so proxies can be served at `https://nexus-{TRE_ID}.{LOCATION}.cloudapp.azure.com`.
 
 ## Setup and usage
 
-1. A TRE Administrator can access Nexus though the admin jumpbox provisioned as part of the TRE deployment. The username is `adminuser` and the password is located in the KeyVault under `vm-<tre-id>-jumpbox-password`
+1. A TRE Administrator can access Nexus though the admin jumpbox provisioned as part of the TRE deployment. The username is `adminuser` and the password is located in the Key Vault under `vm-<tre-id>-jumpbox-password`
 2. A researcher can access Nexus from within the workspace by using the internal Nexus URL of `https://nexus-{TRE_ID}.{LOCATION}.cloudapp.azure.com`
 3. To fetch Python packages from the PyPI proxy, a researcher can use `pip install` while specifying the proxy server:
 
@@ -55,7 +55,7 @@ This will deploy the infrastructure required for Nexus, then start the service a
     ```
 
 !!! info
-    In the built-in Linux and Windows Guacamole VM bundles, PyPI and several other package managers are already configured to use the Nexus proxy by default, so manually specifying in the install commands isn't neccesary.
+    In the built-in Linux and Windows Guacamole VM bundles, PyPI and several other package managers are already configured to use the Nexus proxy by default, so manually specifying in the install commands isn't necessary.
 
 ## Network requirements
 
@@ -108,6 +108,6 @@ If you still have an existing Nexus installation based on App Service (from the
 
 ## Renewing certificates for Nexus
 
-The Nexus service checks Keyvault regularly for the latest certificate matching the name you passed on deploy (`nexus-ssl` by default).
+The Nexus service checks Key Vault regularly for the latest certificate matching the name you passed on deploy (`nexus-ssl` by default).
 
-When approaching expiry, you can either provide an updated certificate into the TRE core KeyVault (with the name you specified when installing Nexus) if you brought your own, or if you used the certs shared service to generate one, just call the `renew` custom action on that service. This will generate a new certificate and persist it to the Keyvault, replacing the expired one.
+When approaching expiry, you can either provide an updated certificate into the TRE core KeyVault (with the name you specified when installing Nexus) if you brought your own, or if you used the certs shared service to generate one, just call the `renew` custom action on that service. This will generate a new certificate and persist it to the Key Vault, replacing the expired one.