Table of Contents

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 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
  2. Select Create a resource
  3. Choose Create a Web App
  4. 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
  5. 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
  6. In the Monitoring Tab
    • Leave all settings as default
    • Click Next
  7. Monitoring Tab
    • Disable Application Insights - This is not needed at this stage
    • Click Next
  8. In the Tags Tab
    • Leave this blank unless you wish to add tags
    • Click Next
  9. 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
  2. Click on Configuration
  3. Select General Settings
  4. Change the Http version to 2.0
  5. Change Ftp state to FTPS only
  6. Change HTTPS Only to On
  7. 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
  2. Select Actions
  3. You have the option to stop the currently running action
  4. 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:
  5. Open the stride-docs-staging-azure.yml workflow and update it with the values obtained in the previous step. Save your changes.
  6. This workflow might also need to be added to the master branch if it is not already present.
  7. 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 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
  2. 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
  3. 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
Edit this page