Table of Contents

Deployment

Production topology

The production workload runs on one dedicated Linux App Service plan in centralus. The API lives in a different resource group from the website; the storage account lives in a third. The resource declarations are explicit for that reason.

flowchart TB
  GH["GitHub Actions"] -->|"zip deploy"| Plan["ReigniteProduction<br/>B2 Linux App Service plan"]
  Plan --> Web["WebsiteProductionApp<br/>reigniteperformance.com"]
  Plan --> API["APIProductionApp2<br/>api.reigniteperformance.com"]
  Plan --> Docs["DocsProductionApp<br/>docsproductionapp.azurewebsites.net"]
  API --> SQL[("Azure SQL Server")]
  API --> Blob[("Azure Blob Storage<br/>speetlstorage")]
  Web --> API
Resource Name Resource group Notes
App Service plan ReigniteProduction WebsiteProductionApp_group B2, Linux, centralus; shared by the production apps.
Website WebsiteProductionApp WebsiteProductionApp_group Domain reigniteperformance.com.
API APIProductionApp2 WebsiteIntegrationApp_group Domain api.reigniteperformance.com; the app has never lived in the website's group.
Storage speetlstorage APIProductionApp_group northcentralus; trace and dump artifacts.
Docs DocsProductionApp WebsiteProductionApp_group Sibling app on the same plan; default host docsproductionapp.azurewebsites.net; custom domain docs.reigniteperformance.com (Cloudflare CNAME, see the setup steps).

The generated production deployment topology is the canonical diagram. Update the model when a resource or domain changes.

Deploying the docs site

The docs site is a tiny ASP.NET Core host (host/Reignite.Docs.Web) that serves the DocFX output from wwwroot. The build and deploy are in .github/workflows/docs.yml.

One-time Azure setup

  1. Create a Linux App Service app (DocsProductionApp) on ReigniteProduction.

  2. Set the runtime to .NET 10 LTS and the startup command to dotnet Reignite.Docs.Web.dll.

  3. Set WEBSITES_PORT to the port the host listens on (the host honours PORT/WEBSITES_PORT; the default is 8080).

  4. Configure the health check path /healthz.

  5. Configure the DNS records (Cloudflare, reigniteperformance.com zone). Two records are required:

    • CNAME docs → docsproductionapp.azurewebsites.net, proxy DNS only (grey cloud), TTL Auto. This routes traffic.
    • TXT asuid.docs → the app's customDomainVerificationId (az webapp show -g WebsiteProductionApp_group -n DocsProductionApp --query customDomainVerificationId -o tsv). This proves domain ownership. Without it, az webapp config hostname add fails with "A TXT record pointing from asuid.docs.reigniteperformance.com ... was not found."

    Use DNS only while the custom domain and managed certificate are validated. The usual "non-A record" failures come from a CNAME at the zone apex (not used here), a missing asuid TXT record, or Cloudflare's orange-cloud proxy intercepting the validation. An A record is a last resort because the app's inbound IP can change.

  6. After both records resolve, bind the custom domain and certificate:

    az webapp config hostname add \
      -g WebsiteProductionApp_group -n DocsProductionApp \
      --hostname docs.reigniteperformance.com
    
    az webapp config ssl create \
      -g WebsiteProductionApp_group -n DocsProductionApp \
      --hostname docs.reigniteperformance.com
    

    Get the managed-certificate thumbprint with az webapp config ssl list and bind it with az webapp config ssl bind --ssl-type SNI.

  7. Store the deploy credentials:

    • Download the publish profile from Azure Portal → DocsProductionApp → Overview → Get publish profile.
    • Get-Content -Raw "<path>" | gh secret set AZURE_WEBAPP_PUBLISH_PROFILE --repo Reignite-Software-Performance/docs
    • gh variable set AZURE_WEBAPP_NAME --repo Reignite-Software-Performance/docs --body DocsProductionApp
    • Do not use az webapp deployment list-publishing-profiles --xml: this subscription returns userName="REDACTED" / userPWD="REDACTED", which the deploy action rejects.

The workflow

On every push to main (and on a pull request for build validation):

  1. Restore the .NET 10 SDK and the local DocFX tool. The docs host, generator and DocFX all ship .NET 10 builds.
  2. Build the solution and run the generator tests.
  3. Regenerate the docs from architecture/model.yaml.
  4. Build the DocFX site to _site.
  5. Copy _site into host/Reignite.Docs.Web/wwwroot.
  6. Publish the host.
  7. Deploy the publish output to the App Service with azure/webapps-deploy.

A pull request stops after the build; only main deploys.

Manual deploy

./scripts/build.ps1
./scripts/deploy.ps1 -ResourceGroup WebsiteProductionApp_group -AppName DocsProductionApp

deploy.ps1 publishes the host, creates the zip with bsdtar (POSIX entries; do not use Compress-Archive for a Linux App Service), and calls az webapp deploy.

Rollback

App Service keeps the previous deployment. Re-deploy the last known-good artifact, or swap a deployment slot if you add one. Because the docs site is static and model-generated, a rollback is usually a checkout of the previous commit and a re-run of the workflow.

Deploying the other services

  • Website and API: follow each repository's existing pipeline. The production plan and domains are above; the repositories own their build and publish profiles.
  • Bots: each bot is its own App Service on the shared plan. The Teams bot's startup command is dotnet TeamsBot.dll; the diagnostic bot's messaging endpoint is https://<bot-host>/api/teams/bot.
  • Media bridge: Windows-only. Use a Windows App Service plan or a Windows VM; see Media Bridge.

Operational checks

Check Where
The docs host is alive GET /healthz returns 200.
The docs site renders GET / returns the landing page with the DocFX header.
A generated page renders Open /architecture/generated/context.html and confirm the Mermaid diagram draws.
The custom domain resolves curl -I https://docs.reigniteperformance.com/healthz.
The TLS certificate is valid The managed certificate is bound and the DNS CNAME is correct.

Security

  • The publish profile is a deployment credential. Store it as a GitHub secret, not in the repo.
  • Do not put connection strings, bot secrets or storage keys in appsettings.json in the repo.
  • The docs site is public and static. Do not add an authenticated area to it without designing the auth boundary; use the main website for account-scoped pages.