Web client to the Oxide API.
At https://console-preview.oxide.computer, the console is deployed as a static site with a mock API running in a Service Worker. You can create mock resources and they will persist across client-side navigations, but they exist only in the browser: nobody else can see them and the mock "DB" is reset on pageload. Request and response bodies in the mock API match the Oxide API's OpenAPI spec, but behavior is only mocked in as much detail as is required for development and testing of the console and is not fully representative of the real API.
In order to avoid the complexity of server-side rendering (and running JS on the rack), the web console is a fully client-side React app. We use Vite (which uses Rollup internally for production builds) to build a set of assets (index.html
, JS bundles, CSS, fonts, images) and we serve those assets as static files from a special set of console endpoints in Nexus. From the control plane API server's point of view, the web console simply is:
The web console has no special privileges as an API consumer. Logging in sets a cookie, and we make cookie-authed API requests after that. See RFD 223 Web Console Architecture (internal document for now) for a more detailed discussion. The endpoints live in nexus/src/external_api/console_api.rs
in Omicron.
The app is in app
. You can see the route structure in app/routes.tsx
. Also in app
we have a ui
dir where the low-level components live and an api
dir where we keep the generated API client and a React Query wrapper for it. The latter is aliased in tsconfig.json
for easy import from the main app as @oxide/api
.
Use Node.js v18+.
npm install
npx playwright install # only needed to run e2e tests
This is the way we do most console development. Just run:
npm run dev
and navigate to http://localhost:4000 in the browser. The running app will automatically update when you write a source file. This mode uses Mock Service Worker to run a mock API right the browser. This mock API is also used in tests.
Pick a user from the list of users in
mock-api/user.ts
. The one without fleet
viewer permissions is Hans Jonas
. Open the browser console and run:
document.cookie = 'msw-user=Hans Jonas;domain=localhost;path=/'
You are now user Hans Jonas. To go back to the default, delete the cookie. (We will get the mock API to clear the cookie for you on logout soon.)
You can also run the console dev server locally with the mock server off, instead passing requests through to localhost:12220
. Run npm run start:nexus
and navigate to http://localhost:4000/login/test-suite-silo/local in the browser. It will not work unless Nexus is running at localhost:12220
, which is the default for omicron-dev
(see Running Omicron (Simulated) for how to set that up).
One way to run everything is to use the tools/start_api.sh
script, which uses tmux to run multiple processes in different panes and automatically populates some fake data (see tools/populate_omicron_data.sh
to see exactly what). From the omicron directory, run tools/start_api.sh
. Since we're assuming console
and omicron
are next to each other, that looks like this:
../console/tools/start_api.sh
npm run start:dogfood
/login
, which will look like a 404session
cookie value, which should look like d9b1a96e151092eb0ea08b1a0d8c4788441f1894
document.cookie = 'session=d9b1a96e151092eb0ea08b1a0d8c4788441f1894;domain=localhost;path=/'
Go to https://localhost:4000 again and you should be logged in.
npm run ladle
This will start a preview environment for UI components at http://localhost:61000
.
Playwright tests live in test/e2e
. npm run e2e
runs the tests in Chrome, Firefox, and Safari, but this is rarely necessary in local dev. npm run e2ec
is a shortcut for playwright test --project=chrome
, which runs the tests in Chrome only (the fastest one, useful for local dev). Playwright has an excellent UI mode for running and debugging tests that you can get to by running npm run e2e -- --ui
.
To debug end-to-end failures on CI, check out the branch with the failure and run ./tools/debug-ci-e2e-fail.sh
. It'll download the latest failures from CI and allow you to open a playwright trace of the failure.
Command | Description |
---|---|
npm run dev |
Run Vite dev server with mock API |
npm test |
Vitest unit tests |
npm run e2ec |
Run Playwright E2E tests in Chrome only |
npm run lint |
ESLint |
npx tsc |
Check types |
npm run ci |
Lint, tests (unit and e2e), and types |
npm run ladle |
Run Ladle (Storybook) |
npm run fmt |
Format everything. Rarely necessary thanks to editor integration |
npm run gen-api |
Generate API client (see docs/update-pinned-api.md ) |
npm run start:mock-api |
Serve mock API on port 12220 |