Merge branch 'main' into tamirkamara/app-insights-changes

docs/using-tre/index.md

@@ -1,9 +1,35 @@
 # Using TRE for Research
 
-!!! info
-    Coming soon
+This documentation part will cover how to use AzureTRE, extend it with your custom images and deploy it.
 
-We're working to improve our documentation, and fill in some gaps. Unfortunately, this particular page is one of the gaps we're looking to fill and isn't yet available.
+## AzureTRE deployment repo
+
+AzureTRE has an OSS deployment repository which you can find [here.](https://github.com/microsoft/AzureTRE-Deployment)
+It contains all the required tooling to develop your custom templates and deploy the Azure TRE:
+
+- Github Actions implementing AzureTRE automation, including running deployments to Azure
+- Configuration specific to deployment
+- Directories setup for: workspace, workspace service and user resource template definitions
+- Devcontainer setup
+
+### AzureTRE Reference
+
+AzureTRE deployment repository allows you to reference AzureTRE as a folder, but also uses it in its deployment. See [AzureTRE deployment readme](https://github.com/microsoft/AzureTRE-Deployment/blob/main/README.md) to learn more about it.
+
+## Getting Started
+
+To get started with AzureTRE follow the next steps:
+
+1. Go to [AzureTRE Deployment repository]((https://github.com/microsoft/AzureTRE-Deployment))
+1. Click on use this template to set up your project from this template:
+
+[![Use AzureTRE Deployment template](../assets/using-tre/use_template.png)](../assets/using-tre/use_template.png)
+
+1. Follow the steps in this [Github templates guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) to set up the repo.
+1. Having the project setup in your account, follow the next steps and guides to setup and extend AzureTRE in your environment:
+    - [Local development](docs/using-tre/local-development/index.md)
+    - Setup [CI/CD pipelines](docs/using-tre/pipelines/index.md)
+    - Add your [custom templates](docs/using-tre/templates/index.md)
 
 ## How to Contribute to our Documentation
 

docs/using-tre/local-development/index.md

@@ -0,0 +1,59 @@
+# Local Development
+
+This guide will cover how to setup local development environment to add custom templates to AzureTRE and deploy AzureTRE from the local machine.
+
+## Local Development Setup
+
+### Prerequisites
+
+To deploy an Azure TRE instance, the following assets and tools are required:
+
+* [Azure subscription](https://azure.microsoft.com)
+* [Azure Active Directory (AAD)](https://docs.microsoft.com/azure/active-directory/fundamentals/active-directory-whatis) tenant in which you can create application registrations
+* Git client such as [Git](https://git-scm.com/) or [GitHub Desktop](https://desktop.github.com/)
+* [Docker Desktop](https://www.docker.com/products/docker-desktop)
+
+### Development container
+
+The AzureTRE Deployment solution contains a [development container](https://code.visualstudio.com/docs/remote/containers) with all the required tooling to develop and deploy the AzureTRE and your custom templates to it. To deploy and extend an AzureTRE instance using the provided development container you will also need:
+
+* [Visual Studio Code](https://code.visualstudio.com)
+* [Remote containers extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+The files in AzureTRE Deployment repo for the dev container are located in `/.devcontainer/` folder.
+
+Having the prerequisites and the development container, to start local development follow the next steps:
+
+1. Clone the project you have created from the AzureTRE Deployment template `git clone <your_project>`
+1. Open it in Visual Studio Code
+1. VSCode will recognize the devcontainer is set up in and will ask to reopen in Devcontainer:
+    ![Open in devcontainer](../../assets/using-tre/reopen_in_devcontainer.png)
+
+After the devcontainer is built, you will see the AzureTRE folder which you can use as a reference for your templates. In addition the sample.env files will be added.
+## Local Deployment
+
+To run AzureTRE  deploy locally:
+
+1. Open your project in VScode devcontainer.
+2. Fill in all the required configuration. Follow [this guide](https://github.com/microsoft/AzureTRE-Deployment#congiguration-setup) to set it up.
+3. run `make all`
+
+!!! tip
+    The Makefile in the AzureTRE deployment repository sources the make commands from AzureTRE that it references. This allows you to add your commands and also use the same make commands used in the AzureTRE.
+
+
+Having all the env vars in place:
+
+## How to Contribute to our Documentation
+
+If you have any comments or suggestions about our documentation then you can visit our GitHub project and either raise a new issue, or comment on one of the existing ones.
+
+You can find our existing documentation issues on GitHub by clicking on the link below:
+
+[Existing Documentation Issues](https://github.com/microsoft/AzureTRE/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation)
+
+Or, you can raise a new issue by clicking on this link:
+
+[Report an Issue or Make a Suggestion](https://github.com/microsoft/AzureTRE/issues/new/choose)
+
+**Thank you for your patience and support!**

docs/using-tre/pipelines/index.md

@@ -0,0 +1,63 @@
+# Pipelines
+
+The [AzureTRE deployment repository](https://github.com/microsoft/AzureTRE-Deployment) contains the following github workflows:
+
+1. Build Validation - validates the code by running linter and terraform validation.
+1. Clean Validation Environments - a periodical workflow to clean unused AzureTRE environments.
+1. Deploy Azure TRE (branch) - This workflow is intended to be used to test workflow changes. It deploys AzureTRE using the workflows defined on the branch
+1. Deploy Azure TRE - This workflow is the integration build run for pushes to the main branch. It also runs on a schedule, serving as the nightly build to keep the main AzureTRE env in sync.
+1. Deploy Azure TRE Reusable - responsible to deploy AzureTRE. It is referenced in other Azure TRE deployment workflows.
+
+
+## Setup Github Environment
+
+The workflows are using Github environment to source its environment variables. Follow [this guide](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#creating-an-environment) to define it in your github repository and provide it as an input for the workflows.
+
+The following environment variables should be defined in your github environment:
+
+1. [Auth env vars](auth.md##create_authentication_assets)
+1. [Core and Devops env vars](docs/tre-admins/environment-variables.md)
+1. Setup Azure Container Registry (ACR) to hold the devcontainer images:
+    1. Create ACR to hold the devcontainer images following [this guide](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-get-started-portal?tabs=azure-cli).
+    1. [Enable Admin Account](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-authentication?tabs=azure-cli#admin-account)
+    1. Having setup the previous steps, add the created ACR info to your Github Actions environment:
+
+    | <div style="width: 330px">Environment variable name</div> | Description                                                                       |
+    | --------------------------------------------------------- | --------------------------------------------------------------------------------- |
+    | `ACTIONS_ACR_NAME`                                        | The Azure Container registry name that the devcontainer is stored in.             |
+    | `ACTIONS_ACR_URI`                                         | The full uri of the Azure Container Registry where the devcontainer is stored in. |
+    | `ACTIONS_ACR_PASSWORD`                                    | The Azure Container registry password for the devcontainer.                       |
+    | `ACTIONS_DEVCONTAINER_TAG`                                | The container label to use when running the command.                              |
+
+
+Having all the environment variables set in the Github environment the next step will be to use it in your pipelines:
+
+In AzureTRE deployment repository You will find all the pipelines under the folder `.github/workflows` on top of each workflow there is the workflow
+inputs part where the used Github environment name is set, make sure to update it with yours, for example:
+
+![Setup env in pipeline](../../assets/using-tre/pipelines_set_env.png)
+
+## Publish Custom Templates in Pipelines
+
+If you have created custom AzureTRE templates you can publish and register them as part of the CI/CD pipelines. To do so follow the next steps:
+1. Go to `.github/workflows/deploy_tre_reusable.yml` workflow. Add your template under the following jobs:
+    - publish_bundles:
+        ![Publish bundle](../../assets/using-tre/push_bundles_step.png)
+    - register_bundles:
+        ![Register bundle](../../assets/using-tre/register_bundles.png)
+    - If it is a user resource add it also under register_user_resource_bundles:
+        ![Register user resource step](../../assets/using-tre/register_user_resource.png)
+
+## How to Contribute to our Documentation
+
+If you have any comments or suggestions about our documentation then you can visit our GitHub project and either raise a new issue, or comment on one of the existing ones.
+
+You can find our existing documentation issues on GitHub by clicking on the link below:
+
+[Existing Documentation Issues](https://github.com/microsoft/AzureTRE/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation)
+
+Or, you can raise a new issue by clicking on this link:
+
+[Report an Issue or Make a Suggestion](https://github.com/microsoft/AzureTRE/issues/new/choose)
+
+**Thank you for your patience and support!**

docs/using-tre/templates/index.md

@@ -0,0 +1,46 @@
+# Creating Custom templates
+
+This document will show how to create custom templates, integrate them into your CI/CD pipelines.
+
+## Templates types
+
+There are 3 types of templates:
+
+1. Workspace
+1. Workspace Service
+1. User Resource
+
+Read more about them [here](../../index.md#workspace)
+
+## How to add custom templates
+
+AzureTRE deployment repository has directories setup for: workspace, workspace service and user resource template definitions.
+
+See [template authoring guide](../../tre-workspace-authors/authoring-workspace-templates.md) to learn more about how to author templates.
+
+**To add your custom templates follow the next steps:**
+- Deployment requirements
+    1. Add your template under relevant folder (For example: if you are adding a new workspace template then place it under /templates/workspaces folder).
+    1. Use existing templates in AzureTRE as a reference.
+    1. Add porter configuration - AzureTRE uses [Porter](https://porter.sh/) as a solution for implementing and deploying workspaces and workspace, learn more about how it is used in AzureTRE [here](https://microsoft.github.io/AzureTRE/tre-developers/resource-processor/#porter).
+    1. Add terraform scripts to setup your deployment plan.
+- Define resource template in the API - follow [this readme](https://microsoft.github.io/AzureTRE/tre-admins/registering-templates/) to register your template.
+- Use the [AzureTRE UI](https://microsoft.github.io/AzureTRE/tre-developers/ui/) to deploy your resources
+- Add your custom templates to CI/CD workflows - in Deploy Azure TRE Reusable workflow make sure to add your bundles under register_bundles and publish_bundles steps.
+
+## Publish and Register Custom templates in the CI/CD
+
+See the [pipelines documentation](../pipelines/index.md) to learn more about publishing and registering your custom templates as part of the CI/CD/
+## How to Contribute to our Documentation
+
+If you have any comments or suggestions about our documentation then you can visit our GitHub project and either raise a new issue, or comment on one of the existing ones.
+
+You can find our existing documentation issues on GitHub by clicking on the link below:
+
+[Existing Documentation Issues](https://github.com/microsoft/AzureTRE/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation)
+
+Or, you can raise a new issue by clicking on this link:
+
+[Report an Issue or Make a Suggestion](https://github.com/microsoft/AzureTRE/issues/new/choose)
+
+**Thank you for your patience and support!**

docs/using-tre/upgrading-tre/index.md

@@ -0,0 +1,37 @@
+# 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)
+
+## Introduction
+
+AzureTRE referenced as an external folder in [AzureTRE deployment repository](https://github.com/microsoft/AzureTRE-Deployment). A specific version of it is downloaded as part of 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
+
+Select AzureTRE version:
+1. In AzureTRE go to releases:
+    ![Go to AzureTRE releases](../../assets/using-tre/select_release.png)
+1. Choose a release version
+
+To upgrade AzureTRE version inside [AzureTRE deployment repository](https://github.com/microsoft/AzureTRE-Deployment):
+1. Go to devcontainer.json file
+1. Update the OSS_VERSION param to the desired version.
+
+    ![Upgrade TRE Version](../../assets/using-tre/upgrade_tre_version.png)
+
+
+
+## How to Contribute to our Documentation
+
+If you have any comments or suggestions about our documentation then you can visit our GitHub project and either raise a new issue, or comment on one of the existing ones.
+
+You can find our existing documentation issues on GitHub by clicking on the link below:
+
+[Existing Documentation Issues](https://github.com/microsoft/AzureTRE/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation)
+
+Or, you can raise a new issue by clicking on this link:
+
+[Report an Issue or Make a Suggestion](https://github.com/microsoft/AzureTRE/issues/new/choose)
+
+**Thank you for your patience and support!**