Installation (Local Dev)

Consystence is built from a single server source tree, but the deployment mode — Cloud org manager or Site server — is baked into each published artifact at publish time and is never read from configuration: a Site binary cannot be flipped to Cloud at runtime. A from-source build is Site-mode; the Cloud artifact is not distributed. For local development you run the server from the consystence monorepo; a plain dotnet run produces a Site-mode server (the fail-closed default). In the Development environment it boots with in-memory state and stub authentication, so you need neither a database, an edge runtime, nor a physical controller to get a working UI.

This page covers a from-source local install. For a guided first run once the server is up, see the quickstart; for the underlying ideas, see core concepts.

Prerequisites

Tool	Version	Required?	Why
.NET SDK	10	Yes	Builds and runs the server (`net10.0`).
Node.js	22	Yes, for the default build (skip with `-p:SkipFrontendBuild=true`)	Builds the browser bundle (esbuild) and CSS (Tailwind v3).
PostgreSQL	16	Optional	Orleans uses in-memory grain storage in dev; Postgres is only needed to exercise persistence.
Git	recent	Yes	Clone the monorepo.

1. Clone the monorepo

git clone <repo-url> consystence
cd consystence

Everything below runs from inside this checkout. The backend lives under backend/, the browser frontend under frontend/.

2. Build and run the server

The server project is backend/Server/Consystence.Server. From the backend/ directory:

cd backend

# Optional — dotnet run restores and builds on its own
dotnet restore
dotnet build Consystence.slnx

# Run the server (uses the default 'dev' launch profile)
dotnet run --project Server/Consystence.Server

The dev launch profile binds the server to http://0.0.0.0:8080, so open:

http://localhost:8080

To open the solution in an IDE, use backend/Consystence.slnx. To run the test suite, use dotnet test from backend/.

3. Build the frontend assets

The UI is server-driven — the server publishes a semantic UI tree over SignalR and the browser’s wire renderer draws it — but the browser still needs a compiled JavaScript bundle and stylesheet. These are built into the server’s wwwroot/ directory by the frontend toolchain. You normally don’t need to run it by hand: dotnet build / dotnet run invoke npm ci, npm run build, and npm run css automatically on every build via MSBuild targets (pass -p:SkipFrontendBuild=true to build without Node.js — the UI then serves unstyled until assets are built). To build the assets manually — for example when iterating on UI code:

cd frontend
npm install

# Build CSS (Tailwind v3) + JS (esbuild) into backend/Server/Consystence.Server/wwwroot/
npm run build:all

While iterating on UI code, run a rebuild-on-change watcher instead:

npm run watch

Both write into backend/Server/Consystence.Server/wwwroot/, which the server serves as static assets — but note that watch rebuilds only the JS bundle (js/consystence.js). After changing tailwind-input.css or Tailwind class usage, re-run npm run css (or build:all) to refresh the stylesheet.

What runs in development mode

With ASPNETCORE_ENVIRONMENT=Development (the default for the dev profile), the server:

runs as a Site-baked binary — the mode is stamped at build time and every local build defaults to Site, so cloud-only surfaces such as /api/provision/* return 404;
uses in-memory Orleans grain storage — no PostgreSQL connection required;
uses a stub auth client with mock data — no external identity service required;
starts with no tenant unless a bootstrap file is configured; seed one yourself via the tenant bootstrap (see the quickstart) — the CLI’s tenant import targets a cloud cell, not a site-mode server;
exposes Swagger UI at /swagger.

Because state and simulated device data live in-process, you do not need the edge runtime or a physical/virtual controller to run the server locally. To work on the edge tier itself, see the edge runtime docs.

Authentication in development

Production identity is Entra External ID (CIAM) via the account control plane; membership is keyed by the Entra oid, and email is only a verified attribute. None of that runs locally. In dev the server defaults to mock/demo auth so you can reach the UI and API immediately. If you want to exercise a real OIDC flow, point the Oidc / Jwt configuration at a local IdP or a real Entra tenant — the full selector model (CIAM Bearer, tenant X-Api-Key, site-PIN JWT) is described in the API auth model.

Troubleshooting

Symptom	Fix
Port `8080` already in use	Find the owner with `lsof -i :8080`, or change `applicationUrl` in `Server/Consystence.Server/Properties/launchSettings.json`.
UI loads unstyled / no interactivity	Frontend assets are missing from `wwwroot/`. Run `npm run build:all` in `frontend/`, or rebuild with Node.js installed so MSBuild builds them automatically.
Orleans silo fails to start	Another silo with the same cluster/service ID is already running on this machine — stop it and retry.
Cloud-only endpoints (e.g. `/api/provision/*`) return 404	The binary is Site-baked — the default for every local build, and the Cloud artifact is not distributed. Confirm the mode with `dotnet run --project Server/Consystence.Server -- --print-mode`.

Next steps

Quickstart — first run, demo org, and a guided tour.
Core concepts — orgs, sites, device types, server modes.
Deploying to Azure — running the platform on Azure Container Apps.