Development#
This section is for whoever builds Wheelhouse from source, extends it, or has to find
out why a build broke. It covers 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, what continuous integration runs, how a release is cut, and the
decisions that were written down. Every page links the files it describes; start with
the row below that matches what you want to change.
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:
| 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 test router and its automation, the build host, deployment paths |
HomelabInfra | The environment: the network the product is exercised against, including the OPNsense router whose configuration is the reference workload |
Product decisions, feature scope and architecture belong here. Test-router, build-host
and deployment work belongs in wheelhouse-infra. 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 test router. How the development router is built and reached lives in
wheelhouse-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 inventory of what is built.
- 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.