Hosting on Azure

This site is a stock Docusaurus 3 scaffold that has been wired up to Azure for a cost / feasibility evaluation.

Moving parts

Layer	Choice	Why
Source control	Azure Repos (HelmITTech/docusaurus)	Requested: new Azure DevOps project
CI/CD	Azure Pipelines (azure-pipelines.yml)	Builds site/ and publishes site/build with the SWA CLI — needs a pipeline agent, see below
Hosting	Azure Static Web Apps, Free tier, westus2	$0/month baseline, global CDN, TLS, built-in Entra ID auth
Infrastructure as code	Bicep (infra/)	Declarative, native to Azure
Change control	Azure Deployment Stack (stack-docusaurus) with denyWriteAndDelete	Blocks portal "click-ops": resources can only change via the stack

Sign in

Use Sign in in the navbar (or visit /account). Static Web Apps redirects to Microsoft Entra ID and back; the /account page then reads /.auth/me and shows the signed-in principal. The site itself is public — sign-in is optional.

:::caution Who can sign in The Free tier's pre-configured Entra ID provider accepts any Microsoft account — work/school accounts from any tenant and personal accounts. authenticated therefore means "has a Microsoft login", not "belongs to HelmIT Tech". Restricting to one tenant requires custom authentication on the Standard plan; on Free you can instead invite specific users to a custom role (≤ 25 invitations) and gate on that role. :::

To require sign-in for the whole site, replace site/static/staticwebapp.config.json with (this keeps the existing 404 override, headers and GitHub-provider block):

{
  "$schema": "https://json.schemastore.org/staticwebapp.config.json",
  "routes": [
    { "route": "/.auth/login/github", "statusCode": 404 },
    { "route": "/*", "allowedRoles": ["authenticated"] }
  ],
  "responseOverrides": {
    "401": { "redirect": "/.auth/login/aad?post_login_redirect_uri=.referrer", "statusCode": 302 },
    "404": { "rewrite": "/404.html", "statusCode": 404 }
  },
  "globalHeaders": {
    "X-Content-Type-Options": "nosniff",
    "Referrer-Policy": "strict-origin-when-cross-origin",
    "X-Frame-Options": "SAMEORIGIN",
    "Content-Security-Policy": "frame-ancestors 'self'"
  }
}

Use "allowedRoles": ["reader"] (or any custom role you invite users into) instead of authenticated to limit access to named people on the Free tier.

Changing things

• Content: edit files under site/, push to main. The pipeline rebuilds and redeploys once the Azure DevOps org has a pipeline agent — at the time of writing the org has no Microsoft-hosted parallelism (free grant not yet applied: set up billing or request it via the parallelism request form, or register a self-hosted agent). Until then, publish from a workstation:

  cd site; npm ci; npm run build
  $env:SWA_CLI_DEPLOYMENT_TOKEN = az staticwebapp secrets list -n swa-docusaurus -g rg-docusaurus --query properties.apiKey -o tsv
  npx @azure/static-web-apps-cli@2.0.10 deploy ./build --env production --no-use-keychain
  $env:SWA_CLI_DEPLOYMENT_TOKEN = $null

• Infrastructure: edit infra/*.bicep, then run infra/deploy.ps1 as a subscription Owner. Direct edits in the Azure portal are denied by the stack.