# Deployment

Our team has explored various deployment options, ultimately selecting the method detailed in this guide for its efficacy. Additionally, for demonstration purposes, you can refer to the [Deployment to GitHub Pages](deployment-azure.md#deployment-to-github-pages) section for alternative deployment strategies you can use to showcase your updates.

## Deploying to Azure Web Apps (Windows) with IIS

This guide is crafted for individuals who already have access to the Azure subscription. It provides step-by-step instructions for setting up a new Azure Web App, specifically tailored for staging environments. Note that the process for setting up a production environment is similar, but requires a distinct web app name.

Deployments to Azure Web Apps are automated through GitHub Actions, forming an integral part of our Continuous Integration/Continuous Deployment (CI/CD) process. The CI/CD pipeline is configured to automatically trigger deployments upon merging changes into either the `staging` or `release` branches.

> [!NOTE]
> The deployment process outlined here is already established and running, hosted on Azure and sponsored by the .NET Foundation. This guide serves primarily as a reference for maintainers in the event that a new deployment setup is required.

### Setting up a new Azure Web App

Follow these instructions carefully to establish your Azure Web App in a staging environment. For deploying in a production environment, replicate these steps with an alternate web app name for differentiation.

1. Navigate to the [Azure Portal](https://portal.azure.com/)
1. Select **Create a resource**
1. Choose **Create a Web App**
1. In the Basic Tab
   - Choose your existing subscription and resource group
   - Under Instance Details, enter:
      - Name: **stride-docs-staging**
      - Publish: **Code**
      - Runtime stack: **ASP.NET V4.8**
      - OS: **Windows**
      - Region: as the current web
      - Pricing Plan - An existing App Service Plan should appear if the region and resource group match that of the existing web app. Currently we use **Standard S1**.
      - Click **Next**
1. In the Deployment Tab - This step can be completed later if preferred.
   - Enable Continuous deployment
   - Select account, organisation `Stride`, repository `stride-docs` and branch `staging`
   - Click **Next**
1. In the Monitoring Tab
   - Leave all settings as default
   - Click **Next**
1. Monitoring Tab
   - Disable Application Insights - This is not needed at this stage
   - Click **Next**
1. In the Tags Tab
   - Leave this blank unless you wish to add tags
   - Click **Next**
1. In the Review Tab
   - Review your settings
   - Click **Create**
   - The GitHub Action will be added to the repository and run automatically. It will fail at this stage, but this will be resolved in the subsequent steps.

> [!CAUTION]
> If you have completed the **Deployment Tab** process, ensure that the deployment profile includes the **DeleteExistingFiles** property. This property may need to be set to `False` or `True` depending on the specific requirements of your deployment. For instance, Stride Docs deployment retains files from previous deployments, allowing multiple versions like `4.2`, `4.1`, etc., to be maintained. Adjust this setting based on your deployment needs.

### Adjusting the Web App Configuration

1. Proceed to the newly created Web App
1. Click on **Configuration**
1. Select **General Settings**
1. Change the `Http version` to **2.0**
1. Change `Ftp state` to **FTPS only**
1. Change `HTTPS Only` to **On**
1. Click **Save** to apply the changes

### Modifying the GitHub Action

The previous step will have added a GitHub Action to your repository, which might fail initially. To address this, you need to modify the GitHub Action:

1. Navigate to the repository
1. Select **Actions**
1. You have the option to stop the currently running action
1. Locate the new GitHub Action file *(stride-docs/blob/master/.github/workflows/some-file-name.yml)* that was automatically generated by Azure Portal. We need to extract the `app-name` and `publish-profile` values from it and disable the push trigger.
   - To disable the push trigger, retain only **workflow_dispatch** (manual trigger) as shown below:
    ```
    on:
    #  push:
    #    branches:
    #      - staging
        workflow_dispatch:
    ```
1. Open the `stride-docs-staging-azure.yml` workflow and update it with the values obtained in the previous step. Save your changes.
1. This workflow might also need to be added to the `master` branch if it is not already present.
1. Execute the workflow `stride-docs-staging-azure.yml`. Ensure you select the correct branch `staging` and click **Run workflow**. This action will deploy the website to the Azure Web App.

### GitHub Actions

- `stride-website-github.yml`: Enables manual deployment to GitHub Pages in a forked repository, primarily for showcasing updates.
- `stride-docs-release-azure.yml`: Automates deployment to production upon merging changes into the `release` branch, with a manual trigger option also available.
- `stride-docs-release-fast-track-azure.yml`: Provides manual deployment to production, bypassing the creation of artifacts.
- `stride-docs-staging-azure.yml`: Facilitates automatic deployment to [staging](https://stride-doc-staging.azurewebsites.net/latest/en/index.html) when changes are merged into the `staging` branch, and includes a manual trigger option.
- `stride-docs-staging-fast-track-azure.yml`: Allows for manual deployment to staging, skipping the creation of artifacts.
- `stride-website-wiki.yml`: Automatically deploys to the GitHub Wiki when changes are pushed to the `wiki` folder in the `master` branch, also includes a manual trigger feature

## Deployment to GitHub Pages

To showcase your updates, especially helpful for design changes pending review, you can deploy the docs website either to your infrastructure or to GitHub Pages, a free hosting service. Once deployed, share the link with us for review.

### Prerequisites

In your `stride-docs` repository:

1. Navigate to **Settings** → **Actions** → **General** → **Workflow Permissions**
   - Choose **Read and write permissions**

### Run GitHub Action

1. Go to **Actions**, select **Build Stride Docs for GitHub Staging**
   - Click **Run workflow**; you may optionally select a branch
2. Monitor the build logs while the action is in progress
3. Upon successful build, a `gh-pages` branch will be created
4. Navigate to **Settings** → **Pages** → **Branch** section
   - Choose the `gh-pages` branch with the root option and click **Save**
5. After saving, an internal GitHub Action **pages build and deployment** is automatically created and triggered, deploying the content to the GitHub Pages website
6. The website will be accessible at `https://[your-username].github.io/stride-docs/4.2/en`
   - Change the version in the URL accordingly. You might see some JS errors, related to file expected in the root level.

### Add Custom Domain

Optionally, you can add also a custom domain. This should resolve JS url related errors.

1. Go to **Settings** → **Pages** → **Custom domain**
   - Enter your custom domain and follow the instructions for verification
1. Upon saving, the **pages build and deployment** action is triggered again, adding a `CNAME` file containing your custom domain name to the `gh-pages` branch
1. Your website should now be fully operational on your custom domain, for example, `https://stride-docs.vaclavelias.com/4.2/en/` is hosted on GitHub Pages