Skip to content

Switch context

Goal: make the app work on another context (another virtufin-api endpoint), and tell whether a context is reachable.

Prerequisites

  • Signed in. Any user may switch; the choice is per browser.
  • The context is in the app server's catalog (contexts.toml on the server; locally ~/.config/virtufin/api/contexts.toml). Users cannot add contexts in the browser.

Steps

  1. Open the context menu: the button at the top right of the header, showing the active context's name and health dot.
  2. Read the list. Each context shows its dot (green up, yellow connecting, red down or key refused), its state (up, connecting, down, key refused), protected when it is, and its description. Hover the dot for the reason of a red one.
  3. Click the context you want. The app checks that it answers (at most 10 s) and only then switches.
  4. Check the header: the button names the new context. A protected context is shown red with protected: writes ask first.

What you should see

  • Every view reads again from the new context (filters and selections are dropped).
  • Home says Context <name>: up.
  • The choice is remembered in this browser for the next visit.

Troubleshooting

Symptom Cause and fix
Notice Switch to <name> failed: … and the old context stays The context did not answer within 10 s or refused the key. Its dot's tooltip has the reason.
State key refused The api answers but refuses the context's api_key (or the server's VIRTUFIN_API_KEY): the deployment must fix the key in contexts.toml.
State down, health stream ended The api is unreachable; the app retries every 5 s by itself.
No contexts: add them to contexts.toml on the app server. The catalog is empty or unreadable; the menu lists the problems (e.g. context foo: no api_port; left out).
Contexts unavailable: … banner The app server did not answer GET /contexts; reload the page.
An alert context <name> That context went down after it answered; an info alert follows when it is back.

More: Contexts.