harmony/README.md

Harmony : Open-source infrastructure orchestration that treats your platform like first-class code.

By NationTech

Unify

• Project Scaffolding
• Infrastructure Provisioning
• Application Deployment
• Day-2 operations

All in one strongly-typed Rust codebase.

Deploy anywhere

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.

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:

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	Declarative description of the desired state (e.g., LAMPScore).
Interpret	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

---

4 · Install

Prerequisites:

• Rust
• Docker (if you deploy locally)
• kubectl / helm for Kubernetes-based topologies

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-003 · Infrastructure Abstractions
  • ADR-006 · Secret Management
  • ADR-011 · Multi-Tenant Cluster

• 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. 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 for the full text.

---

Made with ❤️ & 🦀 by the NationTech and the Harmony community