Skip to content

Developer Quickstart Azure

Jump to bottom
Holger Imbery edited this page Mar 19, 2026 · 7 revisions

Developer — Azure Quickstart

Deploy mate to Microsoft Azure with automated infrastructure provisioning, secrets management, and post-deployment configuration.

For Users: See User-Getting-Started.md for end-user deployment options.

Overview

The Azure quickstart is repository-coupled and uses canonical scripts in infra/azure/scripts.

The release artifact mate-quickstart-azure-<version>.zip is docs-only and points to repository paths.

Prerequisites

  • Azure subscription with Owner or Contributor role
  • Azure CLI 2.50+ — Install
  • PowerShell 7+ — Install
  • Bicep CLI — included with Azure CLI (validated by check-prerequisites.ps1)
  • Authenticated Azure session — Run az login before deployment

Quick Deployment (5 minutes)

1. Clone the Repository

git clone https://github.com/holgerimbery/mate.git
cd mate

2. Validate Prerequisites

pwsh ./infra/azure/scripts/check-prerequisites.ps1

Checks for Azure CLI, PowerShell, and Bicep; guides installation if missing.

3. Configure Environment

pwsh ./infra/azure/scripts/setup-env.ps1

Interactive wizard collects:

  • Tenant ID (from az account show --query tenantId)
  • Subscription ID
  • Azure location (default: westeurope)
  • Environment name (default: mate-dev)
  • Entra ID Client ID for OIDC authentication
  • Optional: App Insights sampling rate, scaling parameters

Creates .env file with all settings — never commit this file.

4. Preview Deployment

pwsh ./infra/azure/scripts/deploy-whatif.ps1

Dry-run showing all resources that will be created — recommended before deploy.

5. Deploy Infrastructure

pwsh ./infra/azure/scripts/deploy.ps1

Deploys Bicep template, provisions resources, waits for PostgreSQL, auto-creates firewall rules, injects secrets:

  • postgres-conn — PostgreSQL connection string
  • blob-conn — Azure Blob Storage connection string

Binds secrets to Container App environment variables:

  • ConnectionStrings__Default → secretref:postgres-conn
  • AzureInfrastructure__BlobConnectionString → secretref:blob-conn

6. Configure Secrets & RBAC

pwsh ./infra/azure/scripts/setup-keyvault-secrets.ps1

Post-deployment: Stores Entra ID client secret in Key Vault, configures RBAC role assignments.

What Gets Deployed

Component Type Version Notes
WebUI Azure Container App Latest Public HTTPS ingress, managed identity
Worker Azure Container App Latest Internal, event-driven (Service Bus queue)
PostgreSQL Flexible Server v17 Public network + auto-firewall rules
Blob Storage Storage Account Standard LRS Document storage (mateXXXXst account)
Key Vault Secure storage N/A Secrets + RBAC
Application Insights Monitoring N/A Logs, traces, metrics
Service Bus Queue Standard Worker queue trigger

Deployment Profiles

Choose a profile matching your use case. Profile determines CPU, memory, instance count, and monthly cost.

Profile Instance Type Instances CPU per Instance Memory Cost/Month
xs Tiny (dev/test) 1 0.5 1 GB ~$15
s Small (dev) 1 0.75 1.5 GB ~$30
m Medium (staging) 2 1.0 2 GB ~$80
l Large (prod) 3 2.0 4 GB ~$200+

Set via .env: AZURE_PROFILE=s

Accessing Your Deployment

After deploy.ps1 completes, the WebUI URL is printed to console:

https://mate-dev-webui.{uniqueId}.{region}.azurecontainerapps.io

First Login

  1. Navigate to the URL
  2. Click Login and authenticate with your Entra ID account (if configured) or generic login
  3. Create your first test suite
  4. Run a test against any connected agent

Scripts Reference

Script Purpose Interactive
infra/azure/scripts/check-prerequisites.ps1 Validates Azure CLI, PowerShell, Bicep No
infra/azure/scripts/setup-env.ps1 Collect Azure + app config Yes
infra/azure/scripts/deploy-whatif.ps1 Dry-run preview No
infra/azure/scripts/deploy.ps1 Deploy infrastructure + secrets No
infra/azure/scripts/setup-keyvault-secrets.ps1 Post-deploy RBAC + secrets No
infra/azure/scripts/update-container-images.ps1 Update container images to new version No
infra/azure/scripts/cleanup-rg.ps1 Delete all resources (keeps RG) No

Updating Container Images (New Release)

After a new version is released, quickly update the running container images without redeploying the entire infrastructure:

pwsh ./infra/azure/scripts/update-container-images.ps1

Or specify a specific version tag:

pwsh ./infra/azure/scripts/update-container-images.ps1 -ImageTag '<version>'  # e.g. '0.9.0-rc.1'

What happens:

  • Updates .env with AZURE_IMAGE_TAG=<version> (maintains Bicep state)
  • Runs focused Bicep deployment for image updates only
  • Creates new Container App revisions for WebUI and Worker
  • Traffic automatically switches to new revisions (zero-downtime)
  • Old revisions deactivated but retained for rollback
  • Waits for deployment completion before returning (typically 5–10 minutes)
  • Runtime secret wiring is managed by Bicep + Key Vault references

💡 Monitoring: Check deployment status with:

az deployment group show --name main --resource-group <your-rg> --query "{State:properties.provisioningState, Duration:properties.duration}" -o table

Preview changes first (recommended):

pwsh ./infra/azure/scripts/update-container-images.ps1 -ImageTag '<version>' -WhatIf

Update to latest (without specifying tag):

pwsh ./infra/azure/scripts/update-container-images.ps1

Quick reference:

Task Command
Update to specific version ./infra/azure/scripts/update-container-images.ps1 -ImageTag '<version>'
Update to latest ./infra/azure/scripts/update-container-images.ps1
Preview changes ./infra/azure/scripts/update-container-images.ps1 -ImageTag '<version>' -WhatIf
Skip confirmation ./infra/azure/scripts/update-container-images.ps1 -Force

When to use:

  • ✅ New release available
  • ✅ Hotfix deployment
  • ✅ Rolling back to previous version
  • ❌ NOT for scaling, location changes, or infrastructure modifications (use deploy.ps1 instead)

Custom domain after image updates:

  • If your WebUI uses a custom hostname and that hostname is not represented in IaC, rebind it after update-container-images.ps1.
pwsh ./infra/azure/scripts/bind-custom-domain.ps1 -DomainName '<your-custom-domain>'

Example values: app.example.com, portal.contoso.com

Bicep State Tracking: The script maintains full Bicep state by updating .env. Future deploy.ps1 runs will use the updated image tag.

"PostgreSQL connection timeout"

  • Cause: Firewall rule not created or PostgreSQL still initializing
  • Fix: Wait 2–3 minutes; deploy.ps1 auto-creates firewall rule AllowAzureServices (0.0.0.0-0.0.0.0)
  • Check logs: az containerapp logs show --name mate-dev-webui --type console --tail 50

"Access denied to Key Vault"

  • Cause: RBAC role not assigned to Container App managed identity
  • Fix: Run setup-keyvault-secrets.ps1 to assign Key Vault Secrets User role

"Container App revision unhealthy"

  • Cause: Startup migration or secret binding failed
  • Fix: Check application logs 
    az containerapp logs show --name mate-dev-webui --type console --tail 100

"Invalid blob connection string"

  • Cause: Secret not injected or malformed
  • Fix: Run deploy.ps1 again — post-deployment block updates secrets automatically

"Deployment times out at PostgreSQL provisioning"

  • Cause: PostgreSQL Flexible Server takes 10+ minutes to provision
  • Fix: Re-run deploy-whatif.ps1 to show status; wait 5 more minutes and re-run deploy.ps1

Cost Estimation

Typical monthly costs by profile (US East region, 730 hours/month):

Profile Container Apps PostgreSQL Storage Insights Total/Month
xs ~$12 ~$30 ~$2 ~$5 ~$49
s ~$18 ~$30 ~$2 ~$5 ~$55
m ~$36 ~$30 ~$2 ~$5 ~$73
l ~$72 ~$30 ~$2 ~$5 ~$109

Always run deploy-whatif.ps1 first to estimate costs for your region and settings.

Cleanup

Delete all resources while keeping the Resource Group (for re-deployment):

pwsh ./infra/azure/scripts/cleanup-rg.ps1

Delete the entire Resource Group (all resources permanently removed):

az group delete --name rg-mate-dev

Environment Variables (.env file)

The .env file contains deployment configuration. Do not commit to git.

Variable Example Required Notes
AZURE_TENANT_ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Yes From az account show --query tenantId
AZURE_SUBSCRIPTION_ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Yes From az account show --query id
AZURE_LOCATION westeurope Yes Azure region
AZURE_ENVIRONMENT_NAME mate-dev Yes Resource name prefix
AZURE_PROFILE s Yes Deployment profile (xs/s/m/l)
AZURE_IMAGE_TAG 0.9.0-rc.1 Yes mate image version
AZURE_AAD_CLIENT_ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx No For Entra ID OIDC (optional)
AZURE_POSTGRES_ADMIN_LOGIN pgadmin Yes DB admin username
AZURE_APPINSIGHTS_SAMPLING_RATE 0.1 No Telemetry sampling (0-1)

Related Documentation

Support

For issues or questions:

  1. Check Troubleshooting section above
  2. Review Application Insights logs in Azure Portal
  3. Check mate-dev-webui Container App revision logs: az containerapp logs show ...
  4. Open an issue on GitHub

mate

Home

User Documentation

Developer Documentation

Clone this wiki locally