Azure and Bicep

The kit describes the Azure side of a site as Bicep files in infra/. You edit one small parameter file, deploy with the Azure CLI, and the resources exist. The pipeline then deploys the site into them. This page covers the files, the resources, the parameters, the secrets and the commands, for all three hosting models.

In Claude Code the setup-hosting skill does the same job and stops for your approval before it changes the hosting model. See Skills.

Write the files

npx mdlake hosting init --ci github,azure-devops --name acme-site

The model it writes for is the one the kit works out for the site: the record in .mdlake/hosting.json, or else what the code shows (a site with on-demand routes is server; a site with none is static). Settings and secrets it lists in the parameter files come from the forms in src/forms. See Choose a hosting model.

Files by model

Every generated file starts with a marker line such as:

// mdlake-hosting: tier=split runtime=dotnet (generated by `npx mdlake hosting init`; keep your edits with `npx mdlake adopt <file>`)

The marker belongs to the generated ownership zone: hosting init may rewrite these files, so do not edit them. The two parameter files are the exception. They are created once and are yours, and the command never overwrites them.

Regenerating and your own changes

Run hosting init again after you change the hosting model, the runtime or the CI systems. The command:

• rewrites every generated file that you have not edited, and says Unchanged for those that need no change;
• refuses a generated file that you edited and exits with code 3, naming it;
• never touches your parameter files. If they exist it prints ... exists already; left as it is (check that it fits the <model> tier). After a model change, compare them with the new main.bicep by hand. A split site needs staticWebAppLocation and apiSku; a static site does not take settings;
• leaves the modules of the old model behind when you switch, and tells you to delete them (infra/modules/appService.bicep is not used by a split site).

If you need a change in a generated file, make it and run npx mdlake adopt infra/main.bicep. The file then counts as yours and hosting init stops rewriting it. The cost is that you also stop getting improvements to that file. --overwrite throws your change away instead.

The resources

Static

One resource: an Azure Static Web App from modules/staticWebApp.bicep.

Outputs: defaultHostName and name.

Server

main.bicep combines modules/appService.bicep and, by default, modules/keyVault.bicep.

The Web App always has these settings: HOST=0.0.0.0, NODE_ENV=production, SCM_DO_BUILD_DURING_DEPLOYMENT=false. Your settings and secretNames are added to them.

Outputs: defaultHostName, name and customDomainVerificationId (the value of the asuid TXT record).

Split

main.bicep combines four modules.

Extra parameters on the split model: staticWebAppLocation (default westeurope), apiSku (default B1) and customDomainType (default auto). The API’s region is location, which defaults to the resource group’s.

Outputs: siteHostName, apiHostName, staticWebAppName and apiName.

The parameter files

Edit infra/parameters/production.bicepparam before you deploy. A file for a split .NET site looks like this:

using '../main.bicep'

param name = 'acme-site-prod'
param staticWebAppLocation = 'westeurope'
param apiSku = 'B1'
param useKeyVault = true
param settings = {
  MAIL_PROVIDER: 'resend'
  MAIL_FROM: ''
  CONTACT_FORM_TO: ''
}
param secretNames = [
  'RESEND_API_KEY'
]
param customDomain = ''
param tags = {
  environment: 'production'
}

The static model’s file has only name, sku, customDomain, customDomainType and tags, since it has no run-time settings.

Deploy the infrastructure

You do this once per environment, and again when you change a parameter file.

1. Sign in and choose the subscription.

   Bash

   az login
   az account set --subscription "<subscription id or name>"

2. Create the resource group. The server and split models suggest swedencentral; a static site suggests westeurope.

   Bash

   az group create --name rg-acme-site --location swedencentral

3. Deploy. Pass secrets on the command line, never in a file. In bash:

   Bash

   az deployment group create \
     --resource-group rg-acme-site \
     --parameters infra/parameters/production.bicepparam \
     --parameters secrets='{"RESEND_API_KEY":"re_xxxxxxxx"}'

   In PowerShell:

   PowerShell

   az deployment group create `
     --resource-group rg-acme-site `
     --parameters infra/parameters/production.bicepparam `
     --parameters secrets='{\"RESEND_API_KEY\":\"re_xxxxxxxx\"}'

   A static site has no secrets: leave out the last line. The command prints the outputs when it finishes.

4. Check the outputs. Open the host name from defaultHostName or siteHostName. A new Static Web App shows Azure’s placeholder page until the pipeline has deployed.

The deployment is incremental: running it again changes only what differs.

Key Vault and secrets

With useKeyVault = true (the default) the app settings do not hold secret values. Each secret in secretNames becomes a Key Vault reference:

@Microsoft.KeyVault(VaultName=acme-site-prod-kv;SecretName=RESEND_API_KEY)

The Web App’s managed identity resolves the reference when the app starts. The vault holds the real value.

There are two ways to put a value in the vault:

• Pass it in secrets when you deploy, as shown above. The Bicep writes every secret that is both in secretNames and in secrets.

• Set it later with the Azure CLI:

  Bash

  az keyvault secret set --vault-name acme-site-prod-kv --name RESEND_API_KEY --value "re_xxxxxxxx"

Azure re-reads Key Vault references on its own schedule, so a new value can take a while to reach the app. Restart the Web App after you change a secret so that it picks up the new value straight away.

Your own account needs permission to write secrets. The vault uses role-based access, so give yourself Key Vault Secrets Officer on the vault if az keyvault secret set is refused.

With useKeyVault = false the Bicep puts the secret values into the app settings directly, taken from secrets. This is simpler and less safe: anyone who can read the Web App’s configuration can read them. Use it only for a short experiment.

Which secrets exist

The last two are not Key Vault secrets. They belong to the pipeline. See GitHub Actions and Azure DevOps.

Get the deployment token

The pipeline sends the pages to Static Web Apps with a deployment token. Read it once and store it as a pipeline secret.

az staticwebapp secrets list --name acme-site-prod --query properties.apiKey -o tsv

The name is the name parameter (the Static Web App itself, not the API).

Manual steps that remain

hosting init prints the steps that are left for you, adapted to your model and CI systems. Read them once after you run the command. They are the ones on this page and in GitHub Actions and Azure DevOps:

1. The resource group.
2. The parameter file and the deployment.
3. The Key Vault secrets.
4. The Static Web Apps deployment token (static and split models).
5. The sign-in of the pipeline to Azure (server and split models).
6. The custom domain.

Cost

Rough sizes, to help you choose; check the Azure price calculator for current prices.

• Static: the Free plan costs nothing. Standard costs a monthly fee per app.
• Server: one Basic B1 App Service plan.
• Split: Static Web Apps Standard plus one Basic B1 plan, plus the Key Vault (a small per-operation cost).

A site that does not need server code should stay static.

Edit the Bicep

Prefer parameters over editing modules. If you need something the modules do not offer (a database, a storage account, a second Web App), add your own Bicep file in infra/ and reference it from your own copy of main.bicep:

1. Run npx mdlake adopt infra/main.bicep.
2. Add your module and parameters.
3. From now on you maintain main.bicep. The generated modules still update with hosting init.

What’s next

• GitHub Actions or Azure DevOps to connect the pipeline.
• The lake in CI, and caches.
• Troubleshooting.