A management UI and REST API running on every SEAPATH node, so that a machine installed from the ISO is usable from a browser, several machines can be joined into a cluster, and Ceph can be deployed on top, with no separate Ansible control machine.
It does not configure machines. It edits the inventory and runs the SEAPATH playbooks. SEAPATH is a function converting an inventory into a running infrastructure, and this service is a friendly front end onto that function, not a way around it. The fourth machine disappears as a machine, not as a function: its two jobs, holding the desired state and running the playbooks, move into the cluster itself.
Concretely, the service does four things:
- holds the inventory in a git repository replicated across the nodes, and edits it through guided forms seeded by hardware discovery;
- brokers SSH trust between nodes, bootstrapped by a manual secret exchange in the Proxmox style, so any node can drive the others;
- runs the upstream playbooks with
ansible-runnerand turns their event stream into a readable progress view; - exposes the runtime plane, meaning starting, stopping and migrating VMs, which is not configuration and does not belong in an inventory.
No SEAPATH role is rewritten, and no configuration file is rendered twice. What the UI runs is what the CI tests.
M1, pending validation on real hardware. A machine installed from the ISO
provisions its own SSH trust, describes itself into a git inventory, and is
configured from a browser with no Ansible control machine anywhere: guided
forms edit the inventory, and the upstream playbooks are run with
ansible-runner from the collection built into the image.
M0 before it: skeleton, PAM authentication with sessions and CSRF, TLS
material generated at first boot, the read only node view and its API, the
image, the quadlet and the test harness. The node view describes what the
machine is, not what it is doing: live state stays with
prometheus-node-exporter, which every SEAPATH node runs.
M2, next, is the VM runtime plane through vm_manager.
python3.11 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
.venv/bin/pytestThe suite runs on a laptop with no cluster, no libvirt and no container, which
is a property worth keeping: everything that touches a host goes through an
adapter that has a fake. To browse the UI without a SEAPATH machine, set
SEAPATH_WEBUI_USE_FAKES=1, which serves invented readings and says so in the
log.
- SPEC.md - principle, scope, architecture, milestones, risks.
- docs/inventory.md - the desired state: storage, writers, discovery, and the form to variable mapping. The heart of the product.
- docs/cluster-join.md - trust between nodes and cluster formation.
- docs/playbooks.md - which playbooks the UI exposes, and what to warn about before each one.
- docs/api.md - REST API surface.
- docs/ceph.md - the Ceph flow, which is mostly a disk selector and a playbook.
- docs/deployment.md - image, quadlet, Ansible role, ISO.
- docs/decisions.md - settled decisions with their reasoning, and the open ones with a recommendation.
- docs/validation.md - what has to be checked on a real machine, per milestone, because the test suite deliberately cannot.
- AGENTS.md - conventions and definition of done.
| Component | Repository | Relation |
|---|---|---|
seapath-ansible |
~/dev/seapath-ansible |
The collection this service ships and runs. Roles are used unchanged. |
vm_manager |
~/dev/vm_manager |
Python library for the runtime plane. Consumed, not reimplemented. |
vmmgrapi role |
seapath-ansible/roles/vmmgrapi |
The existing thin API over vm_manager. Deprecated at M5. |
rtperfui |
~/dev/rtperfui |
Packaging precedent: FastAPI, Jinja, quadlet with host mounts. |
insatomcat-exporter |
~/dev/insatomcat-exporter |
Precedent for the image build and publish flow. |