Development#
This section is for whoever has to build Wheelhouse from source, extend it, or find out
why a build broke. It describes the pieces the product is made of and the boundary
between them, the four things that get built (the agent, the web UI, the .deb and the
ISO), the test suites and what each one covers, what continuous integration runs, how a
release is cut and published, and the decisions that were written down rather than
argued about twice. Everything here is checkable against the repository, and every claim
links to the file it came from.
Where to start#
| If you want to | Read |
|---|---|
| Understand the pieces before touching any of them | Architecture |
| Find a file | The repository, directory by directory |
| Get something running on your own machine | A development environment |
| Change the control plane | Building the agent, then Adding an endpoint |
| Change the web UI | Building the web UI, then Adding a page to the web UI |
| Add an application to the store | Adding an app to the catalogue |
| Produce an installable artefact | Building the package, then Building the image |
| Change what makes the image the product's rather than the base's | The flavor and the branding hooks |
| Know what CI will say before you push | The test suites and What CI does |
| Ship a version | Making a release |
| Know why something is the way it is | Architecture decision records |
| Know what is expected of a change | Working agreements |
The shape of the thing, in one paragraph#
Wheelhouse OS is a VyOS image with two programs added. wheelhouse-agent is a single
static Go binary, run by systemd as root, that drives the router through VyOS' own HTTP
API and serves a React single-page application on port 8443. The agent copies no VyOS
code and links against none: it posts to /retrieve, /show, /configure,
/config-file and /image on https://127.0.0.1 with an API key it mints for itself
on first boot — agent/vyos.go,
packaging/firstboot.sh. Everything the product ships is
built from this one repository by scripts that need Go, Node and the Python standard
library, and nothing else.
The three repositories#
The product repository is not the whole picture. AGENTS.md sets the
split, and it exists so that a fact is written down once:
| Repository | Holds |
|---|---|
wheelhouse (this one) | The product: PLAN.md, the agent, the UI, packaging, the image pipeline, the tools, this documentation |
wheelhouse-infra | The platform: the development bench, the vyoslab router and its automation, deployment paths |
HomelabInfra | The environment: the homelab, including the production OPNsense router whose configuration is the reference workload |
Product decisions, feature scope and architecture belong here. Bench, build-host and
deployment work belongs in wheelhouse-infra. Facts about the homelab belong in
HomelabInfra. Nothing is duplicated across them; a commit that spans two names the
sibling commit.
What this section does not cover#
- Using the product. That is the rest of this wiki.
- Writing for this documentation site. The generator, the front matter and the Markdown it accepts are on Contributing and the page template.
- The bench. How the
vyoslabdevelopment router is built and reached lives inwheelhouse-infra, not here.
See also#
- How Wheelhouse works — the mental model the code implements. Read it before the architecture page if you have not used the product.
- Reference — the flags, files, endpoints and metrics, enumerated.
- What is finished, and what is not — the honest inventory, which this section is not allowed to contradict.
- About Wheelhouse — the licence boundary, the corresponding source and the trademark position, all of which constrain what a change is allowed to do.
- Contributing to this documentation — the site you are reading.
- The product site — what is claimed publicly, which the code has to keep true.
Checked against#
AGENTS.md ·
README.md ·
PLAN.md ·
agent/vyos.go ·
packaging/firstboot.sh