Get Docusaurus Running on Azure Static Web App

Written By Andrew Huddleston

Docusaurus is a popular open-source static site generator that is designed to make it easy to create and maintain documentation websites. In this blog, we'll cover the steps for getting Docusaurus up and running on Azure Static Web Apps with Azure Active Directory (AAD) authentication. 

Why Docusaurus & Azure Static Web Apps?

Docusaurus is an easy-to-use documentation website builder for documentation. It is well documented on their website https://docusaurus.io/ with installation instructions and a discord channel if you have questions. It is easy to get started with and requires minimal setup and configuration. Docusaurus also has several features that make it well-suited for documentation websites, including support for Markdown, versioning, search, and localization.

Azure Static Web Apps is a fully managed service that allows you to deploy static web applications to the cloud. A static web app is a web application that is built using only static files, such as HTML, CSS, and JavaScript. One of the main benefits of Azure Static Web Apps is the ability to automatically build and deploy your web application from a Git repository, such as GitHub or Azure DevOps. This allows you to update your web app quickly and easily, without the need to manually upload files or perform manual deployments. Azure Static Web Apps also provides several features that can improve the performance and security of your web application. These features include automatic SSL certificate management, custom domain support, and the ability to enable Azure Active Directory (AAD) authentication. 

Requirements 

First there is a few things you need to get this up and running

  • A Git repository, such as GitHub or Azure DevOps, this example will be using Azure DevOps 

  • An Azure Subscription where you can host your Azure Static Web App. If you don’t have a subscription you can play with, here is a link to create a free account 

  • Tools to install locally: 

  • For MacOS: 

    • Brew, link to install here 

      • You need this to install the other tools 

    • Node.js 

      • You need this to test Docusaurus locally 

      • brew install node 

    • Yarn 

      • You need this to test Docusaurus locally 

      • brew install yarn 

  • For Windows: 

    • Follow these steps to install npm and Node.js 

    • Follow these steps to install yarn 

Getting Docusaurus up and running 

I will outline here how to install Docusaurus, but here is the link to their install instructions for the latest instructions. 

  1. In your Git repository, run the following steps: 

    1. npx create-docusaurus@latest www classic 

      1. NOTE: This creates a www folder, you can name this whatever you would like 

    2. cd www 
    3. npx docusaurus start 

      1. This will run the website locally and open your browser so you can see it running and what it looks like 

  2. Prepare it for deployment to Azure Static Web Apps: 

    1. In a different terminal window or ctrl-c the local run in the previous step: 

      1. npm run build 

        1. This will create a build repo 

        2. This step can sometimes fail looking for dependencies, but
          yarn run build
          did work for me when that happened 

Creating Azure Static Web App 

  1. Open the Azure Portal and sign in  

  2. Type Static Web App in the Azure Search at the top, and click Static Web App under Services 

  3. Click + Create 

  4. Enter in the required fields, see our example below: 

    • For Plan type if you want to do Azure AD authentication like we are doing in this example you need to use the Standard tier 

    • For App Location make sure you put the same folder from step 1 of getting Docusaurus up and running. In our example we are using www but this could be named whatever you would like.  

    • For Build Presets it must be React, because Docusaurus is built with React 

 NOTE: As you can see in our example, we are using Azure DevOps which if you are using the same login for Azure DevOps as the Azure Portal you won’t need to do anything extra, your repo will show up. If you are using GitHub, you do have to auth to GitHub for Azure to be able to see your repositories  

  1. Click Review + create to finish creating your Static Web App 

  2. After your Static Web App finishes creating you should see a URL that Azure generates for you. If you browse that you should see your Docusaurus Site up and running on the internet for anyone to see.  

Troubleshooting 

If your site doesn’t come up when you build it with the Static Web App, click on the Azure DevOps pipeline under Deployment history  

NOTE: This will be in the same place “Deployment History” if you use GitHub it will just be named different 

In the Pipeline run you could see if you can see if there are any errors to see what is causing it to fail. Most likely it is because the npm run build failed. You can try to run this locally like we did in the Docusaurus section above, if it works locally it should work in the pipeline but make sure to read any errors which will tell you why its failing.  

Updating your site 

To update the Docusaurus site; adding new docs, rename things, styling, formatting, etc. It is very simple, make the changes locally, I recommend using an IDE like VS Code or something similar so you can preview the Markdown files before you push it up. You can also see your changes running it locally 
 
After you make your changes make sure to do the following: 

  • Run the site locally to make sure it looks like you want and builds correctly and so the pipeline doesn’t fail.  

    • In case your forgot how to do that: 

      • cd www 
      • npx docusaurus start 

  • Run npm run build or yarn run build locally to make sure it builds, again so the pipeline doesn’t fail 

Once your changes are finalized just push it up to the branch you pointed your Static Web App to and the pipeline will auto redeploy the changes so your Static Web App, and you should see them when you go to your URL shortly. 

Azure also has something called Preview Deployments, when you make a pull request to the branch you point Static Web App to it will create a preview deployment that you can browse before its merged into the main branch. 

OPTIONAL: Setting up Azure AD authentication to your Static Web App 

To add Azure Active Directory Authentication to your Static Web App, follow the below steps:

  1. First thing you need to do is create and App Registration in Azure.  

    1. Search App Registration in the Azure Portal and click App Registrations under Services 

    2. Click + New Registration 

    3. Fill out the form 

      1. Name it whatever you would like 

      2. For Supported account types, select Accounts in this organizational directory only 

        1. This will only allow people in your active directory to access your static web app. If you want to lock it down more see the next section  

      3. For Redirect URI make sure you put the URL of the Static Web App but with auth added 

        1. Example: ` https://<your_url>/.auth/login/aad/callback` 

    4. After your App Registration is created, open your app registration 

      1. Click Authentication on the left menu 

      2. Under “Implicit grant and hybrid flows” make sure to enable both Access Tokens, and ID Tokens 

      3. Now click Certificates & secrets in the left menu 

      4. Click + New client secret 

        1. Give it a Description and Expiration 

      5. This will give you a Value and Secret ID, make sure you copy the down somewhere as you will not be able to retrieve it again once you click off this page.  

      6. Next click Overview on the left menu 

      7. Copy down Application (client) ID somewhere, you will need it in the next step 

      8. While you are here, copy down Directory (tenant) ID you will need it later. 

  2. Now your App Registration is ready for you Static Web App we need to configure your Static Web App to use said App Registration 

    1. Go back to your Static Web App in the Azure Portal 

    2. Click Configuration in the left menu 

    3. Click Add 

      1. Name this one AZURE_CLIENT_ID 

      2. The value should be the Application (client) ID you copied above 

      3. Click OK 

    4. Click Add again 

      1. Name this one AZURE_CLIENT_SECRET 

      2. The value should be the value of the client secret you created in the App Registration 

      3. Click OK 

    5. Click Save at the top of the page 

  3. Finally, we need to configure Docusaurus to use these values to authenticate to Azure AD

NOTE: Yes, for the keyboard heroes it is technically still configuring the Static Web App but it in the code of your Docusaurus repo so, semantics  

  • Go back to your local code repository 

  • Add a file in the root of your application (in this example it is in the www folder) and name it staticwebapp.config.json 

  • Copy our example below, the only thing you need to change is line 19 (openIdIssuer) you need to your Tenant ID that you copied in Step 1 of this section above 

{
  "routes": [
    { 
      "route": "/*", 
      "allowedRoles": [ "authenticated" ] 
    } 
  ], 
  "responseOverrides": { 
    "401": { 
      "statusCode": 302, 
      "redirect": "/.auth/login/aad" 
      } 
  }, 
  "auth": { 
    "identityProviders": { 
      "azureActiveDirectory": { 
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", 
        "registration": { 
          "openIdIssuer": "https://login.microsoftonline.com/<tenant_id>", 
          "clientIdSettingName": "AZURE_CLIENT_ID", 
          "clientSecretSettingName": "AZURE_CLIENT_SECRET" 
        } 
      } 
    } 
  }, 
  "globalHeaders": { 
    "Cache-Control": "no-cache" 
  } 
}

  • Once you have this file, you can push this up to your branch that your Static Web App is running on. Like I stated in the Updating your site section, once you push the code to the branch that your Static Web App is running on the Azure Pipeline will automatically redeploy your site with changes. Now your Docusaurus site now have Azure AD Auth on it so only people in your organization can access it and they will have to Authenticate to Azure to see it.  

OPTIONAL: Custom Domain Name 

If you don’t want to use the generated name that Azure gives you, you can create a Custom Domain Name for your Docusuarus website. Follow the below steps: 

  1. Open the Azure Portal  

  2. Search for DNS Zones and click DNS Zones under Services 

  3. Click + Create 

  4. Name it whatever you would like for your domain name 

  5. Navigate to your Static Web App in the Azure portal 

  6. Click Custom domains on the left menu 

  7. Click + Add 

    1. Click Custom domain on Azure DNS on the sub menu that pops up 

  8. On this Menu: 

    1. For Domain name: Name it the same as the DNS zone you create 

    2. For DNS Zone: Select your DNS zone you created earlier 

  9. Wait for it to Validate, it will take a while, but it will create a CNAME record, TXT record, and an Alias for your static web app for you in the DNS Zone you created. 

NOTE: If you are using Azure AD Auth, you will need to update the Redirect URI for your App Registration once you have your new custom domain name. 

Andrew Huddleston
Previous

Ephemeral Kubernetes Environments at MBRDNA​
Next

Things We Do to Improve Delivery