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 done through GitHub Actions. The documentation of each version is deployed from its own branch into its own folder of the site (i.e. 4.4/), while the files shared by all versions at the root of the site (versions.json, web.config and robots.txt) are deployed from master. See GitHub Actions for details.

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, the generated workflow deploys the whole site. Disable it as described below: Stride Docs deployments only replace the folder of one version (or the root files), so that multiple versions like 4.2, 4.1, etc. are maintained.

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-deploy-azure.yml and stride-docs-site-root-azure.yml workflows and update them with the values obtained in the previous step. Save your changes.
  6. Execute the workflow stride-docs-site-root-azure.yml from master, selecting the slot, and click Run workflow. This deploys the files shared by all versions.
  7. Execute the workflow stride-docs-deploy-azure.yml from the branch of each version to host (master, master-4.3, ...), selecting the slot, and click Run workflow. Each run deploys one version folder to the Azure Web App.

GitHub Actions

  • stride-docs-github.yml: Enables manual deployment to GitHub Pages in a forked repository, primarily for showcasing updates.
  • stride-docs-deploy-azure.yml: Manually deploys the documentation of the branch it runs from into its version folder, to staging or production.
  • stride-docs-site-root-azure.yml: Deploys versions.json, web.config and robots.txt from master, automatically to staging when they change, and manually to staging or production.
  • stride-docs-test-build.yml: Builds the documentation manually and uploads it as an artifact without deploying anywhere, useful for verifying that a change builds.

For a detailed breakdown of the jobs, triggers, inputs and secrets these workflows use, see GitHub Actions.

Kudu (Advanced Tools)

Each Azure Web App comes with Kudu, a management site to browse, edit and run commands on the files of the web app, without deploying:

It's also reachable from the Azure Portal, in the Web App: Development Tools → Advanced Tools → Go. It requires access to the Azure subscription.

In Debug console → PowerShell, the site is in D:\home\site\wwwroot (a folder per version, and the files shared by all versions at its root), and the logs are in D:\home\LogFiles. Files can be edited in the browser, or with commands in the console.

Old Versions

The documentation of 4.2 and older can't be rebuilt anymore: its toolchain (Docfx version, build scripts) is too outdated, and its branches (master-3.0 ... master-4.2) don't have deployment workflows. It's frozen as deployed, and the rare fixes it needs (e.g. the version selector) are made directly on the server with Kudu.

  • Back up a file before editing it (e.g. main.js.bak), and prefer an idempotent script when the same change applies to several versions.
  • Commit the same change to the branch of the version, so that the branch keeps matching what's deployed.
  • These versions read versions.json from the root of the site, so its format can only gain fields (see the comment in the file).

Request Logs

Some rules of web.config are only needed by old clients (e.g. the Stride Launcher 5.x and older), and say when they become obsolete. To check whether a URL is still requested, enable the web server logs: in the Web App, Monitoring → App Service logs → Web server logging: File System, with a quota (e.g. 35 MB) and a retention period (e.g. 30 days).

The IIS logs are then in D:\home\LogFiles\http\RawLogs. For instance, to count the requests of launchers 5.x and older for release notes, in the Kudu PowerShell console:

Select-String -Path D:\home\LogFiles\http\RawLogs\*.log -Pattern ' /\d+\.\d+/ReleaseNotes/ReleaseNotes\.md ' | Measure-Object
Note

Azure Front Door serves the site from its cache when it can, so the web app only logs part of the requests. The counts are lower than the real traffic, but a URL that doesn't appear in the logs for weeks isn't requested anymore.

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 forked stride-docs repository:

  1. Navigate to Settings → Pages → Build and deployment
    • Under Source, choose GitHub Actions
Note

This workflow uses GitHub's native Pages deployment, which publishes the built site directly from the workflow run. It does not create a gh-pages branch, so do not select Deploy from a branch.

Run GitHub Action

  1. Go to Actions, select Build Stride Docs for GitHub Staging
    • Click Run workflow; you may optionally select a branch and adjust the build inputs
  2. Monitor the build logs while the action is in progress
  3. Upon a successful build, the deploy job publishes the site and the resulting URL is shown on the run page, next to the github-pages environment
  4. The website will be accessible at https://[your-username].github.io/stride-docs/4.4/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. Re-run the workflow so the site is republished under the new domain
  3. Your website should now be fully operational on your custom domain, for example, https://stride-docs.vaclavelias.com/4.4/en/ is hosted on GitHub Pages
Edit this page