Jean-Gabriel Gill-Couture
064fa1da0d
Two design documents framing the next push. `ROADMAP/fleet_platform/v0_2_plan.md` — three-day production push. Replaces the open-ended chapter structure of v0_1_plan.md for the period between the walking-skeleton merge and v0.1.0 in production. Focus is locking the fleet module's public API surface so the inevitable physical refactor (out of `harmony/modules/fleet/`, into `fleet/harmony-fleet/`) is mechanical when we get to it. Anchored in the principle from JG's *Pour l'amour des compilateurs* talk: design the brick before moving the brick. `docs/adr/022-fleet-agent-upgrade.md` — agent upgrade procedure. K8s rolling-update shape applied to one host: drain in-flight work, stage versioned binary alongside old, smoke-test, atomic symlink swap, both agents alive briefly, operator verifies new agent's heartbeat then sends explicit stop signal to old, old exits cleanly. No version is ever erased — N-history on disk is the rollback target. Operator-driven cutover (not self-stopping) so the most-trusted side decides the handoff. Implementation deferred to post-v0.1 backlog; spec exists so anyone can build it without reinventing the design. ADR README index updated.
Harmony Documentation Hub
Welcome to the Harmony documentation. This is the main entry point for learning everything from core concepts to building your own Score, Topologies, and Capabilities.
1. Getting Started
If you're new to Harmony, start here:
- Getting Started Guide: A step-by-step tutorial that takes you from an empty project to deploying your first application.
- Core Concepts: A high-level overview of the key concepts in Harmony:
Score,Topology,Capability,Inventory,Interpret, ...
2. Use Cases & Examples
See how to use Harmony to solve real-world problems.
- OPNsense VM Integration: Boot a real OPNsense firewall in a local KVM VM and configure it entirely through Harmony. Fully automated, zero manual steps — the flashiest demo. Requires Linux with KVM.
- PostgreSQL on Local K3D: Deploy a production-grade PostgreSQL cluster on a local K3D cluster. The fastest way to get started.
- OKD on Bare Metal: A detailed walkthrough of bootstrapping a high-availability OKD cluster from physical hardware.
3. Component Catalogs
Discover existing, reusable components you can use in your Harmony projects.
- Scores Catalog: A categorized list of all available
Scores(the "what"). - Topologies Catalog: A list of all available
Topologies(the "where"). - Capabilities Catalog: A list of all available
Capabilities(the "how").
4. Developer Guides
Ready to build your own components? These guides show you how.
- Writing a Score: Learn how to create your own
ScoreandInterpretlogic to define a new desired state. - Writing a Topology: Learn how to model a new environment (like AWS, GCP, or custom hardware) as a
Topology. - Adding Capabilities: See how to add a
Capabilityto your customTopology.
5. Architecture Decision Records
Harmony's design is documented through Architecture Decision Records (ADRs). See the ADR Overview for a complete index of all decisions.