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
Create a Linux App Service app (
DocsProductionApp) onReigniteProduction.Set the runtime to .NET 10 LTS and the startup command to
dotnet Reignite.Docs.Web.dll.Set
WEBSITES_PORTto the port the host listens on (the host honoursPORT/WEBSITES_PORT; the default is8080).Configure the health check path
/healthz.Configure the DNS records (Cloudflare,
reigniteperformance.comzone). Two records are required:CNAMEdocs→docsproductionapp.azurewebsites.net, proxy DNS only (grey cloud), TTL Auto. This routes traffic.TXTasuid.docs→ the app'scustomDomainVerificationId(az webapp show -g WebsiteProductionApp_group -n DocsProductionApp --query customDomainVerificationId -o tsv). This proves domain ownership. Without it,az webapp config hostname addfails 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
asuidTXT record, or Cloudflare's orange-cloud proxy intercepting the validation. AnArecord is a last resort because the app's inbound IP can change.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.comGet the managed-certificate thumbprint with
az webapp config ssl listand bind it withaz webapp config ssl bind --ssl-type SNI.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/docsgh variable set AZURE_WEBAPP_NAME --repo Reignite-Software-Performance/docs --body DocsProductionApp- Do not use
az webapp deployment list-publishing-profiles --xml: this subscription returnsuserName="REDACTED"/userPWD="REDACTED", which the deploy action rejects.
The workflow
On every push to main (and on a pull request for build validation):
- Restore the .NET 10 SDK and the local DocFX tool. The docs host, generator and DocFX all ship .NET 10 builds.
- Build the solution and run the generator tests.
- Regenerate the docs from
architecture/model.yaml. - Build the DocFX site to
_site. - Copy
_siteintohost/Reignite.Docs.Web/wwwroot. - Publish the host.
- 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 ishttps://<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.jsonin 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.