141 lines
6.1 KiB
Markdown
141 lines
6.1 KiB
Markdown
# Harmony
|
||
|
||
Open-source infrastructure orchestration that treats your platform like first-class code.
|
||
|
||
_By [NationTech](https://nationtech.io)_
|
||
|
||
[](https://git.nationtech.io/nationtech/harmony)
|
||
[](LICENSE)
|
||
|
||
### 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.**
|
||
|
||
## 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.
|
||
|
||
## Where to Start
|
||
|
||
We have a comprehensive set of documentation right here in the repository.
|
||
|
||
| I want to... | Start Here |
|
||
| ----------------- | ------------------------------------------------------------------ |
|
||
| Get Started | [Getting Started Guide](./docs/guides/getting-started.md) |
|
||
| See an Example | [Use Case: Deploy a Rust Web App](./docs/use-cases/rust-webapp.md) |
|
||
| Explore | [Documentation Hub](./docs/README.md) |
|
||
| See Core Concepts | [Core Concepts Explained](./docs/concepts.md) |
|
||
|
||
## Quick Look: Deploy a Rust Webapp
|
||
|
||
The snippet below spins up a complete **production-grade Rust + Leptos Webapp** with monitoring. Swap it for your own scores to deploy anything from microservices to machine-learning pipelines.
|
||
|
||
```rust
|
||
use harmony::{
|
||
inventory::Inventory,
|
||
modules::{
|
||
application::{
|
||
ApplicationScore, RustWebFramework, RustWebapp,
|
||
features::{PackagingDeployment, rhob_monitoring::Monitoring},
|
||
},
|
||
monitoring::alert_channel::discord_alert_channel::DiscordWebhook,
|
||
},
|
||
topology::K8sAnywhereTopology,
|
||
};
|
||
use harmony_macros::hurl;
|
||
use std::{path::PathBuf, sync::Arc};
|
||
|
||
#[tokio::main]
|
||
async fn main() {
|
||
let application = Arc::new(RustWebapp {
|
||
name: "harmony-example-leptos".to_string(),
|
||
project_root: PathBuf::from(".."), // <== Your project root, usually .. if you use the standard `/harmony` folder
|
||
framework: Some(RustWebFramework::Leptos),
|
||
service_port: 8080,
|
||
});
|
||
|
||
// Define your Application deployment and the features you want
|
||
let app = ApplicationScore {
|
||
features: vec![
|
||
Box::new(PackagingDeployment {
|
||
application: application.clone(),
|
||
}),
|
||
Box::new(Monitoring {
|
||
application: application.clone(),
|
||
alert_receiver: vec![
|
||
Box::new(DiscordWebhook {
|
||
name: "test-discord".to_string(),
|
||
url: hurl!("https://discord.doesnt.exist.com"), // <== Get your discord webhook url
|
||
}),
|
||
],
|
||
}),
|
||
],
|
||
application,
|
||
};
|
||
|
||
harmony_cli::run(
|
||
Inventory::autoload(),
|
||
K8sAnywhereTopology::from_env(), // <== Deploy to local automatically provisioned local k3d by default or connect to any kubernetes cluster
|
||
vec![Box::new(app)],
|
||
None,
|
||
)
|
||
.await
|
||
.unwrap();
|
||
}
|
||
```
|
||
|
||
To run this:
|
||
|
||
- Clone the repository: `git clone https://git.nationtech.io/nationtech/harmony`
|
||
- Install dependencies: `cargo build --release`
|
||
- Run the example: `cargo run --example try_rust_webapp`
|
||
|
||
## Documentation
|
||
|
||
All documentation is in the `/docs` directory.
|
||
|
||
- [Documentation Hub](./docs/README.md): The main entry point for all documentation.
|
||
- [Core Concepts](./docs/concepts.md): A detailed look at Score, Topology, Capability, Inventory, and Interpret.
|
||
- [Component Catalogs](./docs/catalogs/README.md): Discover all available Scores, Topologies, and Capabilities.
|
||
- [Developer Guide](./docs/guides/developer-guide.md): Learn how to write your own Scores and Topologies.
|
||
|
||
## Architectural Decision Records
|
||
|
||
- [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)
|
||
|
||
## Contribute
|
||
|
||
Discussions and roadmap live in [Issues](https://git.nationtech.io/nationtech/harmony/-/issues). PRs, ideas, and feedback are welcome!
|
||
|
||
## 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_
|