# 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](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](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
- **PowerShell 7+** — [Install](https://github.com/PowerShell/PowerShell/releases)
- **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

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

### 2. Validate Prerequisites

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

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

### 3. Configure Environment

```powershell
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

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

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

### 5. Deploy Infrastructure

```powershell
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

```powershell
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:

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

Or specify a specific version tag:

```powershell
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:
> ```powershell
> az deployment group show --name main --resource-group <your-rg> --query "{State:properties.provisioningState, Duration:properties.duration}" -o table
> ```

**Preview changes first (recommended):**

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

**Update to `latest` (without specifying tag):**

```powershell
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`.

```powershell
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
  ```powershell
  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):

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

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

```powershell
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

- **Architecture:** [Developer-Architecture.md](Developer-Architecture.md) — system design and infrastructure overview
- **Local Development:** [Developer-Getting-Started.md](Developer-Getting-Started.md) — Docker Compose for local setup
- **Infrastructure Code:** [`infra/azure/README.md`](https://github.com/holgerimbery/mate/blob/main/infra/azure/README.md) — Bicep templates and modules
- **Deployment Reference:** [`quickstart-azure/DEPLOYMENT.md`](https://github.com/holgerimbery/mate/blob/main/quickstart-azure/DEPLOYMENT.md) — technical workflow detail
- **Module Development:** [Developer-Module-Development.md](Developer-Module-Development.md) — extending mate with custom modules

---

## Support

For issues or questions:
1. Check [Troubleshooting](#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](https://github.com/holgerimbery/mate/issues)