About this manual
This manual is part of the source code. It lives in the site/ folder of the repository,
is built with Docusaurus, and is published to git-pages by the
continuous integration of the project. Each page describes the software at the commit that
was built, so the manual cannot fall behind the interface.
What happens on each change
On every change to the default branch, and on every merge request that touches the code, the interface or the manual, the pipeline:
- builds the web interface and the server from the same commit;
- starts the server with a real Redis and local storage, and fills it with demo data: two clusters, three agents, one viewer account, two CPE mappings, alert rules and a report;
- drives a headless browser through the pages, and captures each screenshot the manual uses;
- builds the manual with the screenshots, failing if any image is missing;
- publishes the manual to git-pages, on the default branch only.
Because the screenshots are captured again on every run, a change to the interface shows up in the manual on the next pipeline without anyone editing an image.
The demo data is written by site/screenshots/seed.mjs. The fixtures it uploads are the
CycloneDX documents in site/screenshots/fixtures. The screenshots are taken by
site/screenshots/capture.mjs, which lists each image with the page it shows.
Writing the manual
- Write pages as Markdown in
site/docs. The folders are the three guides, User, Administrator and Reference; the sidebars are insite/sidebars.js. - Link to other pages with their address, such as
/admin/hosts, so that the build checks the link. A broken link fails the build. - Reference a screenshot with a light and a dark version, one inside each
screenshot-lightandscreenshot-darkdiv:and. The reader's theme picks one of them. To add one, add it tosite/screenshots/capture.mjsfirst; the script takes both versions. - Keep the wording of the interface exactly as it appears: button labels, column names and tab names. The screenshots are the proof.
- Put facts that change often, such as default values, in the environment reference and link to them from the guides.
Building it locally
Node.js 20 or later and pnpm are needed.
make docs # install and build the manual into site/build
make docs-start # a live preview at http://localhost:3000
make docs-screenshots # captures the screenshots from a running server
make docs-screenshots needs a running server that has no data yet, because it creates the demo
users, agents and rules. Set VOP_URL to its address and VOP_ADMIN_PASSWORD to the password of its
administrator, and set CHROMIUM_PATH if no Chromium is installed for Playwright. Without screenshots the
build still succeeds, with warnings for the missing images; the pipeline builds with DOCS_STRICT=1, which
fails instead.
Versions
The manual describes the version of the software in the commit it was built from. The pages are not versioned separately. If you run an older release, read the manual of that release in its repository, not the latest one.