oc3-frontend is a single-page application that replaces the web2py + jQuery interface of the legacy collector (opensvc/collector). It talks exclusively to the oc3 REST API, typed from its OpenAPI specification, and receives changes in real time over the websocket of the oc3 messenger.
- Features
- Requirements
- Quick start
- Configuration
- Scripts
- Architecture
- Deployment
- Contributing
- License
Inventory and operations
- About thirty views: nodes, clusters, services, instances, resources, actions, networks, disks, SAN switches, hardware, packages, apps, tags, requests, compliance (modulesets, rulesets, designer, logs), statistics, and administration (users, teams, filters, filtersets, forms, metrics, charts, reports).
- Tabbed detail panels (properties, inventory, checks, alerts, logs, sysreport, statistics…), with a history of the records viewed, bookmarks and cross-links between objects.
- Actions on objects from a dedicated menu: queued agent actions (start, stop, freeze…) and data actions, filtered by the user's privileges and confirmed before they run.
Lists
- Per-column filters in a popover, with operators, regular expressions and the distribution of values; multi-column sorting; column selection and ordering.
- CSV and XLSX export of the whole selection, hidden columns included on demand.
- Comparison of the selected rows (common attributes), and saving the active filters as a filterset.
- Columns, sort, filters and page size remembered with the user's account.
Navigation
- Global search (
Ctrl+Kor/) across every kind of object, narrowed to one kind with a prefix (node:,svc:,fset:…), as in the legacy collector. - Session filter: a filterset that narrows every list at once.
- Keyboard shortcuts (
?lists them); detail panels on the right or on the left.
Accessibility and appearance
- English and French interface, with bilingual search.
- Light and dark modes; standard, high-contrast and colour-blind friendly themes.
- A state is never conveyed by colour alone: an icon, a shape or a label always goes with it.
- Live updates, without reloading, as the agents send their data.
- Node.js 24 LTS or later (see
.nvmrc) and npm; - a reachable oc3 instance: its API (
server) and its messenger (websocket); - a collector account to sign in with.
git clone https://github.com/opensvc/oc3-frontend.git
cd oc3-frontend
cp .env.example .env # oc3 API address, see Configuration
npm install
npm run dev # http://localhost:5173In development, Vite serves the application and proxies /api and /realtime to oc3:
the browser only ever talks to a single origin, so there is no CORS to configure.
After a change to the oc3 API, regenerate the client types:
npm run gen:api # updates src/lib/api/schema.d.ts from the OpenAPI specVariables go in .env (never committed; .env.example is the template).
| Variable | Purpose | Default |
|---|---|---|
OC3_API_TARGET |
URL of the oc3 API that /api is proxied to |
http://localhost:8080 |
OC3_OPENAPI_URL |
URL of the OpenAPI spec read by npm run gen:api |
http://127.0.0.1:8081/api/openapi.json |
OC3_REALTIME_TARGET |
URL of the oc3 messenger that /realtime is proxied to |
API host, port 8889 |
OC3_PUBLIC_HOST |
Public host name when the dev server is exposed behind a TLS gateway | empty |
| Command | Purpose |
|---|---|
npm run dev |
Development server with hot reload |
npm run build |
Type check, then production build into dist/ |
npm run preview |
Serve the production build locally |
npm run typecheck |
Type check only |
npm run lint |
ESLint |
npm test |
Unit tests (Vitest, jsdom), in watch mode |
npm run test:ci |
Unit tests, once |
npm run format |
Prettier, with Tailwind class sorting |
npm run gen:api |
Regenerate the API types from the oc3 OpenAPI spec |
| Area | Choice |
|---|---|
| UI | React 19, strict TypeScript, Vite |
| Data | TanStack Query, typed openapi-fetch client generated by openapi-typescript |
| Routing | TanStack Router; the state of each view (sort, filters, selection, tab) lives in the URL |
| Tables | TanStack Table and Virtual |
| Styling | Tailwind CSS 4 and design tokens (src/styles/tokens.css) |
| Translation | i18next, en and fr catalogs |
src/
├── app/ router and application shell (top bar, menu, search, panels)
├── components/
│ ├── ui/ generic components, with no knowledge of OpenSVC
│ └── opensvc/ business components shared across views
├── features/<view>/ one collector view per folder
├── lib/ API client, preferences, filters, formatting, export…
├── i18n/ translation setup and catalogs
└── styles/ design tokens and global CSS
A few principles hold it together:
- every API call goes through
src/lib/api/client.tsand TanStack Query;src/lib/api/schema.d.tsis generated and never edited by hand; - a gap in the API is fixed in the oc3 spec, not worked around here;
- colours, radii and sizes come from the design tokens, never from hard-coded values;
- every visible string goes through
t(), in English and in French.
The application and the oc3 API must share one HTTPS origin: the sign-in cookies are
Secure and __Host- prefixed, and oc3 refuses session requests coming from another
origin. Terminate TLS in front of the frontend, on the public host name — the one
server.oidc.redirect_url names when OpenID Connect sign-in is enabled.
The Dockerfile builds the application and serves it with an unprivileged nginx
(uid 101, port 8080), which also proxies /api and /realtime to oc3.
Each published release is built and pushed as ghcr.io/opensvc/oc3-frontend, tagged
with its version, <major>.<minor>, <major> and latest, and signed with cosign.
The other pushes and pull requests to main are built, not pushed. To build it
yourself:
docker build \
--build-arg VERSION="$(git describe --tags --always)" \
--build-arg BUILDTIME="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-t opensvc/oc3-frontend .
docker run -d -p 8080:8080 \
-e OC3_API_UPSTREAM=http://oc3-server:8081 \
-e OC3_REALTIME_UPSTREAM=http://oc3-messenger:8889 \
opensvc/oc3-frontend| Variable | Purpose | Default |
|---|---|---|
OC3_API_UPSTREAM |
oc3 server that /api is proxied to, path kept |
http://oc3-server:8081 |
OC3_REALTIME_UPSTREAM |
oc3 messenger that the /realtime websocket is proxied to |
http://oc3-messenger:8889 |
OC3_LISTEN_PORT |
Port nginx listens on inside the container | 8080 |
OC3_MAX_BODY_SIZE |
Largest request body accepted for /api |
32m |
The nginx configuration lives in deploy/nginx/. Besides the proxying, it:
- returns
index.htmlfor any path that is not a file, since the application does its own routing; - caches the hashed files of
assets/for a year, and never cachesindex.html, so a new release is picked up at the next page load; - sets a strict Content-Security-Policy (everything from this origin only), along with
X-Frame-Options,X-Content-Type-OptionsandReferrer-Policy; - forwards
X-Forwarded-Protofrom the TLS gateway, or sets it from its own scheme; - answers
GET /healthz, used by the image'sHEALTHCHECK.
nginx resolves the upstream host names when it starts: they must exist by then.
npm ci
npm run builddist/ holds static files. Serve them on the same origin as above, with the same rules
as deploy/nginx/default.conf.template: /api to the oc3 API, /realtime (websocket) to
the oc3 messenger, index.html for any other unknown path.
npm ci
npm run build:singledist-single/index.html is the whole application in one file (about 2.4 MB): the
script, the stylesheet, the fonts and the images are inlined, nothing else is loaded.
dist-single/index.html.gz is the same, gzipped (about 760 kB), for a server that
sends it as is, as nginx does with gzip_static always. Serve it on the same origin as
above, for / and any path that is not /api or /realtime.
Each published release gets its gzipped single file as an asset, index.html.gz:
https://github.com/opensvc/oc3-frontend/releases/download/<version>/index.html.gz,
or https://github.com/opensvc/oc3-frontend/releases/latest/download/index.html.gz
for the latest release. The OpenSVC oc3 template seeds its key from there.
The file carries its own Content-Security-Policy, in a <meta> tag: its single inline
script allowed by hash, fonts and images as data URIs, everything else from this origin
only. The header policy of deploy/nginx/security-headers.conf forbids inline scripts:
a server of the single file must not send it, nor any policy stricter than the file's.
Nothing is cached apart: a page load revalidates the file, and each release downloads it
whole, its fonts and images included, where the standard build keeps those it has.
Contributions are welcome through pull requests. Before opening one:
npm run typecheck && npm run lint- Code comments are written in English.
- Every new visible string is added to both
src/i18n/locales/en.jsonandfr.json. - A new npm dependency must be justified in the pull request; a copied component or a few lines of code are preferred.
- A view ported from the legacy collector lists its deliberate parity gaps.
Released under the Apache 2.0 license.