Jean-Gabriel Gill-Couture
86c681be70
All checks were successful
Run Check Script / check (push) Successful in 1m52s
Reviewed-on: https://git.nationtech.io/NationTech/harmony/pulls/59 Co-authored-by: Jean-Gabriel Gill-Couture <jg@nationtech.io> Co-committed-by: Jean-Gabriel Gill-Couture <jg@nationtech.io>
142 lines
5.4 KiB
Markdown
142 lines
5.4 KiB
Markdown
# Harmony
|
||
|
||
[](https://git.nationtech.io/nationtech/harmony)
|
||
[](LICENSE)
|
||
|
||
**Open-source infrastructure orchestration that treats your platform like first-class code.**
|
||
|
||
Harmony unifies project scaffolding, infrastructure provisioning, application deployment, and day-2 operations in **one strongly-typed Rust codebase**. From a developer laptop to a global production cluster, a single source of truth drives the full software lifecycle.
|
||
|
||
---
|
||
|
||
## 1 · The Harmony Philosophy
|
||
|
||
Infrastructure is essential, but it shouldn’t be your core business. Harmony is built on three guiding principles that make modern platforms reliable, repeatable, and easy to reason about.
|
||
|
||
| Principle | What it means for you |
|
||
|-----------|-----------------------|
|
||
| **Infrastructure as Resilient Code** | Replace sprawling YAML and bash scripts with type-safe Rust. Test, refactor, and version your platform just like application code. |
|
||
| **Prove It Works — Before You Deploy** | Harmony uses the compiler to verify that your application’s needs match the target environment’s capabilities at **compile-time**, eliminating an entire class of runtime outages. |
|
||
| **One Unified Model** | Software and infrastructure are a single system. Harmony models them together, enabling deep automation—from bare-metal servers to Kubernetes workloads—with zero context switching. |
|
||
|
||
These principles surface as simple, ergonomic Rust APIs that let teams focus on their product while trusting the platform underneath.
|
||
|
||
---
|
||
|
||
## 2 · Quick Start
|
||
|
||
The snippet below spins up a complete **production-grade LAMP stack** with monitoring. Swap it for your own scores to deploy anything from microservices to machine-learning pipelines.
|
||
|
||
```rust
|
||
use harmony::{
|
||
data::Version,
|
||
inventory::Inventory,
|
||
maestro::Maestro,
|
||
modules::{
|
||
lamp::{LAMPConfig, LAMPScore},
|
||
monitoring::monitoring_alerting::MonitoringAlertingStackScore,
|
||
},
|
||
topology::{K8sAnywhereTopology, Url},
|
||
};
|
||
|
||
#[tokio::main]
|
||
async fn main() {
|
||
// 1. Describe what you want
|
||
let lamp_stack = LAMPScore {
|
||
name: "harmony-lamp-demo".into(),
|
||
domain: Url::Url(url::Url::parse("https://lampdemo.example.com").unwrap()),
|
||
php_version: Version::from("8.3.0").unwrap(),
|
||
config: LAMPConfig {
|
||
project_root: "./php".into(),
|
||
database_size: "4Gi".into(),
|
||
..Default::default()
|
||
},
|
||
};
|
||
|
||
// 2. Pick where it should run
|
||
let mut maestro = Maestro::<K8sAnywhereTopology>::initialize(
|
||
Inventory::autoload(), // auto-detect hardware / kube-config
|
||
K8sAnywhereTopology::from_env(), // local k3d, CI, staging, prod…
|
||
)
|
||
.await
|
||
.unwrap();
|
||
|
||
// 3. Enhance with extra scores (monitoring, CI/CD, …)
|
||
let mut monitoring = MonitoringAlertingStackScore::new();
|
||
monitoring.namespace = Some(lamp_stack.config.namespace.clone());
|
||
|
||
maestro.register_all(vec![Box::new(lamp_stack), Box::new(monitoring)]);
|
||
|
||
// 4. Launch an interactive CLI / TUI
|
||
harmony_cli::init(maestro, None).await.unwrap();
|
||
}
|
||
```
|
||
|
||
Run it:
|
||
|
||
```bash
|
||
cargo run
|
||
```
|
||
|
||
Harmony analyses the code, shows an execution plan in a TUI, and applies it once you confirm. Same code, same binary—every environment.
|
||
|
||
---
|
||
|
||
## 3 · Core Concepts
|
||
|
||
| Term | One-liner |
|
||
|------|-----------|
|
||
| **Score<T>** | Declarative description of the desired state (e.g., `LAMPScore`). |
|
||
| **Interpret<T>** | Imperative logic that realises a `Score` on a specific environment. |
|
||
| **Topology** | An environment (local k3d, AWS, bare-metal) exposing verified *Capabilities* (Kubernetes, DNS, …). |
|
||
| **Maestro** | Orchestrator that compiles Scores + Topology, ensuring all capabilities line up **at compile-time**. |
|
||
| **Inventory** | Optional catalogue of physical assets for bare-metal and edge deployments. |
|
||
|
||
A visual overview is in the diagram below.
|
||
|
||
[Harmony Core Architecture](docs/diagrams/Harmony_Core_Architecture.drawio.svg)
|
||
|
||
---
|
||
|
||
## 4 · Install
|
||
|
||
Prerequisites:
|
||
|
||
* Rust
|
||
* Docker (if you deploy locally)
|
||
* `kubectl` / `helm` for Kubernetes-based topologies
|
||
|
||
```bash
|
||
git clone https://git.nationtech.io/nationtech/harmony
|
||
cd harmony
|
||
cargo build --release # builds the CLI, TUI and libraries
|
||
```
|
||
|
||
---
|
||
|
||
## 5 · Learning More
|
||
|
||
* **Architectural Decision Records** – dive into the rationale
|
||
- [ADR-001 · Why Rust](adr/001-rust.md)
|
||
- [ADR-003 · Infrastructure Abstractions](adr/003-infrastructure-abstractions.md)
|
||
- [ADR-006 · Secret Management](adr/006-secret-management.md)
|
||
- [ADR-011 · Multi-Tenant Cluster](adr/011-multi-tenant-cluster.md)
|
||
|
||
* **Extending Harmony** – write new Scores / Interprets, add hardware like OPNsense firewalls, or embed Harmony in your own tooling (`/docs`).
|
||
|
||
* **Community** – discussions and roadmap live in [GitLab issues](https://git.nationtech.io/nationtech/harmony/-/issues). PRs, ideas, and feedback are welcome!
|
||
|
||
---
|
||
|
||
## 6 · License
|
||
|
||
Harmony is released under the **GNU AGPL v3**.
|
||
|
||
> We choose a strong copyleft license to ensure the project—and every improvement to it—remains open and benefits the entire community. Fork it, enhance it, even out-innovate us; just keep it open.
|
||
|
||
See [LICENSE](LICENSE) for the full text.
|
||
|
||
---
|
||
|
||
*Made with ❤️ & 🦀 by the NationTech and the Harmony community*
|