Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.
2. Run your first application
The quickest introduction is the supplied document workflow. It provisions its own resources, uploads a document, sends queue work, writes SQL data, caches a result and queries its telemetry.
Step 1: check the prerequisites
Use a Linux x86-64 development machine with Docker Engine and Compose v2, GNU
Make, Python 3, OpenSSL, .NET SDK 10, and Node.js 24 LTS or a compatible newer
LTS. The first build needs access to package registries and container images.
The runtime image is docker-dotnet:latest from the sibling Triglav-OS project.
Build it there with make -j8 docker-dotnet if it is unavailable. Quinzee can
load its exported image from ../os; set TRIGLAV_OS_DIR for a different checkout.
Check the commands on the host:
docker version
docker compose version
dotnet --version
node --version
python3 --version
openssl version
The application helper builds the cloud image and the .NET/React application; you do not need to build the native QHQ application first. If you want QHQ or a native emulator binary, follow Building from source.
Step 2: start the environment
From the repository root on the host:
make application-observability-up
Leave this terminal running. Initial setup downloads/builds dependencies,
prepares native engine images, creates private certificates and starts the cloud,
DNS, application, engine supervisor and telemetry tools. Subsequent runs reuse
the environment in .local/application/development.
The command prints the application URL (normally https://localhost:3000),
the public browser CA path and the path to an application access-token file.
Wait for those messages before opening the browser. Build and environment logs
are in .local/application/development/environment.log.
For the same environment without the external dashboards, use
make application-up instead. Application Insights and Log Analytics APIs still
work; those services run inside Quinzee itself.
Step 3: open and sign in
- Trust the public development CA certificate printed by the command in
your development browser. This environment has its own CA, separate from the
one used by
make cloud-up. Do not import a private.keyfile. - Open the printed HTTPS URL. The browser should accept the certificate for
localhost; do not bypass a certificate warning. - Read
.local/application/development/access-tokenprivately and paste the token into the application's sign-in form.
This browser token unlocks the example application's UI. It is not an Azure bearer token or the application's client secret. Azure credentials remain in the backend's private settings; the browser does not receive them.
Connect with the private token printed by your launcher. The image intentionally shows the form before a token is entered.
Step 4: process a document
Select PostgreSQL and leave the initial document text in place. Start the workflow. Each step shows its progress, including provisioning, Key Vault and App Configuration access, Blob and Queue operations, SQL/Redis writes and Application Insights queries. A successful run shows a trace ID.
Repeat with MySQL. The template provisions both SQL engines; the selection controls which one processes the document. This uses real database servers, not in-memory mock SQL responses.
Choose Verify with the same database and document to check persisted data and recover the leased queue item left by the run. A verification consumes that recovery item: run the full workflow again before repeating that recovery check. Cancel stops client work, but does not roll back resources already created. Cleanup deletes this sample application's resource group and its data.
Step 5: find the trace
Grafana is normally https://localhost:13001. Trust
.local/observability/ca.crt, sign in as admin with the password from
.local/observability/grafana-password, and open the Quinzee observability
dashboard. In Explore, select Tempo and look up the workflow trace ID. The
trace can include application, cloud and engine spans.
Use the monitoring chapter to understand the separate platform dashboards and Azure-compatible application telemetry APIs.
Step 6: continue or stop
Keep the environment running for the next chapter. To finish a session, first exit any development containers you joined to its network, then press Ctrl+C in the application terminal. Its state and native data volumes are retained. Stop the separately operated dashboard tools with:
make observability-down
Restart with the same application command to reuse your environment. Use application/resource-group cleanup only when you intend to delete data.