Developer Setup

The recommended development environment is a VS Code Dev Container (or GitHub Codespace). The .devcontainer/ configuration installs all required tooling automatically - no manual setup needed.

Opening the dev container

1. Open this repository in VS Code.
2. When prompted “Reopen in Container”, click Reopen in Container.
   • Or use the command palette: Dev Containers: Reopen in Container.
3. Wait for the container to build and the post-create/post-start scripts to finish.

The container is based on mcr.microsoft.com/devcontainers/typescript-node:22 and includes:

Tool	Version	Purpose
Node.js	22 LTS	JavaScript runtime
pnpm	10.x	Package manager (workspaces)
Nx	22.x	Monorepo task runner
Python	3.12	Pexip SDK and VM scripts
UV	latest	Python dependency management
Azure CLI	latest	Azure resource management
Azure Functions Core Tools	v4	Local Function App development
GitHub CLI (gh)	latest	PR and issue management
Azurite	latest	Local Azure Storage emulator

Post-create: what happens automatically

The setup.sh script runs once when the container is first created:

npm install -g nx pnpm azurite   # Global CLI tools
pip install uv                    # Python package manager
pnpm install                      # Node dependencies
uv sync                           # Python dependencies

Post-start: authentication checks

Every time the container starts, post-start.sh runs and reports auth status:

==> GitHub CLI status
    gh is authenticated ✓

==> Azure CLI status
    az is authenticated ✓  (subscription: ...)

If either is not authenticated, follow the prompts:

# GitHub
gh auth login

# Azure (use device code flow in containers)
az login --use-device-code

Common commands

Nx is installed globally, so you do not need a pnpm prefix:

# Documentation site
nx run docs:dev          # Dev server on :4321
nx run docs:build        # Production build

# Onboarding site
nx run onboarding:dev    # Dev server on :4322

# Pexip SDK (Function App)
nx run pexip-sdk:serve   # Local Function App on :7071
nx run pexip-sdk:test    # Run Python tests
nx run pexip-sdk:lint    # Ruff linting

# VM Start/Stop
nx run vm-start-stop:test

# Workspace-wide
nx graph                 # Dependency graph visualization
nx run-many -t lint      # Lint all projects
nx run-many -t test      # Test all projects

Forwarded ports

The dev container automatically forwards these ports:

Port	Service
4321	Docs site
4322	Onboarding site
7071	Azure Functions (local)
10000–10002	Azurite (Blob, Queue, Table)

Running the Function App locally

Before starting, ensure packages/pexip-sdk/local.settings.json exists and is complete (see below).

# From the repository root
nx run pexip-sdk:serve

Once running, the interactive OpenAPI docs (Swagger UI) are available at http://localhost:7071/docs.

This is auto-generated by FastAPI and reflects the current state of all endpoints, request/response schemas, and query parameters. Use it for:

• Exploring available endpoints without reading source code
• Testing API calls interactively with the “Try it out” feature
• Viewing the raw OpenAPI spec at http://localhost:7071/openapi.json

Note

Authentication is not required when running locally. The Azure API Management layer (which enforces OAuth2.0 bearer tokens) is only present in deployed environments.

Environment variables for local Function App

Create packages/pexip-sdk/local.settings.json (this file is git-ignored). All fields below are required — the Function App will fail to start if any are missing.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage__accountName": "samaxconftest",
    "QUEUE_URL": "https://samaxconftest.queue.core.windows.net",
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "AzureWebJobsFeatureFlags": "EnableWorkerIndexing",
    "KEYVAULT_URL": "https://kvlt-maxconf-test.vault.azure.net/",
    "AZURE_TENANT_ID": "953fc14a-00c7-4452-a2fb-0a73070de7f3",
    "PEXIP_CLIENT_ID": "<fetch from Key Vault: pexip-client-id>",
    "PEXIP_JWT_KEY": "<fetch from Key Vault: pexip-jwt-base64-token>",
    "LOG_ANALYTICS_WORKSPACE_ID": "<fetch from Key Vault: log-analytics-workspace-id>",
    "LOG_ANALYTICS_WORKSPACE_KEY": "<fetch from Key Vault: log-analytics-workspace-key>"
  }
}

Fetching secrets from Key Vault

With az login active, you can pull the required secrets directly:

az keyvault secret show --vault-name kvlt-maxconf-test --name pexip-client-id --query value -o tsv
az keyvault secret show --vault-name kvlt-maxconf-test --name pexip-jwt-base64-token --query value -o tsv
az keyvault secret show --vault-name kvlt-maxconf-test --name log-analytics-workspace-id --query value -o tsv
az keyvault secret show --vault-name kvlt-maxconf-test --name log-analytics-workspace-key --query value -o tsv

Paste the output of each command into the corresponding field in local.settings.json.

Storage authentication

AzureWebJobsStorage__accountName uses DefaultAzureCredential — no connection string is required. The dev container’s az login session satisfies this automatically provided you have at least Storage Queue Data Contributor on samaxconftest.

When to remove AZURE_CLIENT_ID and AZURE_CLIENT_SECRET

For local development in the dev container, these settings should usually be omitted.

Remove them when all of the following are true:

• You can run az login in the container.
• Your signed-in identity has data-plane access to the required resources (at minimum Storage Queue access on samaxconftest; Key Vault access if resolving secrets directly).
• You are not trying to validate behavior for a specific service principal.

Keep (or add) them only when one of the following is true:

• You are running in a non-interactive environment where az login is not available.
• You must explicitly test with a specific service principal identity.

If AZURE_CLIENT_ID/AZURE_CLIENT_SECRET are set and the secret is invalid, DefaultAzureCredential will prefer ClientSecretCredential, causing errors such as AADSTS7000215 and Unable to access AzureWebJobsStorage.

Managing Python dependency split safely

nx run pexip-sdk:* uses uv resolution from packages/pexip-sdk/pyproject.toml + uv.lock. Deployment paths may still consume packages/pexip-sdk/requirements.txt. Keep both in sync to avoid local-vs-deployed behavior drift.

Recommended workflow for dependency changes:

1. Update packages/pexip-sdk/pyproject.toml first.
2. Run uv lock from the repository root and commit uv.lock.
3. Mirror runtime-sensitive pins in packages/pexip-sdk/requirements.txt (for example authlib).
4. Validate the resolved local version with uv run python -c "import authlib; print(authlib.__version__)".

For this repository, authlib is pinned to 1.5.2 in both dependency files to avoid JWT key handling differences between local and deployed execution paths.

Caution

Local development connects to the test Pexip management environment. The storage queues on samaxconftest must be used (not Azurite) so that room-creation-queue and room-deletion-queue correctly reflect the rooms on the test Pexip instance.

VS Code extensions

The dev container pre-installs these extensions:

• Nx Console - Task explorer and project graph
• ESLint + Prettier - JavaScript/TypeScript formatting
• Ruff - Python linting and formatting
• Astro - .astro and .mdx file support
• Azure Functions - Local debugging and deployment
• Azurite - Storage emulator management
• GitHub Copilot - AI pair programming