> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valedo.uniwave.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run Valedo.API, the Publisher API and the add-in locally against the Azure dev resources.

## 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

```bash theme={null}
dotnet build Valedo.slnx
npm ci
npm run typecheck
```

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:

   ```bash theme={null}
   az login --tenant ed5c1757-0275-4beb-a5ea-072c938da4e2
   ```

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:

   ```bash theme={null}
   az ad signed-in-user show --query id -o tsv
   ```

   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:

   ```bash theme={null}
   az deployment group create -g uw-rg-valedo-weu-dev \
     --template-file infra/modules/cosmos-access.bicep \
     --parameters accountName=uw-cosmos-valedo-weu-dev \
       principalIds="[\"$(az ad signed-in-user show --query id -o tsv)\"]"
   ```

   To keep the access across deployments, add the same object ID in both places the dev deployment reads it from ([Deployment](https://docs.valedo.uniwave.ai/developers/deployment.md#developer-data-access)):

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

     ```bash theme={null}
     gh variable set DEVELOPER_PRINCIPAL_IDS --env dev --body "<object-id>[,<object-id>]"
     ```

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

   ```bash theme={null}
   cp src/Valedo.Api/appsettings.Development.example.json src/Valedo.Api/appsettings.Development.json
   cp src/Valedo.Publisher.Api/appsettings.Development.example.json src/Valedo.Publisher.Api/appsettings.Development.json
   cp src/Valedo.Worker/local.settings.example.json src/Valedo.Worker/local.settings.json
   ```

4. Set the dev app registrations (`AzureAd:*`) in user secrets: see [Entra app registrations](https://docs.valedo.uniwave.ai/developers/entra-apps.md#local-development-user-secrets). 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:

| | Dev | Prod |
| - | - | - |
| Cosmos DB account | `uw-cosmos-valedo-weu-dev` | `uw-cosmos-valedo-weu` |
| Resource group | `uw-rg-valedo-weu-dev` | `uw-rg-valedo-weu` |
| Developer data access | Yes, through `developerPrincipalIds` | No: `main.bicep` ignores `developerPrincipalIds` in prod |
| Local settings | `appsettings.Development.json`, `local.settings.json` | None; the apps get their settings from App Service |

* 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

```bash theme={null}
dotnet run --project src/Valedo.Api
dotnet run --project src/Valedo.Publisher.Api
```

| Host | HTTPS | HTTP |
| - | - | - |
| Valedo.API | `https://localhost:7101` | `http://localhost:5101` |
| Publisher API | `https://localhost:7102` | `http://localhost:5102` |

Check that both are up:

```bash theme={null}
curl -s https://localhost:7101/healthz
curl -s https://localhost:7102/healthz
```

## 4. Call the API

Import `postman/valedo-api.postman_collection.json` and the `valedo-local` environment (see [Postman](https://docs.valedo.uniwave.ai/developers/postman.md)). Set `accessToken` in the environment to a bearer token for your test tenant, then run the requests.

> [!WARNING]
>
> 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

```bash theme={null}
npm run dev -w src/web-admin
npm run dev -w src/web-publisher
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.