Skip to main content

​
Prerequisites

  • .NET 10 SDK (see global.json)
  • Node.js 20 or later with npm (the repository root is an npm workspace)
  • Azure CLI, signed in to the publisher tenant (local debugging uses the Azure dev resources); Bicep for deployment
  • Azure Functions Core Tools and Azurite, for the Worker
  • An Entra ID test tenant with an app registration for the API

​
1. Build the solution

Building Valedo.API also regenerates src/Valedo.Api/openapi/Valedo.Api.json.

​
2. Configure the hosts against Azure dev

Local debugging uses the Azure dev resources (Cosmos DB uw-cosmos-valedo-weu-dev, database signatures), not emulators. The hosts sign in to Cosmos DB with your own Entra identity through DefaultAzureCredential; the account has key authentication disabled, so there is no connection string.
  1. Sign in to the publisher tenant with the Azure CLI:
  2. Get Cosmos DB data access on dev (Cosmos DB Built-in Data Contributor). Without this role, every Cosmos DB request from your machine fails with 403. Get your object ID first:
    To grant the role right away, without a full redeploy, deploy only the access module. It creates the same role assignment the full deployment does:
    To keep the access across deployments, add the same object ID in both places the dev deployment reads it from (Deployment):
    • developerPrincipalIds in infra/parameters/main.dev.parameters.json, for deployments from your machine;
    • the DEVELOPER_PRINCIPAL_IDS variable of the GitHub dev environment (comma-separated), for deployments from the workflow:
      --body replaces the whole value, so include the IDs that are already there (gh variable get DEVELOPER_PRINCIPAL_IDS --env dev).
  3. Copy the Development settings. They already point at dev; real settings files are gitignored.
  4. Set the dev app registrations (AzureAd:*) in user secrets: see Entra app registrations. Put any client secret or certificate in user secrets, never in a file.
The Worker still uses Azurite for AzureWebJobsStorage (UseDevelopmentStorage=true); start it with azurite before func host start. In VS Code, start azurite and then the Valedo: back ends launch configuration.

​
Production

Local debugging never targets prod. Prod Cosmos DB (uw-cosmos-valedo-weu) holds customer data, and only the managed identities of the two prod App Service apps have data access to it:
  • Don’t point local settings or user secrets at the prod account, and don’t run cosmos-access.bicep against it: either would bypass the rule that no developer identity reads prod customer data (README §15.1).
  • Investigate prod issues from telemetry in Application Insights uw-appi-valedo-weu and Log Analytics uw-log-valedo-weu. Logs contain object IDs only, never tokens or rendered signatures.
  • To reproduce a prod problem, recreate the data in dev and debug there.

​
3. Run the hosts

Check that both are up:

​
4. Call the API

Import postman/valedo-api.postman_collection.json and the valedo-local environment (see Postman). Set accessToken in the environment to a bearer token for your test tenant, then run the requests.
Never paste a real token into a committed file or into the collection. The accessToken variable is marked secret and must stay empty in the example environment files.

​
5. Run the front ends