Skip to content

Developer Getting Started

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

Getting Started (Developer)

This guide walks you through setting up a local mate development environment.

Local Dev Flow

flowchart LR
   CLONE[Clone repo] --> ENV[Create infra/local/.env]
   ENV --> CHOOSE{Run mode}
   CHOOSE -->|Docker| DC[docker compose up --build]
   CHOOSE -->|dotnet run| DR[Run WebUI directly]
   DC --> STACK[PostgreSQL + Azurite + WebUI + Worker]
   DR --> WEB[WebUI only]
   STACK --> OPEN[Open http://localhost:5000]
   WEB --> OPEN
Loading

This is the fastest way to understand the local developer workflow: clone, configure local environment values, choose the runtime path, then validate the WebUI and backing services.

Prerequisites

Tool Version Notes
.NET SDK 9.0+ Check global.json for the exact version
Docker Desktop Latest Required for the containerised stack
Git Any
A code editor VS Code / Rider / Visual Studio

Clone the Repository

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

Option A — Docker (recommended)

The easiest way to run the full stack locally.

flowchart TD
   E1[infra/local/.env] --> C[Docker Compose]
   C --> PG[postgres]
   C --> AZ[azurite]
   C --> WEB[webui :5000]
   C --> WK[worker]
   WEB --> DB[(PostgreSQL)]
   WEB --> BS[Azurite Blob Storage]
   WK --> DB
   WK --> BS
Loading

1. Create the environment file

cp infra/local/.env.template infra/local/.env

Edit infra/local/.env to set at minimum:

Authentication__Scheme=Generic

2. Build and start

cd infra/local
docker compose up --build

This starts PostgreSQL 17, Azurite, mate-webui, and mate-worker automatically — no profile flag required.

Services started:

Service Port Description
postgres 5432 PostgreSQL 17 database
azurite 10000 Azurite blob storage emulator
webui 5000 Blazor Server + REST API
worker — Background test-run worker

Open http://localhost:5000.

3. Stop

docker compose down

Option B — dotnet run (WebUI only)

For fast iteration on the WebUI without Docker (requires a running PostgreSQL instance):

cd src/Host/mate.WebUI
dotnet run

The app starts on http://localhost:5000 (port defined in launchSettings.json).
Set ConnectionStrings__Default in appsettings.Development.json to point at your local PostgreSQL database.

Running Tests

# All tests
dotnet test mate.sln

# Unit tests only
dotnet test tests/mate.Tests.Unit/mate.Tests.Unit.csproj

# Integration tests
dotnet test tests/mate.Tests.Integration/mate.Tests.Integration.csproj

Environment Variables Reference

Variable Default Description
Authentication__Scheme Generic Auth mode: Generic (anonymous) · EntraId (Azure AD OIDC)
Infrastructure__Provider Container Blob storage backend: Container (Azurite) · Azure (Azure Blob Storage). Database is always PostgreSQL.
ConnectionStrings__Default (baked into docker-compose.yml) PostgreSQL connection string
AzureInfrastructure__BlobConnectionString UseDevelopmentStorage=true;DevelopmentStorageProxyUri=http://azurite Azurite emulator or Azure Blob Storage connection string
AzureInfrastructure__BlobContainerName mate-blobs Blob container name
AzureInfrastructure__UseKeyVaultForSecrets false Core secret backend switch (false = database, true = single-vault)
AzureInfrastructure__KeyVaultUri — Required when single-vault mode is enabled
AZURE_CLIENT_ID — Required in Docker single-vault mode
AZURE_CLIENT_SECRET — Required in Docker single-vault mode
AZURE_TENANT_ID — Required in Docker single-vault mode
AzureAd__TenantId — Required for EntraId scheme
AzureAd__ClientId — Required for EntraId scheme
AzureAd__ClientSecret — Required for EntraId scheme
AzureAd__RedirectUri — Required for EntraId scheme — public HTTPS URL of the app

AI Judge, Question Generation, and Monitoring settings are configured through the Settings UI in the application and stored in the database — no environment variables needed.

All __ separated keys map to nested JSON config sections.
Set them in infra/local/.env (Docker) or appsettings.Development.json (direct run).

Core Secrets Mode Switch (Developer Verification)

flowchart LR
   S[Secrets mode switch] -->|UseKeyVaultForSecrets=false| DBM[Database mode]
   S -->|UseKeyVaultForSecrets=true| KVM[Single-vault mode]
   DBM --> REBUILD[Rebuild containers]
   KVM --> REBUILD
   REBUILD --> VERIFY[Verify app + secret path]
Loading

To run database mode (default):

AzureInfrastructure__UseKeyVaultForSecrets=false
AzureInfrastructure__KeyVaultUri=

To run single-vault mode:

AzureInfrastructure__UseKeyVaultForSecrets=true
AzureInfrastructure__KeyVaultUri=https://<your-vault>.vault.azure.net/
AZURE_CLIENT_ID=<app-client-id>
AZURE_CLIENT_SECRET=<app-client-secret>
AZURE_TENANT_ID=<tenant-id>

After switching values, rebuild containers:

./debug-container.ps1 -Stop
./debug-container.ps1 -Source build -Rebuild

Quick database-mode verification:

docker exec mate-postgres psql -U mate -d mate -c 'SELECT "RefName","TenantId" FROM "AppSecrets" ORDER BY "UpdatedAt" DESC LIMIT 10;'

Switching to EntraId Authentication

  1. Register an app in Azure Entra ID (App Registrations).
  2. Set the redirect URI to https://<your-domain>/signin-oidc.
  3. Set environment variables: 
    Authentication__Scheme=EntraId
AzureAd__TenantId=<your-tenant-guid>
AzureAd__ClientId=<your-app-client-id>
AzureAd__ClientSecret=<your-client-secret>
  4. The app must be served over HTTPS — Azure AD's form_post callback is blocked by browsers on HTTP.

For local EntraId testing, use an nginx reverse proxy with a valid TLS certificate (see infra/ for examples).

Project Structure Quick Reference

src/Core/mate.Core           — module registry, execution engine
src/Core/mate.Domain         — entities, contracts
src/Host/mate.WebUI          — Blazor pages, Minimal API endpoints, Program.cs
src/Host/mate.Worker         — IHostedService, TestRunWorker
src/Infrastructure/          — PostgreSQL/Azurite/Azure implementations
src/Modules/                 — pluggable agent connectors, judge modules
tests/                       — Unit, Integration, EndToEnd
infra/local/                 — docker-compose.yml, Dockerfiles, .env.template
docs/wiki/                   — full user and developer documentation

Next Steps

mate

Home

User Documentation

Developer Documentation

Clone this wiki locally