You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/DEPLOYMENT_GUIDE.md
+10-7Lines changed: 10 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,7 +46,9 @@ The template includes subscription-scope toggles to reduce Microsoft Defender fo
46
46
These set Microsoft.Security/pricings resources to Free or Standard as appropriate. CSPM (Arm) remains Free to preserve secure score and policy evaluations.
47
47
48
48
49
-
If you want the fastest, repeatable route to a working Management Portal backed by live Cosmos data, follow these steps. This path deploys the smoke sample, seeds representative baseline data using the Seeder (AAD RBAC), and verifies Portal ↔ DAB ↔ Cosmos connectivity.
49
+
If you want the fastest, repeatable route to a working Management Portal backed by live Cosmos data, follow these steps. This path deploys the smoke sample, seeds representative baseline data using the Seeder (AAD RBAC), and verifies Portal ↔ GraphQL backend ↔ Cosmos connectivity. The GraphQL backend is implemented using Hot Chocolate.
50
+
51
+
Note: Hot Chocolate is the actively supported GraphQL backend used throughout this repository. User-facing documentation has been rebaselined to focus on Hot Chocolate so new developers see the current, supported stack.
50
52
51
53
1. Create a resource group and deploy the smoke sample (lab-friendly parameters):
52
54
@@ -75,7 +77,7 @@ dotnet run
75
77
76
78
4. Verify the deployment and seeded data.
77
79
78
-
- Retrieve deployment outputs to get the Portal and DAB endpoints:
80
+
- Retrieve deployment outputs to get the Portal and GraphQL backend endpoints (note: some deployment outputs retain legacy names like `dab-graphql-url`):
79
81
80
82
```powershell
81
83
pwsh -Command "az deployment group show --resource-group rg-stamps-smoke --name $(az deployment group list --resource-group rg-stamps-smoke --query '[0].name' -o tsv) --query properties.outputs"
@@ -84,7 +86,7 @@ pwsh -Command "az deployment group show --resource-group rg-stamps-smoke --name
84
86
- Open the Management Portal URL in a browser and confirm seeded tenants/cells are visible. Optionally test the GraphQL endpoint:
85
87
86
88
```powershell
87
-
pwsh -Command "curl -s -X POST 'https://<DAB_GRAPHQL_URL>/graphql' -H 'Content-Type: application/json' -d '{\"query\":\"{ tenants { id name } }\"}'"
89
+
pwsh -Command "curl -s -X POST 'https://<GRAPHQL_URL>/graphql' -H 'Content-Type: application/json' -d '{\"query\":\"{ tenants { id name } }\"}'"
88
90
```
89
91
90
92
Notes:
@@ -153,7 +155,8 @@ Steps:
153
155
1) Start local data stack (Cosmos Emulator, Portal, GraphQL API) [optional]
154
156
155
157
- PowerShell (Windows):
156
-
- pwsh -File ./scripts/run-local.ps1
158
+
- Note: `scripts/run-local.ps1` has been removed. To run locally, start the portal directly:
159
+
`dotnet run --project ./management-portal/src/Portal/Portal.csproj`
- Cosmos TLS trust: the run-local.ps1 script imports the emulator certificate into CurrentUser/Root; if calls fail, open <https://localhost:8085/_explorer/emulator.pem>once in a browser to trust the cert.
187
+
-- Cosmos TLS trust: the legacy `run-local.ps1` previously imported the emulator certificate into CurrentUser/Root. If SSL calls fail, open <https://localhost:8085/_explorer/emulator.pem> in a browser and import/accept the cert manually, or run the sample import steps in `docs/DEVELOPER_QUICKSTART.md`.
185
188
- Functions task in VS Code: use the default “build (functions)” task, then start with func start from the AzureArchitecture folder.
186
189
187
190
## 📖 Key Concepts Before You Start
@@ -1186,8 +1189,8 @@ Use this quick checklist before promoting a test deployment to production. Cross
1186
1189
- Authentication and authorization
1187
1190
- Enable built‑in auth for Azure Container Apps and Functions; require login for all endpoints.
1188
1191
- Map Entra ID groups to application roles (e.g., platform.admin). Disable anonymous access and lock down CORS.
1189
-
- Propagate platform roles to DAB; ensure non‑admins have read‑only or least‑privilege permissions.
1190
-
- API/DAB hardening
1192
+
- Propagate platform roles to the GraphQL backend (or to legacy DAB deployments); ensure non‑admins have read‑only or least‑privilege permissions.
1193
+
- API hardening for the GraphQL backend
1191
1194
- Disable public schema mutation where not needed; restrict filters/projections; rate‑limit externally exposed routes via APIM/App Gateway.
1192
1195
- Turn off development features in production (verbose errors, GraphQL introspection if policy requires).
Copy file name to clipboardExpand all lines: docs/DEVELOPER_QUICKSTART.md
+12-8Lines changed: 12 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,13 +23,18 @@ cd StampsPattern
23
23
24
24
## 2) Start local data stack (scripted)
25
25
26
-
Recommended: use the helper to start Cosmos Emulator, DAB, and the portal.
26
+
Recommended: use the helper to start Cosmos Emulator and the portal. The portal hosts a Hot Chocolate GraphQL endpoint by default; starting Data API Builder (DAB) is optional and only needed for legacy compatibility testing.
27
+
28
+
Note: Hot Chocolate is the active GraphQL backend. References and legacy names (for example `DAB_GRAPHQL_URL` or `ca-stamps-dab`) are being rebaselined across the documentation; before renaming or removing production secrets or resource identifiers, follow a staged verification and migration procedure to avoid service disruptions.
27
29
28
30
```powershell
29
-
pwsh -File ./scripts/run-local.ps1
31
+
Note: `scripts/run-local.ps1` has been removed. Start the portal locally with:
32
+
`dotnet run --project ./management-portal/src/Portal/Portal.csproj`
33
+
Seed sample data with:
34
+
`dotnet run --project ./management-portal/Seeder/Seeder.csproj`
30
35
```
31
36
32
-
Default ports: Cosmos 8085, DAB 8082, Portal 8081. The script also helps trust the emulator cert.
37
+
Default ports: Cosmos 8085, Portal 8081. (Legacy DAB port: 8082) The script also helps trust the emulator cert.
33
38
34
39
Manual alternative (optional):
35
40
@@ -64,7 +69,7 @@ At minimum set Cosmos and identity settings:
64
69
// "B2C_POLICY": "your-policy"
65
70
}
66
71
}
67
-
```jsonc
72
+
```
68
73
69
74
Tip: The emulator account key shown above is the standard sample key; adjust if your emulator differs.
70
75
@@ -79,11 +84,10 @@ If `func` isn’t found, ensure your npm global bin is on PATH.
79
84
80
85
## 5) Build and run the Functions app
81
86
82
-
```powershell
83
87
```powershell
84
88
cd ./AzureArchitecture
85
-
dotnet build
86
-
func start
89
+
dotnet build
90
+
func start
87
91
```
88
92
89
93
If the default port is busy, try `func start --port 7072`.
@@ -110,7 +114,7 @@ func start --verbose
110
114
111
115
# Check port conflicts, try another port
112
116
func start --port 7072
113
-
```bash
117
+
```
114
118
115
119
See also: Known Issues → Functions host exits on startup or endpoints not reachable locally.
Copy file name to clipboardExpand all lines: docs/GLOSSARY.md
+5-4Lines changed: 5 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -133,12 +133,13 @@ Secure store for secrets, keys, and certificates.
133
133
-**Integration**: Managed identity; reference secrets in app settings and Bicep
134
134
-**Docs**: <ahref="https://learn.microsoft.com/azure/key-vault/general/overview"target="_blank"rel="noopener"title="Opens in a new tab">Key Vault overview</a> <sup>↗</sup>
135
135
136
-
### **Data API Builder (DAB)**
136
+
### **GraphQL backend (Hot Chocolate) — Data API Builder (DAB) (legacy)**
137
137
138
-
Runtime that exposes databases as REST/GraphQL with role-based access.
138
+
The Management Portal exposes a GraphQL API for control-plane data. The primary, actively maintained implementation uses Hot Chocolate (a .NET GraphQL server). Older references to Data API Builder (DAB) still exist in archive material and some operational scripts.
139
139
140
-
-**Use Cases**: Data plane for the Management Portal with Easy Auth headers
141
-
-**Docs**: <ahref="https://learn.microsoft.com/azure/data-api-builder/overview"target="_blank"rel="noopener"title="Opens in a new tab">Data API Builder overview</a> <sup>↗</sup>
140
+
-**Use Cases**: Exposes control-plane data (tenants, cells, operations) via GraphQL with role-based access patterns
141
+
-**Notes**: Hot Chocolate is the recommended GraphQL backend. References to Data API Builder (DAB) in the repo are legacy; we are rebaselining docs and examples to prefer Hot Chocolate. Some runtime names and secrets still include "DAB"; follow a staged verification and migration plan before renaming live secrets or resources.
142
+
-**Docs**: Hot Chocolate: <https://chillicream.com/docs/hotchocolate> & DAB: <https://learn.microsoft.com/azure/data-api-builder/overview> (legacy)
Copy file name to clipboardExpand all lines: docs/KNOWN_ISSUES.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,8 +22,8 @@ Practical fixes and workarounds for common issues across development, deployment
22
22
>
23
23
> 1. Bicep/template errors — run `bicep build <file>.bicep` and `az deployment group what-if` → see [Deployment Issues](#-deployment-issues).
24
24
> 2. Name conflicts — change `resourceToken` or use uniqueString(resourceGroup().id) → [Deployment Issues](#-deployment-issues).
25
-
> 3.DAB crashing / port mismatch — confirm `ASPNETCORE_URLS` vs Container App `targetPort` → [Deployment Issues](#-deployment-issues).
26
-
> 4. Portal timeouts to DAB — check `DAB_GRAPHQL_URL` secret and Container App logs → [Troubleshooting Playbooks](#portal-→-dab-connectivity-decision-tree).
25
+
> 3.GraphQL backend crashing / port mismatch — confirm `ASPNETCORE_URLS` vs Container App `targetPort` → [Deployment Issues](#-deployment-issues). # note: env var names like `ASPNETCORE_URLS` are still used by the image
26
+
> 4. Portal timeouts to the GraphQL backend — check `DAB_GRAPHQL_URL` secret and Container App logs → [Troubleshooting Playbooks](#portal-→-dab-connectivity-decision-tree).
27
27
> 5. Seeder 401/403 — grant Cosmos DB Data Contributor to the identity and use DefaultAzureCredential locally → [Development Issues](#-development-issues).
28
28
> 6. Key Vault access denied — grant `get`/`list` or Key Vault Secrets User RBAC to the principal → [Security Issues](#-security-issues).
29
29
> 7. Cosmos 429 throttling — implement retries/backoff and scale RU/s or enable autoscale → [Performance Issues](#-performance-issues).
@@ -150,7 +150,7 @@ flowchart LR
150
150
151
151
## 🔁 Troubleshooting Playbooks (decision trees)
152
152
153
-
Below are three focused decision trees that operators reach for frequently: Portal → DAB connectivity, DAB container startup, and AAD/authentication issues. Use these as quick visual playbooks during incidents.
153
+
Below are three focused decision trees that operators reach for frequently: Portal → GraphQL backend connectivity, GraphQL container startup, and AAD/authentication issues. Use these as quick visual playbooks during incidents. Note: runtime names and secrets like `DAB_GRAPHQL_URL` may still be used for compatibility.
154
154
155
155
### 1) Portal → DAB connectivity decision tree
156
156
@@ -166,7 +166,7 @@ flowchart TD
166
166
P2 --> P4{Is DAB endpoint configured (DAB_GRAPHQL_URL)?}
Copy file name to clipboardExpand all lines: docs/LANDING_ZONES_GUIDE.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -35,7 +35,7 @@ Practical guide to placing Azure Stamps Pattern components within Azure Landing
35
35
36
36
- Platform landing zones host shared enterprise services: Identity (process), Management, Connectivity, and Shared Services (global edge, shared gateways). Do not put all infra into the Management subscription.
37
37
- Application (workload) landing zones host your CELLs (shared or dedicated) per region. Use one subscription per CELL for isolation, quotas, and billing clarity.
38
-
- Control Plane (management portal, DAB GraphQL, control metadata): either a) Platform Shared-Services subscription if used by many apps/org-wide, or b) a dedicated “ControlPlane” workload subscription under Landing Zones for autonomy and SDLC separation.
38
+
- Control Plane (management portal, GraphQL backend, control metadata): either a) Platform Shared-Services subscription if used by many apps/org-wide, or b) a dedicated “ControlPlane” workload subscription under Landing Zones for autonomy and SDLC separation.
Copy file name to clipboardExpand all lines: docs/LIVE_DATA_PATH.md
+16-16Lines changed: 16 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,61 +1,61 @@
1
1
---
2
-
# Live Data Path — Portal → DAB → Cosmos (quick guide)
2
+
# Live Data Path — Portal → GraphQL → Cosmos (quick guide)
3
3
4
4
Purpose
5
5
6
-
- One-page smoke path and quick checks to validate the Management Portal consumes live data from Data API Builder (DAB) backed by Cosmos DB.
6
+
- One-page smoke path and quick checks to validate the Management Portal consumes live data from the GraphQL backend (Hot Chocolate) backed by Cosmos DB.
7
7
8
8
Who this is for
9
9
10
10
- Developers, platform engineers, and operators who need a fast, repeatable set of checks to confirm the live-data flow is healthy.
11
11
12
12
Overview
13
13
14
-
- Path: Management Portal (UI) → DAB (GraphQL) → Cosmos DB (control-plane containers: tenants, cells, operations)
15
-
- Secrets and identity: Portal authenticates users via AAD; Portal calls DAB over internal network; DAB uses MI or connection string to read Cosmos.
- Secrets and identity: Portal authenticates users via AAD; Portal calls the GraphQL backend over the internal network; the GraphQL backend uses a managed identity or connection string to read Cosmos.
16
16
17
17
Quick diagram
18
18
19
19
```mermaid
20
20
flowchart LR
21
21
Portal[Management Portal]
22
-
DAB[Data API Builder (Container App)]
22
+
GraphQL[GraphQL (Hot Chocolate) (Container App)]
23
23
Cosmos[Cosmos DB - stamps-control-plane]
24
24
25
-
Portal -->|HTTP GraphQL POST| DAB
26
-
DAB -->|Cosmos SDK / REST| Cosmos
25
+
Portal -->|HTTP GraphQL POST| GraphQL
26
+
GraphQL -->|Cosmos SDK / REST| Cosmos
27
27
```mermaid
28
28
29
29
Essential variables
30
30
31
-
- DAB GraphQL URL (secret): DAB_GRAPHQL_URL — e.g. https://<internal-fqdn>/graphql
32
-
- Portal secret/setting: ensure Portal reads `DAB_GRAPHQL_URL` from container-app secrets or Key Vault
31
+
- GraphQL URL (secret): DAB_GRAPHQL_URL — e.g. https://<internal-fqdn>/graphql (kept for backwards compatibility)
32
+
- Portal secret/setting: ensure Portal reads `DAB_GRAPHQL_URL` from container-app secrets or Key Vault. Note: the portal uses Hot Chocolate as the GraphQL implementation; `DAB_*` runtime names are retained for compatibility and should not be renamed without an infra/secret migration plan.
33
+
34
+
Note: The GraphQL backend used in this project is Hot Chocolate. `DAB_*` names and references in this document are legacy compatibility artifacts. Runtime identifiers such as `DAB_GRAPHQL_URL` and `ca-stamps-dab` are intentionally preserved — do not rename them without a coordinated infra/secrets migration.
1) Validate GraphQL backend is healthy (Container Apps)
38
40
39
-
# ```powershell
40
41
# List revisions and health
41
-
az containerapp revision list -g rg-stamps-mgmt -n ca-stamps-dab -o table
42
+
az containerapp revision list -g rg-stamps-mgmt -n ca-stamps-dab -o table# resource name retained for compatibility
42
43
43
44
# Show ingress configuration (confirm targetPort matches container)
44
45
az containerapp show -g rg-stamps-mgmt -n ca-stamps-dab --query properties.configuration.ingress
45
-
```bash
46
46
47
-
2) Tail DAB logs (look for startup errors and GraphQL listening)
47
+
2) Tail GraphQL backend logs (look for startup errors and GraphQL listening). The Container App resource may still be named `ca-stamps-dab` for backward compatibility.
48
48
49
49
```powershell
50
50
az containerapp logs show -g rg-stamps-mgmt -n ca-stamps-dab --container dab --tail 200
51
51
```
52
52
53
53
1) Quick GraphQL introspection / simple query
54
54
55
-
Using PowerShell (Invoke-RestMethod) — replace `$DAB` with the DAB GraphQL URL (from secret/outputs):
55
+
Using PowerShell (Invoke-RestMethod) — replace `$DAB` with the GraphQL backend URL (from secret/outputs). Legacy secret names like `DAB_GRAPHQL_URL` may still be used:
0 commit comments