Getting started¶
Open the app¶
The app is deployed at https://app.virtufin.com. There is nothing to install: open it in a current browser (desktop or phone; at phone width the sidebar folds behind the ☰ button in the header).
Sign in¶
Signed out, the app shows only its sign-in page (Sign in to see the platform's workers, worlds and scenarios.) and a Log in button. Log in sends you to the organisation's identity provider (Pocket ID on medusa); after you sign in there you come back to the page you started from.
- A sign-in lasts 12 hours by default (
VIRTUFIN_APP_SESSION_HOURSon the server); after that the app asks you to log in again. - The header shows your name, a badge and Log out. Log out ends the session.
- If the provider takes longer than 10 minutes to send you back, the sign-in is refused (the sign-in took too long or was not started here; sign in again): log in again.
Roles: who may write¶
| You are | You may |
|---|---|
| Signed in (any member) | Read everything: every view, every list, every stream. The badge says read only; buttons that change something are disabled, with the tooltip Only admins may …. |
A member of the admin group (virtufin-admins by default, VIRTUFIN_APP_ADMIN_GROUP on the server) |
Also write: start, stop, create, delete, tag, schedule, share, halt, … The badge says admin. |
The app server enforces this, not only the buttons: a write from a non-admin is refused
with 403 only admins may write whatever sends it (a view, a script, the assistant). See
Architecture for how the server tells a
read from a write.
Your admin membership is read when you sign in: after a change in the provider's groups, log out and in again.
The context menu¶
Everything you see and do is on one context: one virtufin-api endpoint (for example
demo). The context menu, top right in the header, names the active context with a health
dot (green up, yellow connecting, red down or key refused). Click it to see every context,
its health, its description and whether it is protected, and to switch. On a protected
context the button is red and says protected: writes ask first. See
Contexts.
First steps¶
- Home lists the views this app has for the navigation in use and the active
context's state (
Context demo: up.). - Infra > Workers lists the context's workers, live. Type in the filter, e.g.
status:runningortag:world=act; click a row and press Detail (orEnter) for its config, tags, code history and lifecycle events. - Trading > Scenario shows the scenarios and their trading halt; Use picks the scenario P&L and Risk follow in this browser.
- Infra > Events → Topics… to follow some topics and watch their CloudEvents arrive.
- Settings > AI to add an AI provider key; then AI in the header opens the assistant on every view (Set up AI).
The How-tos walk through the common tasks.
For developers: run it locally¶
The app is a Vue 3 frontend with a small Node server side (the context proxy, sign-in, the AI relay and the change log). Locally the Vite dev server runs the same server side as a plugin.
cd src/VirtufinApp
npm install # @virtufin/* come from the Gitea npm registry (.npmrc, token from VIRTUFIN_REGISTRY_TOKEN)
npm run dev # http://localhost:3000
The contexts come from ~/.config/virtufin/api/contexts.toml, the same file the TUI and
the notebooks read (VIRTUFIN_CONTEXTS_FILE names another). Pick the starting context with
VIRTUFIN_CONTEXT:
A minimal contexts.toml:
[[contexts]]
name = "demo"
description = "medusa demo"
api_host = "api.virtufin.com"
api_port = 443
tls = true
api_key = "..." # or VIRTUFIN_API_KEY in the dev server's environment
protected = false
Without the sign-in settings (VIRTUFIN_APP_OIDC_ISSUER and the others, see
Architecture) the dev server signs no one in and everyone is
an admin: the header shows no sign-in (dev). With them set, the dev server signs in as
the deployed one does.
scripts/run_app.sh starts the backend (api, WorkManager) through the sibling
deploy-local repo and the frontend together. Build, typecheck and tests are in the repo
README (docs/README.md).