fix: Support multiple mac address on static host binding

Reviewed-on: #125

.dockerignore

@@ -0,0 +1,2 @@
+target/
+Dockerfile

.gitattributes

@@ -2,3 +2,5 @@ bootx64.efi filter=lfs diff=lfs merge=lfs -text
 grubx64.efi filter=lfs diff=lfs merge=lfs -text
 initrd filter=lfs diff=lfs merge=lfs -text
 linux filter=lfs diff=lfs merge=lfs -text
+data/okd/bin/* filter=lfs diff=lfs merge=lfs -text
+data/okd/installer_image/* filter=lfs diff=lfs merge=lfs -text

.gitea/workflows/check.yml

@@ -1,11 +1,15 @@
 name: Run Check Script
 on:
   push:
+    branches:
+      - master
   pull_request:
 
 jobs:
   check:
-    runs-on: rust-cargo
+    runs-on: docker
+    container:
+      image: hub.nationtech.io/harmony/harmony_composer:latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

.gitea/workflows/harmony_composer.yaml

@@ -0,0 +1,95 @@
+name: Compile and package harmony_composer
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  package_harmony_composer:
+    container:
+      image: hub.nationtech.io/harmony/harmony_composer:latest
+    runs-on: dind
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build for Linux x86_64
+        run: cargo build --release --bin harmony_composer --target x86_64-unknown-linux-gnu
+
+      - name: Build for Windows x86_64 GNU
+        run: cargo build --release --bin harmony_composer --target x86_64-pc-windows-gnu
+
+      - name: Setup log into hub.nationtech.io
+        uses: docker/login-action@v3
+        with:
+          registry: hub.nationtech.io
+          username: ${{ secrets.HUB_BOT_USER }}
+          password: ${{ secrets.HUB_BOT_PASSWORD }}
+
+      # TODO: build ARM images and MacOS binaries (or other targets) too
+
+      - name: Update snapshot-latest tag
+        run: |
+          git config user.name "Gitea CI"
+          git config user.email "ci@nationtech.io"
+          git tag -f snapshot-latest
+          git push origin snapshot-latest --force
+
+      - name: Install jq
+        run: apt install -y jq # The current image includes apt lists so we don't have to apt update and rm /var/lib/apt... every time. But if the image is optimized it won't work anymore
+
+      - name: Create or update release
+        run: |
+          # First, check if release exists and delete it if it does
+          RELEASE_ID=$(curl -s -X GET \
+            -H "Authorization: token ${{ secrets.GITEATOKEN }}" \
+            "https://git.nationtech.io/api/v1/repos/nationtech/harmony/releases/tags/snapshot-latest" \
+            | jq -r '.id // empty')
+
+          if [ -n "$RELEASE_ID" ]; then
+            # Delete existing release
+            curl -X DELETE \
+              -H "Authorization: token ${{ secrets.GITEATOKEN }}" \
+              "https://git.nationtech.io/api/v1/repos/nationtech/harmony/releases/$RELEASE_ID"
+          fi
+
+          # Create new release
+          RESPONSE=$(curl -X POST \
+            -H "Authorization: token ${{ secrets.GITEATOKEN }}" \
+            -H "Content-Type: application/json" \
+            -d '{
+              "tag_name": "snapshot-latest",
+              "name": "Latest Snapshot",
+              "body": "Automated snapshot build from master branch",
+              "draft": false,
+              "prerelease": true
+            }' \
+            "https://git.nationtech.io/api/v1/repos/nationtech/harmony/releases")
+
+          echo "RELEASE_ID=$(echo $RESPONSE | jq -r '.id')" >> $GITHUB_ENV
+
+      - name: Upload Linux binary
+        run: |
+          curl -X POST \
+            -H "Authorization: token ${{ secrets.GITEATOKEN }}" \
+            -H "Content-Type: application/octet-stream" \
+            --data-binary "@target/x86_64-unknown-linux-gnu/release/harmony_composer" \
+            "https://git.nationtech.io/api/v1/repos/nationtech/harmony/releases/${{ env.RELEASE_ID }}/assets?name=harmony_composer"
+
+      - name: Upload Windows binary
+        run: |
+          curl -X POST \
+            -H "Authorization: token ${{ secrets.GITEATOKEN }}" \
+            -H "Content-Type: application/octet-stream" \
+            --data-binary "@target/x86_64-pc-windows-gnu/release/harmony_composer.exe" \
+            "https://git.nationtech.io/api/v1/repos/nationtech/harmony/releases/${{ env.RELEASE_ID }}/assets?name=harmony_composer.exe"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: hub.nationtech.io/harmony/harmony_composer:latest

.gitignore

@@ -1,3 +1,25 @@
-target
-private_repos
-log/
+### General ###
+private_repos/
+
+### Harmony ###
+harmony.log
+
+### Helm ###
+# Chart dependencies
+**/charts/*.tgz
+
+### Rust ###
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb

.sqlx/query-2ea29df2326f7c84bd4100ad510a3fd4878dc2e217dc83f9bf45a402dfd62a91.json

@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT host_id FROM host_role_mapping WHERE role = ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "host_id",
+        "ordinal": 0,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "2ea29df2326f7c84bd4100ad510a3fd4878dc2e217dc83f9bf45a402dfd62a91"
+}

.sqlx/query-8d247918eca10a88b784ee353db090c94a222115c543231f2140cba27bd0f067.json

@@ -0,0 +1,32 @@
+{
+  "db_name": "SQLite",
+  "query": "\n        SELECT\n            p1.id,\n            p1.version_id,\n            p1.data as \"data: Json<PhysicalHost>\"\n        FROM\n            physical_hosts p1\n        INNER JOIN (\n            SELECT\n                id,\n                MAX(version_id) AS max_version\n            FROM\n                physical_hosts\n            GROUP BY\n                id\n        ) p2 ON p1.id = p2.id AND p1.version_id = p2.max_version\n        ",
+  "describe": {
+    "columns": [
+      {
+        "name": "id",
+        "ordinal": 0,
+        "type_info": "Text"
+      },
+      {
+        "name": "version_id",
+        "ordinal": 1,
+        "type_info": "Text"
+      },
+      {
+        "name": "data: Json<PhysicalHost>",
+        "ordinal": 2,
+        "type_info": "Blob"
+      }
+    ],
+    "parameters": {
+      "Right": 0
+    },
+    "nullable": [
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "8d247918eca10a88b784ee353db090c94a222115c543231f2140cba27bd0f067"
+}

.sqlx/query-934035c7ca6e064815393e4e049a7934b0a7fac04a4fe4b2a354f0443d630990.json

@@ -0,0 +1,32 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT id, version_id, data as \"data: Json<PhysicalHost>\" FROM physical_hosts WHERE id = ? ORDER BY version_id DESC LIMIT 1",
+  "describe": {
+    "columns": [
+      {
+        "name": "id",
+        "ordinal": 0,
+        "type_info": "Text"
+      },
+      {
+        "name": "version_id",
+        "ordinal": 1,
+        "type_info": "Text"
+      },
+      {
+        "name": "data: Json<PhysicalHost>",
+        "ordinal": 2,
+        "type_info": "Null"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "934035c7ca6e064815393e4e049a7934b0a7fac04a4fe4b2a354f0443d630990"
+}

.sqlx/query-df7a7c9cfdd0972e2e0ce7ea444ba8bc9d708a4fb89d5593a0be2bbebde62aff.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "\n        INSERT INTO host_role_mapping (host_id, role)\n        VALUES (?, ?)\n        ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": []
+  },
+  "hash": "df7a7c9cfdd0972e2e0ce7ea444ba8bc9d708a4fb89d5593a0be2bbebde62aff"
+}

.sqlx/query-f10f615ee42129ffa293e46f2f893d65a237d31d24b74a29c6a8d8420d255ab8.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT INTO physical_hosts (id, version_id, data) VALUES (?, ?, ?)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "f10f615ee42129ffa293e46f2f893d65a237d31d24b74a29c6a8d8420d255ab8"
+}

Cargo.toml

@@ -11,6 +11,10 @@ members = [
   "opnsense-config-xml",
   "harmony_cli",
   "k3d",
+  "harmony_composer",
+  "harmony_inventory_agent",
+  "harmony_secret_derive",
+  "harmony_secret", "adr/agent_discovery/mdns",
 ]
 
 [workspace.package]
@@ -19,28 +23,48 @@ readme = "README.md"
 license = "GNU AGPL v3"
 
 [workspace.dependencies]
-log = "0.4.22"
-env_logger = "0.11.5"
-derive-new = "0.7.0"
-async-trait = "0.1.82"
-tokio = { version = "1.40.0", features = ["io-std", "fs", "macros", "rt-multi-thread"] }
-cidr = "0.2.3"
-russh = "0.45.0"
-russh-keys = "0.45.0"
-rand = "0.8.5"
-url = "2.5.4"
-kube = "0.98.0"
-k8s-openapi = { version = "0.24.0", features = ["v1_30"] }
-serde_yaml = "0.9.34"
-serde-value = "0.7.0"
-http = "1.2.0"
-inquire = "0.7.5"
-convert_case =  "0.8.0"
-
-[workspace.dependencies.uuid]
-version = "1.11.0"
-features = [
-  "v4",                # Lets you generate random UUIDs
-  "fast-rng",          # Use a faster (but still sufficiently random) RNG
-  "macro-diagnostics", # Enable better diagnostics for compile-time UUIDs
-]
+log = { version = "0.4", features = ["kv"] }
+env_logger = "0.11"
+derive-new = "0.7"
+async-trait = "0.1"
+tokio = { version = "1.40", features = [
+  "io-std",
+  "fs",
+  "macros",
+  "rt-multi-thread",
+] }
+cidr = { features = ["serde"], version = "0.2" }
+russh = "0.45"
+russh-keys = "0.45"
+rand = "0.9"
+url = "2.5"
+kube = { version = "1.1.0", features = [
+  "config",
+  "client",
+  "runtime",
+  "rustls-tls",
+  "ws",
+  "jsonpatch",
+] }
+k8s-openapi = { version = "0.25", features = ["v1_30"] }
+serde_yaml = "0.9"
+serde-value = "0.7"
+http = "1.2"
+inquire = "0.7"
+convert_case = "0.8"
+chrono = "0.4"
+similar = "2"
+uuid = { version = "1.11", features = ["v4", "fast-rng", "macro-diagnostics"] }
+pretty_assertions = "1.4.1"
+tempfile = "3.20.0"
+bollard = "0.19.1"
+base64 = "0.22.1"
+tar = "0.4.44"
+lazy_static = "1.5.0"
+directories = "6.0.0"
+thiserror = "2.0.14"
+serde = { version = "1.0.209", features = ["derive", "rc"] }
+serde_json = "1.0.127"
+askama = "0.14"
+sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite" ] }
+reqwest = { version = "0.12", features = ["blocking", "stream", "rustls-tls", "http2", "json"], default-features = false }

Dockerfile

@@ -0,0 +1,26 @@
+FROM docker.io/rust:1.89.0 AS build
+
+WORKDIR /app
+
+COPY . .
+
+RUN cargo build --release --bin harmony_composer
+
+FROM docker.io/rust:1.89.0
+
+WORKDIR /app
+
+RUN rustup target add x86_64-pc-windows-gnu
+RUN rustup target add x86_64-unknown-linux-gnu
+RUN rustup component add rustfmt
+RUN rustup component add clippy
+
+RUN apt update
+
+# TODO: Consider adding more supported targets
+# nodejs for checkout action, docker for building containers, mingw for cross-compiling for windows
+RUN apt install -y nodejs docker.io mingw-w64
+
+COPY --from=build /app/target/release/harmony_composer .
+
+ENTRYPOINT ["/app/harmony_composer"]

README.md

@@ -1,171 +1,150 @@
-# Harmony : Open Infrastructure Orchestration
+# Harmony : Open-source infrastructure orchestration that treats your platform like first-class code
 
-## Quick demo
+_By [NationTech](https://nationtech.io)_
 
-`cargo run -p example-tui`
+[![Build](https://git.nationtech.io/NationTech/harmony/actions/workflows/check.yml/badge.svg)](https://git.nationtech.io/nationtech/harmony)
+[![License](https://img.shields.io/badge/license-AGPLv3-blue?style=flat-square)](LICENSE)
 
-This will launch Harmony's minimalist terminal ui which embeds a few demo scores.
+### Unify
 
-Usage instructions will be displayed at the bottom of the TUI.
+- **Project Scaffolding**
+- **Infrastructure Provisioning**
+- **Application Deployment**
+- **Day-2 operations**
 
-`cargo run --bin example-cli -- --help`
+All in **one strongly-typed Rust codebase**.
 
-This is the harmony CLI, a minimal implementation
+### Deploy anywhere
 
-The current help text:
+From a **developer laptop** to a **global production cluster**, a single **source of truth** drives the **full software lifecycle.**
 
-````
-Usage: example-cli [OPTIONS]
+---
 
-Options:
-  -y, --yes              Run score(s) or not
-  -f, --filter <FILTER>  Filter query
-  -i, --interactive      Run interactive TUI or not
-  -a, --all              Run all or nth, defaults to all
-  -n, --number <NUMBER>  Run nth matching, zero indexed [default: 0]
-  -l, --list             list scores, will also be affected by run filter
-  -h, --help             Print help
-  -V, --version          Print version```
+## 1 · The Harmony Philosophy
 
-## Core architecture
+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.
 
-![Harmony Core Architecture](docs/diagrams/Harmony_Core_Architecture.drawio.svg)
-````
-## Supporting a new field in OPNSense `config.xml`
+| 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. |
 
-Two steps:
-- Supporting the field in `opnsense-config-xml`
-- Enabling Harmony to control the field
+These principles surface as simple, ergonomic Rust APIs that let teams focus on their product while trusting the platform underneath.
 
-We'll use the `filename` field in the `dhcpcd` section of the file as an example.
+---
 
-### Supporting the field
+## 2 · Quick Start
 
-As type checking if enforced, every field from `config.xml` must be known by the code. Each subsection of `config.xml` has its `.rs` file. For the `dhcpcd` section, we'll modify `opnsense-config-xml/src/data/dhcpd.rs`.
+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.
 
-When a new field appears in the xml file, an error like this will be thrown and Harmony will panic :
-```
-     Running `/home/stremblay/nt/dir/harmony/target/debug/example-nanodc`
-Found unauthorized element filename
-thread 'main' panicked at opnsense-config-xml/src/data/opnsense.rs:54:14:
-OPNSense received invalid string, should be full XML: ()
+```rust
+use harmony::{
+    data::Version,
+    inventory::Inventory,
+    maestro::Maestro,
+    modules::{
+        lamp::{LAMPConfig, LAMPScore},
+        monitoring::monitoring_alerting::MonitoringAlertingStackScore,
+    },
+    topology::{K8sAnywhereTopology, Url},
+};
 
-```
-
-Define the missing field (`filename`) in the `DhcpInterface` struct of `opnsense-config-xml/src/data/dhcpd.rs`:
-```
-pub struct DhcpInterface {
-    ...
-    pub filename: Option<String>,
-```
-
-Harmony should now be fixed, build and run.
-
-### Controlling the field
-
-Define the `xml field setter` in `opnsense-config/src/modules/dhcpd.rs`.
-```
-impl<'a> DhcpConfig<'a> {
-    ...
-    pub fn set_filename(&mut self, filename: &str) {
-        self.enable_netboot();
-        self.get_lan_dhcpd().filename = Some(filename.to_string());
-    }
-    ...
-```
-
-Define the `value setter` in the `DhcpServer trait`  in `domain/topology/network.rs`
-```
-#[async_trait]
-pub trait DhcpServer: Send + Sync {
-    ...
-    async fn set_filename(&self, filename: &str) -> Result<(), ExecutorError>;
-    ...
-```
-
-Implement the `value setter` in each `DhcpServer` implementation.
-`infra/opnsense/dhcp.rs`:
-```
-#[async_trait]
-impl DhcpServer for OPNSenseFirewall {
-    ...
-    async fn set_filename(&self, filename: &str) -> Result<(), ExecutorError> {
-        {
-            let mut writable_opnsense = self.opnsense_config.write().await;
-            writable_opnsense.dhcp().set_filename(filename);
-            debug!("OPNsense dhcp server set filename {filename}");
-        }
-
-        Ok(())
-    }
-    ...
-```
-
-`domain/topology/ha_cluster.rs`
-```
-#[async_trait]
-impl DhcpServer for DummyInfra {
-    ...
-    async fn set_filename(&self, _filename: &str) -> Result<(), ExecutorError> {
-        unimplemented!("{}", UNIMPLEMENTED_DUMMY_INFRA)
-    }
-    ...
-```
-
-Add the new field to the DhcpScore in `modules/dhcp.rs`
-```
-pub struct DhcpScore {
-    ...
-    pub filename: Option<String>,
-```
-
-Define it in its implementation in `modules/okd/dhcp.rs`
-```
-impl OKDDhcpScore {
-        ...
-        Self {
-            dhcp_score: DhcpScore {
-                ...
-                filename: Some("undionly.kpxe".to_string()),
-```
-
-Define it in its implementation in `modules/okd/bootstrap_dhcp.rs`
-```
-impl OKDDhcpScore {
-        ...
-        Self {
-            dhcp_score: DhcpScore::new(
-                ...
-                Some("undionly.kpxe".to_string()),
-```
-
-Update the interpret (function called by the `execute` fn of the interpret) so it now updates the `filename` field value in `modules/dhcp.rs`
-```
-impl DhcpInterpret {
-        ...
-        let filename_outcome = match &self.score.filename {
-            Some(filename) => {
-                let dhcp_server = Arc::new(topology.dhcp_server.clone());
-                dhcp_server.set_filename(&filename).await?;
-                Outcome::new(
-                    InterpretStatus::SUCCESS,
-                    format!("Dhcp Interpret Set filename to {filename}"),
-                )
-            }
-            None => Outcome::noop(),
+#[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()
+        },
     };
 
-        if next_server_outcome.status == InterpretStatus::NOOP
-            && boot_filename_outcome.status == InterpretStatus::NOOP
-            && filename_outcome.status == InterpretStatus::NOOP
+    // 2. Enhance with extra scores (monitoring, CI/CD, …)
+    let mut monitoring = MonitoringAlertingStackScore::new();
+    monitoring.namespace = Some(lamp_stack.config.namespace.clone());
 
-            ...
-
-            Ok(Outcome::new(
-            InterpretStatus::SUCCESS,
-            format!(
-                "Dhcp Interpret Set next boot to [{:?}], boot_filename to [{:?}], filename to [{:?}]",
-                self.score.boot_filename, self.score.boot_filename, self.score.filename
-            )
-            ...
+    // 3. Run your scores on the desired topology & inventory
+    harmony_cli::run(
+        Inventory::autoload(),                // auto-detect hardware / kube-config
+        K8sAnywhereTopology::from_env(),      // local k3d, CI, staging, prod…
+        vec![
+          Box::new(lamp_stack),
+          Box::new(monitoring)
+        ],
+        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_

adr/010-monitoring-alerting/architecture.rs

@@ -0,0 +1,73 @@
+pub trait MonitoringSystem {}
+
+// 1. Modified AlertReceiver trait:
+//    - Removed the problematic `clone` method.
+//    - Added `box_clone` which returns a Box<dyn AlertReceiver>.
+pub trait AlertReceiver {
+    type M: MonitoringSystem;
+    fn install(&self, sender: &Self::M) -> Result<(), String>;
+    // This method allows concrete types to clone themselves into a Box<dyn AlertReceiver>
+    fn box_clone(&self) -> Box<dyn AlertReceiver<M = Self::M>>;
+}
+#[derive(Clone)]
+struct Prometheus{}
+impl MonitoringSystem for Prometheus {}
+
+#[derive(Clone)] // Keep derive(Clone) for DiscordWebhook itself
+struct DiscordWebhook{}
+
+impl AlertReceiver for DiscordWebhook {
+    type M = Prometheus;
+    fn install(&self, sender: &Self::M) -> Result<(), String> {
+        // Placeholder for actual installation logic
+        println!("DiscordWebhook installed for Prometheus monitoring.");
+        Ok(())
+    }
+    // 2. Implement `box_clone` for DiscordWebhook:
+    //    This uses the derived `Clone` for DiscordWebhook to create a new boxed instance.
+    fn box_clone(&self) -> Box<dyn AlertReceiver<M = Self::M>> {
+        Box::new(self.clone())
+    }
+}
+
+// 3. Implement `std::clone::Clone` for `Box<dyn AlertReceiver<M= M>>`:
+//    This allows `Box<dyn AlertReceiver>` to be cloned.
+//    The `+ 'static` lifetime bound is often necessary for trait objects stored in collections,
+//    ensuring they live long enough.
+impl<M: MonitoringSystem + 'static> Clone for Box<dyn AlertReceiver<M= M>> {
+    fn clone(&self) -> Self {
+        self.box_clone() // Call the custom `box_clone` method
+    }
+}
+
+// MonitoringConfig can now derive Clone because its `receivers` field
+// (Vec<Box<dyn AlertReceiver<M = M>>>) is now cloneable.
+#[derive(Clone)]
+struct MonitoringConfig <M: MonitoringSystem + 'static>{
+    receivers: Vec<Box<dyn AlertReceiver<M = M>>>
+}
+
+// Example usage to demonstrate compilation and functionality
+fn main() {
+    let prometheus_instance = Prometheus{};
+    let discord_webhook_instance = DiscordWebhook{};
+
+    let mut config = MonitoringConfig {
+        receivers: Vec::new()
+    };
+
+    // Create a boxed alert receiver
+    let boxed_receiver: Box<dyn AlertReceiver<M = Prometheus>> = Box::new(discord_webhook_instance);
+    config.receivers.push(boxed_receiver);
+
+    // Clone the config, which will now correctly clone the boxed receiver
+    let cloned_config = config.clone();
+
+    println!("Original config has {} receivers.", config.receivers.len());
+    println!("Cloned config has {} receivers.", cloned_config.receivers.len());
+
+    // Example of using the installed receiver
+    if let Some(receiver) = config.receivers.get(0) {
+        let _ = receiver.install(&prometheus_instance);
+    }
+}

adr/012-project-delivery-automation.md

@@ -0,0 +1,63 @@
+# Architecture Decision Record: \<Title\>
+
+Initial Author: Jean-Gabriel Gill-Couture
+
+Initial Date: 2025-06-04
+
+Last Updated Date: 2025-06-04
+
+## Status
+
+Proposed
+
+## Context
+
+As Harmony's goal is to make software delivery easier, we must provide an easy way for developers to express their app's semantics and dependencies with great abstractions, in a similar fashion to what the score.dev project is doing.
+
+Thus, we started working on ways to package common types of applications such as LAMP, which we started working on with `LAMPScore`.
+
+Now is time for the next step : we want to pave the way towards complete lifecycle automation. To do this, we will start with a way to execute Harmony's modules easily from anywhere, starting with locally and in CI environments.
+
+## Decision
+
+To achieve easy, portable execution of Harmony, we will follow this architecture :
+
+- Host a basic harmony release that is compiled with the CLI by our gitea/github server
+    - This binary will do the following : check if there is a `harmony` folder in the current path
+    - If yes
+        - Check if cargo is available locally and compile the harmony binary, or compile the harmony binary using a rust docker container, if neither cargo or a container runtime is available, output a message explaining the situation
+        - Run the newly compiled binary. (Ideally using pid handoff like exec does but some research around this should be done. I think handing off the process is to help with OS interaction such as terminal apps, signals, exit codes, process handling, etc but there might be some side effects)
+    - If not
+        - Suggest initializing a project by auto detecting what the project looks like
+        - When the project type cannot be auto detected, provide links to Harmony's documentation on how to set up a project, a link to the examples folder, and a ask the user if he wants to initialize an empty Harmony project in the current folder
+            - harmony/Cargo.toml with dependencies set
+            - harmony/src/main.rs with an example LAMPScore setup and ready to run
+- This same binary can be used in a CI environment to run the target project's Harmony module. By default, we provide these opinionated steps :
+    1. **An empty check step.** The purpose of this step is to run all tests and checks against the codebase. For complex projects this could involve a very complex pipeline of test environments setup and execution but this is out of scope for now. This is not handled by harmony. For projects with automatic setup, we can fill this step with something like `cargo fmt --check; cargo test; cargo build` but Harmony is not directly involved in the execution of this step.
+    2. **Package and publish.** Once all checks have passed, the production ready container is built and pushed to a registry. This is done by Harmony.
+    3. **Deploy to staging automatically.** 
+    4. **Run a sanity check on staging.** As Harmony is responsible for deploying, Harmony should have all the knowledge of how to perform a sanity check on the staging environment. This will, most of the time, be a simple verification of the kubernetes health of all deployed components, and a poke on the public endpoint when there is one.
+    5. **Deploy to production automatically.** Many projects will require manual approval here, this can be easily set up in the CI afterwards, but our opinion is that 
+    6. **Run a sanity check on production.** Same check as staging, but on production.
+
+*Note on providing a base pipeline :* Having a complete pipeline set up automatically will encourage development teams to build upon these by adding tests where they belong. The goal here is to provide an opiniated solution that works for most small and large projects. Of course, many orgnizations will need to add steps such as deploying to sandbox environments, requiring more advanced approvals, more complex publication and coordination with other projects. But this here encompasses the basics required to build and deploy software reliably at any scale.
+
+### Environment setup
+
+TBD : For now, environments (tenants) will be set up and configured manually. Harmony will rely on the kubeconfig provided in the environment where it is running to deploy in the namespace.
+
+For the CD tool such as Argo or Flux they will be activated by default by Harmony when using application level Scores such as LAMPScore in a similar way that the container is automatically built. Then, CI deployment steps will be notifying the CD tool using its API of the new release to deploy.
+
+## Rationale
+
+Reasoning behind the decision
+
+## Consequences
+
+Pros/Cons of chosen solution
+
+## Alternatives considered
+
+Pros/Cons of various proposed solutions considered
+
+## Additional Notes

adr/013-monitoring-notifications.md

@@ -0,0 +1,78 @@
+# Architecture Decision Record: Monitoring Notifications
+
+Initial Author: Taha Hawa
+
+Initial Date: 2025-06-26
+
+Last Updated Date: 2025-06-26
+
+## Status
+
+Proposed
+
+## Context
+
+We need to send notifications (typically from AlertManager/Prometheus) and we need to receive said notifications on mobile devices for sure in some way, whether it's push messages, SMS, phone call, email, etc or all of the above.
+
+## Decision
+
+We should go with https://ntfy.sh except host it ourselves.
+
+`ntfy` is an open source solution written in Go that has the features we need.
+
+## Rationale
+
+`ntfy` has pretty much everything we need (push notifications, email forwarding, receives via webhook), and nothing/not much we don't. Good fit, lightweight.
+
+## Consequences
+
+Pros:
+
+- topics, with ACLs
+- lightweight
+- reliable
+- easy to configure
+- mobile app
+  - the mobile app can listen via websocket, poll, or receive via Firebase/GCM on Android, or similar on iOS.
+- Forward to email
+- Text-to-Speech phone call messages using Twilio integration
+- Operates based on simple HTTP requests/Webhooks, easily usable via AlertManager
+
+Cons:
+
+- No SMS pushes
+- SQLite DB, makes it harder to HA/scale
+
+## Alternatives considered
+
+[AWS SNS](https://aws.amazon.com/sns/):
+Pros:
+
+- highly reliable
+- no hosting needed
+
+Cons:
+
+- no control, not self hosted
+- costs (per usage)
+
+[Apprise](https://github.com/caronc/apprise):
+Pros:
+
+- Way more ways of sending notifications
+- Can use ntfy as one of the backends/ways of sending
+
+Cons:
+
+- Way too overkill for what we need in terms of features
+
+[Gotify](https://github.com/gotify/server):
+Pros:
+
+- simple, lightweight, golang, etc
+
+Cons:
+
+- Pushes topics are per-user
+
+## Additional Notes

adr/agent_discovery/mdns/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "mdns"
+edition = "2024"
+version.workspace = true
+readme.workspace = true
+license.workspace = true
+
+[dependencies]
+mdns-sd = "0.14"
+tokio = { version = "1", features = ["full"] }
+futures = "0.3"
+dmidecode = "0.2" # For getting the motherboard ID on the agent
+log.workspace=true
+env_logger.workspace=true
+clap = { version = "4.5.46", features = ["derive"] }
+get_if_addrs = "0.5.3"
+local-ip-address = "0.6.5"

adr/agent_discovery/mdns/src/advertise.rs

@@ -0,0 +1,60 @@
+// harmony-agent/src/main.rs
+
+use log::info;
+use mdns_sd::{ServiceDaemon, ServiceInfo};
+use std::collections::HashMap;
+
+use crate::SERVICE_TYPE;
+
+// The service we are advertising.
+const SERVICE_PORT: u16 = 43210; // A port for the service. It needs one, even if unused.
+
+pub async fn advertise() {
+    info!("Starting Harmony Agent...");
+
+    // Get a unique ID for this machine.
+    let motherboard_id = "some motherboard id";
+    let instance_name = format!("harmony-agent-{}", motherboard_id);
+    info!("This agent's instance name: {}", instance_name);
+    info!("Advertising with ID: {}", motherboard_id);
+
+    // Create a new mDNS daemon.
+    let mdns = ServiceDaemon::new().expect("Failed to create mDNS daemon");
+
+    // Create a TXT record HashMap to hold our metadata.
+    let mut properties = HashMap::new();
+    properties.insert("id".to_string(), motherboard_id.to_string());
+    properties.insert("version".to_string(), "1.0".to_string());
+
+    // Create the service information.
+    // The instance name should be unique on the network.
+    let local_ip = local_ip_address::local_ip().unwrap();
+    let service_info = ServiceInfo::new(
+        SERVICE_TYPE,
+        &instance_name,
+        "harmony-host.local.", // A hostname for the service
+        local_ip,
+        // "0.0.0.0",
+        SERVICE_PORT,
+        Some(properties),
+    )
+    .expect("Failed to create service info");
+
+    // Register our service with the daemon.
+    mdns.register(service_info)
+        .expect("Failed to register service");
+
+    info!(
+        "Service '{}' registered and now being advertised.",
+        instance_name
+    );
+    info!("Agent is running. Press Ctrl+C to exit.");
+
+    for iface in get_if_addrs::get_if_addrs().unwrap() {
+        println!("{:#?}", iface);
+    }
+
+    // Keep the agent running indefinitely.
+    tokio::signal::ctrl_c().await.unwrap();
+    info!("Shutting down agent.");
+}

adr/agent_discovery/mdns/src/discover.rs

@@ -0,0 +1,109 @@
+use mdns_sd::{ServiceDaemon, ServiceEvent};
+
+use crate::SERVICE_TYPE;
+
+pub async fn discover() {
+    println!("Starting Harmony Master and browsing for agents...");
+
+    // Create a new mDNS daemon.
+    let mdns = ServiceDaemon::new().expect("Failed to create mDNS daemon");
+
+    // Start browsing for the service type.
+    // The receiver will be a stream of events.
+    let receiver = mdns.browse(SERVICE_TYPE).expect("Failed to browse");
+
+    println!(
+        "Listening for mDNS events for '{}'. Press Ctrl+C to exit.",
+        SERVICE_TYPE
+    );
+
+    std::thread::spawn(move || {
+        while let Ok(event) = receiver.recv() {
+            match event {
+                ServiceEvent::ServiceData(resolved) => {
+                    println!("Resolved a new service: {}", resolved.fullname);
+                }
+                other_event => {
+                    println!("Received other event: {:?}", &other_event);
+                }
+            }
+        }
+    });
+
+    // Gracefully shutdown the daemon.
+    std::thread::sleep(std::time::Duration::from_secs(1000000));
+    mdns.shutdown().unwrap();
+
+    // Process events as they come in.
+    // while let Ok(event) = receiver.recv_async().await {
+    //     debug!("Received event {event:?}");
+    //     // match event {
+    //     //     ServiceEvent::ServiceFound(svc_type, fullname) => {
+    //     //         println!("\n--- Agent Discovered ---");
+    //     //         println!("  Service Name: {}", fullname());
+    //     //         // You can now resolve this service to get its IP, port, and TXT records
+    //     //         // The resolve operation is a separate network call.
+    //     //         let receiver = mdns.browse(info.get_fullname()).unwrap();
+    //     //         if let Ok(resolve_event) = receiver.recv_timeout(Duration::from_secs(2)) {
+    //     //              if let ServiceEvent::ServiceResolved(info) = resolve_event {
+    //     //                 let ip = info.get_addresses().iter().next().unwrap();
+    //     //                 let port = info.get_port();
+    //     //                 let motherboard_id = info.get_property("id").map_or("N/A", |v| v.val_str());
+    //     //
+    //     //                 println!("  IP: {}:{}", ip, port);
+    //     //                 println!("  Motherboard ID: {}", motherboard_id);
+    //     //                 println!("------------------------");
+    //     //
+    //     //                 // TODO: Add this agent to your central list of discovered hosts.
+    //     //              }
+    //     //         } else {
+    //     //             println!("Could not resolve service '{}' in time.", info.get_fullname());
+    //     //         }
+    //     //     }
+    //     //     ServiceEvent::ServiceRemoved(info) => {
+    //     //         println!("\n--- Agent Removed ---");
+    //     //         println!("  Service Name: {}", info.get_fullname());
+    //     //         println!("---------------------");
+    //     //         // TODO: Remove this agent from your list.
+    //     //     }
+    //     //     _ => {
+    //     //         // We don't care about other event types for this example
+    //     //     }
+    //     // }
+    // }
+}
+
+async fn _discover_example() {
+    use mdns_sd::{ServiceDaemon, ServiceEvent};
+
+    // Create a daemon
+    let mdns = ServiceDaemon::new().expect("Failed to create daemon");
+
+    // Use recently added `ServiceEvent::ServiceData`.
+    mdns.use_service_data(true)
+        .expect("Failed to use ServiceData");
+
+    // Browse for a service type.
+    let service_type = "_mdns-sd-my-test._udp.local.";
+    let receiver = mdns.browse(service_type).expect("Failed to browse");
+
+    // Receive the browse events in sync or async. Here is
+    // an example of using a thread. Users can call `receiver.recv_async().await`
+    // if running in async environment.
+    std::thread::spawn(move || {
+        while let Ok(event) = receiver.recv() {
+            match event {
+                ServiceEvent::ServiceData(resolved) => {
+                    println!("Resolved a new service: {}", resolved.fullname);
+                }
+                other_event => {
+                    println!("Received other event: {:?}", &other_event);
+                }
+            }
+        }
+    });
+
+    // Gracefully shutdown the daemon.
+    std::thread::sleep(std::time::Duration::from_secs(1));
+    mdns.shutdown().unwrap();
+}

adr/agent_discovery/mdns/src/main.rs

@@ -0,0 +1,31 @@
+use clap::{Parser, ValueEnum};
+
+mod advertise;
+mod discover;
+
+#[derive(Parser, Debug)]
+#[command(version, about, long_about = None)]
+struct Args {
+    #[arg(value_enum)]
+    profile: Profiles,
+}
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, ValueEnum)]
+enum Profiles {
+    Advertise,
+    Discover,
+}
+
+// The service type we are looking for.
+const SERVICE_TYPE: &str = "_harmony._tcp.local.";
+
+#[tokio::main]
+async fn main() {
+    env_logger::init();
+    let args = Args::parse();
+
+    match args.profile {
+        Profiles::Advertise => advertise::advertise().await,
+        Profiles::Discover => discover::discover().await,
+    }
+}

check.sh

@@ -1,5 +1,8 @@
 #!/bin/sh
 set -e
+
+rustc --version
 cargo check --all-targets --all-features --keep-going
 cargo fmt --check
+cargo clippy
 cargo test

data/okd/installer_image/scos-live-initramfs.x86_64.img

@@ -0,0 +1 @@
+scos-9.0.20250510-0-live-initramfs.x86_64.img

data/okd/installer_image/scos-live-kernel.x86_64

@@ -0,0 +1 @@
+scos-9.0.20250510-0-live-kernel.x86_64

data/okd/installer_image/scos-live-rootfs.x86_64.img

@@ -0,0 +1 @@
+scos-9.0.20250510-0-live-rootfs.x86_64.img

data/pxe/okd/README.md

@@ -0,0 +1,8 @@
+Here lies all the data files required for an OKD cluster PXE boot setup.
+
+This inclues ISO files, binary boot files, ipxe, etc.
+
+TODO as of august 2025 :
+
+- `harmony_inventory_agent` should be downloaded from official releases, this embedded version is practical for now though
+- The cluster ssh key should be generated and handled by harmony with the private key saved in a secret store

data/pxe/okd/http_files/.gitattributes

@@ -0,0 +1,9 @@
+harmony_inventory_agent filter=lfs diff=lfs merge=lfs -text
+os filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9 filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9/images filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9/initrd.img filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9/vmlinuz filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9/images/efiboot.img filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9/images/install.img filter=lfs diff=lfs merge=lfs -text
+os/centos-stream-9/images/pxeboot filter=lfs diff=lfs merge=lfs -text

data/pxe/okd/http_files/cluster_ssh_key.pub

@@ -0,0 +1 @@
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBx6bDylvC68cVpjKfEFtLQJ/dOFi6PVS2vsIOqPDJIc jeangab@liliane2

docs/README.md

@@ -0,0 +1 @@
+Not much here yet, see the `adr` folder for now. More to come in time!

docs/cyborg-metaphor.md

@@ -0,0 +1,13 @@
+## Conceptual metaphor : The Cyborg and the Central Nervous System
+
+At the heart of Harmony lies a core belief: in modern, decentralized systems, **software and infrastructure are not separate entities.** They are a single, symbiotic organism—a cyborg.
+
+The software is the electronics, the "mind"; the infrastructure is the biological host, the "body". They live or die, thrive or sink together.
+
+Traditional approaches attempt to manage this complex organism with fragmented tools: static YAML for configuration, brittle scripts for automation, and separate Infrastructure as Code (IaC) for provisioning. This creates a disjointed system that struggles to scale or heal itself, making it inadequate for the demands of fully automated, enterprise-grade clusters.
+
+Harmony's goal is to provide the **central nervous system for this cyborg**. We aim to achieve the full automation of complex, decentralized clouds by managing this integrated entity holistically.
+
+To achieve this, a tool must be both robust and powerful. It must manage the entire lifecycle—deployment, upgrades, failure recovery, and decommissioning—with precision. This requires full control over application packaging and a deep, intrinsic integration between the software and the infrastructure it inhabits.
+
+This is why Harmony uses a powerful, living language like Rust. It replaces static, lifeless configuration files with a dynamic, breathing codebase. It allows us to express the complex relationships and behaviors of a modern distributed system, enabling the creation of truly automated, resilient, and powerful platforms that can thrive.

docs/pxe_test/README.md

@@ -0,0 +1,108 @@
+# OPNsense PXE Lab Environment
+
+This project contains a script to automatically set up a virtual lab environment for testing PXE boot services managed by an OPNsense firewall.
+
+## Overview
+
+The `pxe_vm_lab_setup.sh` script will create the following resources using libvirt/KVM:
+
+1.  **A Virtual Network**: An isolated network named `harmonylan` (`virbr1`) for the lab.
+2.  **Two Virtual Machines**:
+    *   `opnsense-pxe`: A firewall VM that will act as the gateway and PXE server.
+    *   `pxe-node-1`: A client VM configured to boot from the network.
+
+## Prerequisites
+
+Ensure you have the following software installed on your Arch Linux host:
+
+*   `libvirt`
+*   `qemu`
+*   `virt-install` (from the `virt-install` package)
+*   `curl`
+*   `bzip2`
+
+## Usage
+
+### 1. Create the Environment
+
+Run the `up` command to download the necessary images and create the network and VMs.
+
+```bash
+sudo ./pxe_vm_lab_setup.sh up
+```
+
+### 2. Install and Configure OPNsense
+
+The OPNsense VM is created but the OS needs to be installed manually via the console.
+
+1.  **Connect to the VM console**:
+    ```bash
+    sudo virsh console opnsense-pxe
+    ```
+
+2.  **Log in as the installer**:
+    *   Username: `installer`
+    *   Password: `opnsense`
+
+3.  **Follow the on-screen installation wizard**. When prompted to assign network interfaces (`WAN` and `LAN`):
+    *   Find the MAC address for the `harmonylan` interface by running this command in another terminal:
+        ```bash
+        virsh domiflist opnsense-pxe
+        # Example output:
+        # Interface   Type      Source       Model    MAC
+        # ---------------------------------------------------------
+        # vnet18      network   default      virtio   52:54:00:b5:c4:6d
+        # vnet19      network   harmonylan   virtio   52:54:00:21:f9:ba
+        ```
+    *   Assign the interface connected to `harmonylan` (e.g., `vtnet1` with MAC `52:54:00:21:f9:ba`) as your **LAN**.
+    *   Assign the other interface as your **WAN**.
+
+4.  After the installation is complete, **shut down** the VM from the console menu.
+
+5.  **Detach the installation media** by editing the VM's configuration:
+    ```bash
+    sudo virsh edit opnsense-pxe
+    ```
+    Find and **delete** the entire `<disk>` block corresponding to the `.img` file (the one with `<target ... bus='usb'/>`).
+
+6.  **Start the VM** to boot into the newly installed system:
+    ```bash
+    sudo virsh start opnsense-pxe
+    ```
+
+### 3. Connect to OPNsense from Your Host
+
+To configure OPNsense, you need to connect your host to the `harmonylan` network.
+
+1.  By default, OPNsense configures its LAN interface with the IP `192.168.1.1`.
+2.  Assign a compatible IP address to your host's `virbr1` bridge interface:
+    ```bash
+    sudo ip addr add 192.168.1.5/24 dev virbr1
+    ```
+3.  You can now access the OPNsense VM from your host:
+    *   **SSH**: `ssh root@192.168.1.1` (password: `opnsense`)
+    *   **Web UI**: `https://192.168.1.1`
+
+### 4. Configure PXE Services with Harmony
+
+With connectivity established, you can now use Harmony to configure the OPNsense firewall for PXE booting. Point your Harmony OPNsense scores to the firewall using these details:
+
+*   **Hostname/IP**: `192.168.1.1`
+*   **Credentials**: `root` / `opnsense`
+
+### 5. Boot the PXE Client
+
+Once your Harmony configuration has been applied and OPNsense is serving DHCP/TFTP, start the client VM. It will automatically attempt to boot from the network.
+
+```bash
+sudo virsh start pxe-node-1
+sudo virsh console pxe-node-1
+```
+
+## Cleanup
+
+To destroy all VMs and networks created by the script, run the `clean` command:
+
+```bash
+sudo ./pxe_vm_lab_setup.sh clean
+```

docs/pxe_test/pxe_vm_lab_setup.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# --- Configuration ---
+LAB_DIR="/var/lib/harmony_pxe_test"
+IMG_DIR="${LAB_DIR}/images"
+STATE_DIR="${LAB_DIR}/state"
+VM_OPN="opnsense-pxe"
+VM_PXE="pxe-node-1"
+NET_HARMONYLAN="harmonylan"
+
+# Network settings for the isolated LAN
+VLAN_CIDR="192.168.150.0/24"
+VLAN_GW="192.168.150.1"
+VLAN_MASK="255.255.255.0"
+
+# VM Specifications
+RAM_OPN="2048"
+VCPUS_OPN="2"
+DISK_OPN_GB="10"
+OS_VARIANT_OPN="freebsd14.0" # Updated to a more recent FreeBSD variant
+
+RAM_PXE="4096"
+VCPUS_PXE="2"
+DISK_PXE_GB="40"
+OS_VARIANT_LINUX="centos-stream9"
+
+OPN_IMG_URL="https://mirror.ams1.nl.leaseweb.net/opnsense/releases/25.7/OPNsense-25.7-serial-amd64.img.bz2"
+OPN_IMG_PATH="${IMG_DIR}/OPNsense-25.7-serial-amd64.img"
+CENTOS_ISO_URL="https://mirror.stream.centos.org/9-stream/BaseOS/x86_64/os/images/boot.iso"
+CENTOS_ISO_PATH="${IMG_DIR}/CentOS-Stream-9-latest-boot.iso"
+
+CONNECT_URI="qemu:///system"
+
+download_if_missing() {
+  local url="$1"
+  local dest="$2"
+  if [[ ! -f "$dest" ]]; then
+    echo "Downloading $url to $dest"
+    mkdir -p "$(dirname "$dest")"
+    local tmp
+    tmp="$(mktemp)"
+    curl -L --progress-bar "$url" -o "$tmp"
+    case "$url" in
+      *.bz2) bunzip2 -c "$tmp" > "$dest" && rm -f "$tmp" ;;
+      *) mv "$tmp" "$dest" ;;
+    esac
+  else
+    echo "Already present: $dest"
+  fi
+}
+
+# Ensures a libvirt network is defined and active
+ensure_network() {
+  local net_name="$1"
+  local net_xml_path="$2"
+  if virsh --connect "${CONNECT_URI}" net-info "${net_name}" >/dev/null 2>&1; then
+    echo "Network ${net_name} already exists."
+  else
+    echo "Defining network ${net_name} from ${net_xml_path}"
+    virsh --connect "${CONNECT_URI}" net-define "${net_xml_path}"
+  fi
+
+  if ! virsh --connect "${CONNECT_URI}" net-info "${net_name}" | grep "Active: *yes"; then
+    echo "Starting network ${net_name}..."
+    virsh --connect "${CONNECT_URI}" net-start "${net_name}"
+    virsh --connect "${CONNECT_URI}" net-autostart "${net_name}"
+  fi
+}
+
+# Destroys a VM completely
+destroy_vm() {
+  local vm_name="$1"
+  if virsh --connect "${CONNECT_URI}" dominfo "$vm_name" >/dev/null 2>&1; then
+    echo "Destroying and undefining VM: ${vm_name}"
+    virsh --connect "${CONNECT_URI}" destroy "$vm_name" || true
+    virsh --connect "${CONNECT_URI}" undefine "$vm_name" --nvram
+  fi
+}
+
+# Destroys a libvirt network
+destroy_network() {
+  local net_name="$1"
+  if virsh --connect "${CONNECT_URI}" net-info "$net_name" >/dev/null 2>&1; then
+    echo "Destroying and undefining network: ${net_name}"
+    virsh --connect "${CONNECT_URI}" net-destroy "$net_name" || true
+    virsh --connect "${CONNECT_URI}" net-undefine "$net_name"
+  fi
+}
+
+# --- Main Logic ---
+create_lab_environment() {
+  # Create network definition files
+  cat > "${STATE_DIR}/default.xml" <<EOF
+<network>
+  <name>default</name>
+  <forward mode='nat'/>
+  <bridge name='virbr0' stp='on' delay='0'/>
+  <ip address='192.168.122.1' netmask='255.255.255.0'>
+    <dhcp>
+      <range start='192.168.122.100' end='192.168.122.200'/>
+    </dhcp>
+  </ip>
+</network>
+EOF
+
+  cat > "${STATE_DIR}/${NET_HARMONYLAN}.xml" <<EOF
+<network>
+  <name>${NET_HARMONYLAN}</name>
+  <bridge name='virbr1' stp='on' delay='0'/>
+</network>
+EOF
+
+  # Ensure both networks exist and are active
+  ensure_network "default" "${STATE_DIR}/default.xml"
+  ensure_network "${NET_HARMONYLAN}" "${STATE_DIR}/${NET_HARMONYLAN}.xml"
+
+  # --- Create OPNsense VM (MODIFIED SECTION) ---
+  local disk_opn="${IMG_DIR}/${VM_OPN}.qcow2"
+  if [[ ! -f "$disk_opn" ]]; then
+    qemu-img create -f qcow2 "$disk_opn" "${DISK_OPN_GB}G"
+  fi
+
+  echo "Creating OPNsense VM using serial image..."
+  virt-install \
+    --connect "${CONNECT_URI}" \
+    --name "${VM_OPN}" \
+    --ram "${RAM_OPN}" \
+    --vcpus "${VCPUS_OPN}" \
+    --cpu host-passthrough \
+    --os-variant "${OS_VARIANT_OPN}" \
+    --graphics none \
+    --noautoconsole \
+    --disk path="${disk_opn}",device=disk,bus=virtio,boot.order=1 \
+    --disk path="${OPN_IMG_PATH}",device=disk,bus=usb,readonly=on,boot.order=2 \
+    --network network=default,model=virtio \
+    --network network="${NET_HARMONYLAN}",model=virtio \
+    --boot uefi,menu=on
+
+  echo "OPNsense VM created. Connect with: sudo virsh console ${VM_OPN}"
+  echo "The VM will boot from the serial installation image."
+  echo "Login with user 'installer' and password 'opnsense' to start the installation."
+  echo "Install onto the VirtIO disk (vtbd0)."
+  echo "After installation, shutdown the VM, then run 'sudo virsh edit ${VM_OPN}' and remove the USB disk block to boot from the installed system."
+
+  # --- Create PXE Client VM ---
+  local disk_pxe="${IMG_DIR}/${VM_PXE}.qcow2"
+  if [[ ! -f "$disk_pxe" ]]; then
+    qemu-img create -f qcow2 "$disk_pxe" "${DISK_PXE_GB}G"
+  fi
+
+  echo "Creating PXE client VM..."
+  virt-install \
+    --connect "${CONNECT_URI}" \
+    --name "${VM_PXE}" \
+    --ram "${RAM_PXE}" \
+    --vcpus "${VCPUS_PXE}" \
+    --cpu host-passthrough \
+    --os-variant "${OS_VARIANT_LINUX}" \
+    --graphics none \
+    --noautoconsole \
+    --disk path="${disk_pxe}",format=qcow2,bus=virtio \
+    --network network="${NET_HARMONYLAN}",model=virtio \
+    --pxe \
+    --boot uefi,menu=on
+
+  echo "PXE VM created. It will attempt to netboot on ${NET_HARMONYLAN}."
+}
+
+# --- Script Entrypoint ---
+case "${1:-}" in
+  up)
+    mkdir -p "${IMG_DIR}" "${STATE_DIR}"
+    download_if_missing "$OPN_IMG_URL" "$OPN_IMG_PATH"
+    download_if_missing "$CENTOS_ISO_URL" "$CENTOS_ISO_PATH"
+    create_lab_environment
+    echo "Lab setup complete. Use 'sudo virsh list --all' to see VMs."
+    ;;
+  clean)
+    destroy_vm "${VM_PXE}"
+    destroy_vm "${VM_OPN}"
+    destroy_network "${NET_HARMONYLAN}"
+    # Optionally destroy the default network if you want a full reset
+    # destroy_network "default"
+    echo "Cleanup complete."
+    ;;
+  *)
+    echo "Usage: sudo $0 {up|clean}"
+    exit 1
+    ;;
+esac

examples/application_monitoring_with_tenant/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "example-application-monitoring-with-tenant"
+edition = "2024"
+version.workspace = true
+readme.workspace = true
+license.workspace = true
+
+[dependencies]
+env_logger.workspace = true
+harmony = { path = "../../harmony" }
+harmony_cli = { path = "../../harmony_cli" }
+harmony_types = { path = "../../harmony_types" }
+logging = "0.1.0"
+tokio.workspace = true
+url.workspace = true

examples/application_monitoring_with_tenant/src/main.rs

@@ -0,0 +1,56 @@
+use std::{path::PathBuf, str::FromStr, sync::Arc};
+
+use harmony::{
+    inventory::Inventory,
+    modules::{
+        application::{ApplicationScore, RustWebFramework, RustWebapp, features::Monitoring},
+        monitoring::alert_channel::webhook_receiver::WebhookReceiver,
+        tenant::TenantScore,
+    },
+    topology::{K8sAnywhereTopology, tenant::TenantConfig},
+};
+use harmony_types::id::Id;
+use harmony_types::net::Url;
+
+#[tokio::main]
+async fn main() {
+    //TODO there is a bug where the application is deployed into the namespace matching the
+    //application name and the tenant is created in the namesapce matching the tenant name
+    //in order for the application to be deployed in the tenant namespace the application.name and
+    //the TenantConfig.name must match
+    let tenant = TenantScore {
+        config: TenantConfig {
+            id: Id::from_str("test-tenant-id").unwrap(),
+            name: "example-monitoring".to_string(),
+            ..Default::default()
+        },
+    };
+    let application = Arc::new(RustWebapp {
+        name: "example-monitoring".to_string(),
+        domain: Url::Url(url::Url::parse("https://rustapp.harmony.example.com").unwrap()),
+        project_root: PathBuf::from("./examples/rust/webapp"),
+        framework: Some(RustWebFramework::Leptos),
+    });
+
+    let webhook_receiver = WebhookReceiver {
+        name: "sample-webhook-receiver".to_string(),
+        url: Url::Url(url::Url::parse("https://webhook-doesnt-exist.com").unwrap()),
+    };
+
+    let app = ApplicationScore {
+        features: vec![Box::new(Monitoring {
+            alert_receiver: vec![Box::new(webhook_receiver)],
+            application: application.clone(),
+        })],
+        application,
+    };
+
+    harmony_cli::run(
+        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
+        vec![Box::new(tenant), Box::new(app)],
+        None,
+    )
+    .await
+    .unwrap();
+}

examples/cli/src/main.rs

@@ -1,20 +1,27 @@
 use harmony::{
     inventory::Inventory,
-    maestro::Maestro,
-    modules::dummy::{ErrorScore, PanicScore, SuccessScore},
+    modules::{
+        dummy::{ErrorScore, PanicScore, SuccessScore},
+        inventory::LaunchDiscoverInventoryAgentScore,
+    },
     topology::LocalhostTopology,
 };
 
 #[tokio::main]
 async fn main() {
-    let inventory = Inventory::autoload();
-    let topology = LocalhostTopology::new();
-    let mut maestro = Maestro::initialize(inventory, topology).await.unwrap();
-
-    maestro.register_all(vec![
+    harmony_cli::run(
+        Inventory::autoload(),
+        LocalhostTopology::new(),
+        vec![
             Box::new(SuccessScore {}),
             Box::new(ErrorScore {}),
             Box::new(PanicScore {}),
-    ]);
-    harmony_cli::init(maestro, None).await.unwrap();
+            Box::new(LaunchDiscoverInventoryAgentScore {
+                discovery_timeout: Some(10),
+            }),
+        ],
+        None,
+    )
+    .await
+    .unwrap();
 }

examples/kube-rs/Cargo.toml

@@ -14,8 +14,8 @@ harmony_macros = { path = "../../harmony_macros" }
 log = { workspace = true }
 env_logger = { workspace = true }
 url = { workspace = true }
-kube = "0.98.0"
-k8s-openapi = { version = "0.24.0", features = [ "v1_30" ] }
+kube = "1.1.0"
+k8s-openapi = { version = "0.25.0", features = ["v1_30"] }
 http = "1.2.0"
 serde_yaml = "0.9.34"
 inquire.workspace = true

examples/kube-rs/src/main.rs

@@ -125,40 +125,47 @@ spec:
                   name: nginx"#,
     )
     .unwrap();
-    return deployment;
+    deployment
 }
 fn nginx_deployment_2() -> Deployment {
-    let mut pod_template = PodTemplateSpec::default();
-    pod_template.metadata = Some(ObjectMeta {
+    let pod_template = PodTemplateSpec {
+        metadata: Some(ObjectMeta {
             labels: Some(BTreeMap::from([(
                 "app".to_string(),
                 "nginx-test".to_string(),
             )])),
             ..Default::default()
-    });
-    pod_template.spec = Some(PodSpec {
+        }),
+        spec: Some(PodSpec {
             containers: vec![Container {
                 name: "nginx".to_string(),
                 image: Some("nginx".to_string()),
                 ..Default::default()
             }],
             ..Default::default()
-    });
-    let mut spec = DeploymentSpec::default();
-    spec.template = pod_template;
-    spec.selector = LabelSelector {
+        }),
+    };
+
+    let spec = DeploymentSpec {
+        template: pod_template,
+        selector: LabelSelector {
             match_expressions: None,
             match_labels: Some(BTreeMap::from([(
                 "app".to_string(),
                 "nginx-test".to_string(),
             )])),
+        },
+        ..Default::default()
     };
 
-    let mut deployment = Deployment::default();
-    deployment.spec = Some(spec);
-    deployment.metadata.name = Some("nginx-test".to_string());
-
-    deployment
+    Deployment {
+        spec: Some(spec),
+        metadata: ObjectMeta {
+            name: Some("nginx-test".to_string()),
+            ..Default::default()
+        },
+        ..Default::default()
+    }
 }
 
 fn nginx_deployment() -> Deployment {

examples/lamp/src/main.rs

@@ -1,13 +1,10 @@
 use harmony::{
     data::Version,
     inventory::Inventory,
-    maestro::Maestro,
-    modules::{
-        lamp::{LAMPConfig, LAMPScore},
-        monitoring::monitoring_alerting::{AlertChannel, MonitoringAlertingStackScore},
-    },
-    topology::{K8sAnywhereTopology, Url},
+    modules::lamp::{LAMPConfig, LAMPScore},
+    topology::K8sAnywhereTopology,
 };
+use harmony_types::net::Url;
 
 #[tokio::main]
 async fn main() {
@@ -27,30 +24,32 @@ async fn main() {
         // This config can be extended as needed for more complicated configurations
         config: LAMPConfig {
             project_root: "./php".into(),
-            database_size: format!("4Gi").into(),
+            database_size: "4Gi".to_string().into(),
             ..Default::default()
         },
     };
 
+    //let monitoring = MonitoringAlertingScore {
+    //    alert_receivers: vec![Box::new(DiscordWebhook {
+    //        url: Url::Url(url::Url::parse("https://discord.idonotexist.com").unwrap()),
+    //        // TODO write url macro
+    //        // url: url!("https://discord.idonotexist.com"),
+    //    })],
+    //    alert_rules: vec![],
+    //    scrape_targets: vec![],
+    //};
+
     // You can choose the type of Topology you want, we suggest starting with the
     // K8sAnywhereTopology as it is the most automatic one that enables you to easily deploy
     // locally, to development environment from a CI, to staging, and to production with settings
     // that automatically adapt to each environment grade.
-    let mut maestro = Maestro::<K8sAnywhereTopology>::initialize(
+    harmony_cli::run(
         Inventory::autoload(),
-        K8sAnywhereTopology::new(),
+        K8sAnywhereTopology::from_env(),
+        vec![Box::new(lamp_stack)],
+        None,
     )
     .await
     .unwrap();
-
-    let url = url::Url::parse("https://discord.com/api/webhooks/dummy_channel/dummy_token")
-        .expect("invalid URL");
-
-    let mut monitoring_stack_score = MonitoringAlertingStackScore::new();
-    monitoring_stack_score.namespace = Some(lamp_stack.config.namespace.clone());
-
-    maestro.register_all(vec![Box::new(lamp_stack), Box::new(monitoring_stack_score)]);
-    // Here we bootstrap the CLI, this gives some nice features if you need them
-    harmony_cli::init(maestro, None).await.unwrap();
 }
 // That's it, end of the infra as code.

examples/monitoring/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "example-monitoring"
+edition = "2024"
+version.workspace = true
+readme.workspace = true
+license.workspace = true
+
+[dependencies]
+harmony = { path = "../../harmony" }
+harmony_cli = { path = "../../harmony_cli" }
+harmony_macros = { path = "../../harmony_macros" }
+harmony_types = { path = "../../harmony_types" }
+tokio.workspace = true
+url.workspace = true

examples/monitoring/src/main.rs

@@ -0,0 +1,86 @@
+use std::collections::HashMap;
+
+use harmony::{
+    inventory::Inventory,
+    modules::{
+        monitoring::{
+            alert_channel::discord_alert_channel::DiscordWebhook,
+            alert_rule::prometheus_alert_rule::AlertManagerRuleGroup,
+            kube_prometheus::{
+                helm_prometheus_alert_score::HelmPrometheusAlertingScore,
+                types::{
+                    HTTPScheme, MatchExpression, Operator, Selector, ServiceMonitor,
+                    ServiceMonitorEndpoint,
+                },
+            },
+        },
+        prometheus::alerts::{
+            infra::dell_server::{
+                alert_global_storage_status_critical, alert_global_storage_status_non_recoverable,
+                global_storage_status_degraded_non_critical,
+            },
+            k8s::pvc::high_pvc_fill_rate_over_two_days,
+        },
+    },
+    topology::K8sAnywhereTopology,
+};
+use harmony_types::net::Url;
+
+#[tokio::main]
+async fn main() {
+    let discord_receiver = DiscordWebhook {
+        name: "test-discord".to_string(),
+        url: Url::Url(url::Url::parse("https://discord.doesnt.exist.com").unwrap()),
+    };
+
+    let high_pvc_fill_rate_over_two_days_alert = high_pvc_fill_rate_over_two_days();
+    let dell_system_storage_degraded = global_storage_status_degraded_non_critical();
+    let alert_global_storage_status_critical = alert_global_storage_status_critical();
+    let alert_global_storage_status_non_recoverable = alert_global_storage_status_non_recoverable();
+
+    let additional_rules =
+        AlertManagerRuleGroup::new("pvc-alerts", vec![high_pvc_fill_rate_over_two_days_alert]);
+    let additional_rules2 = AlertManagerRuleGroup::new(
+        "dell-server-alerts",
+        vec![
+            dell_system_storage_degraded,
+            alert_global_storage_status_critical,
+            alert_global_storage_status_non_recoverable,
+        ],
+    );
+
+    let service_monitor_endpoint = ServiceMonitorEndpoint {
+        port: Some("80".to_string()),
+        path: Some("/metrics".to_string()),
+        scheme: Some(HTTPScheme::HTTP),
+        ..Default::default()
+    };
+
+    let service_monitor = ServiceMonitor {
+        name: "test-service-monitor".to_string(),
+        selector: Selector {
+            match_labels: HashMap::new(),
+            match_expressions: vec![MatchExpression {
+                key: "test".to_string(),
+                operator: Operator::In,
+                values: vec!["test-service".to_string()],
+            }],
+        },
+        endpoints: vec![service_monitor_endpoint],
+        ..Default::default()
+    };
+    let alerting_score = HelmPrometheusAlertingScore {
+        receivers: vec![Box::new(discord_receiver)],
+        rules: vec![Box::new(additional_rules), Box::new(additional_rules2)],
+        service_monitors: vec![service_monitor],
+    };
+
+    harmony_cli::run(
+        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
+        vec![Box::new(alerting_score)],
+        None,
+    )
+    .await
+    .unwrap();
+}

examples/monitoring_with_tenant/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "example-monitoring-with-tenant"
+edition = "2024"
+version.workspace = true
+readme.workspace = true
+license.workspace = true
+
+[dependencies]
+cidr.workspace = true
+harmony = { path = "../../harmony" }
+harmony_cli = { path = "../../harmony_cli" }
+harmony_types = { path = "../../harmony_types" }
+tokio.workspace = true
+url.workspace = true

examples/monitoring_with_tenant/src/main.rs

@@ -0,0 +1,90 @@
+use std::{collections::HashMap, str::FromStr};
+
+use harmony::{
+    inventory::Inventory,
+    modules::{
+        monitoring::{
+            alert_channel::discord_alert_channel::DiscordWebhook,
+            alert_rule::prometheus_alert_rule::AlertManagerRuleGroup,
+            kube_prometheus::{
+                helm_prometheus_alert_score::HelmPrometheusAlertingScore,
+                types::{
+                    HTTPScheme, MatchExpression, Operator, Selector, ServiceMonitor,
+                    ServiceMonitorEndpoint,
+                },
+            },
+        },
+        prometheus::alerts::k8s::pvc::high_pvc_fill_rate_over_two_days,
+        tenant::TenantScore,
+    },
+    topology::{
+        K8sAnywhereTopology,
+        tenant::{ResourceLimits, TenantConfig, TenantNetworkPolicy},
+    },
+};
+use harmony_types::id::Id;
+use harmony_types::net::Url;
+
+#[tokio::main]
+async fn main() {
+    let tenant = TenantScore {
+        config: TenantConfig {
+            id: Id::from_str("1234").unwrap(),
+            name: "test-tenant".to_string(),
+            resource_limits: ResourceLimits {
+                cpu_request_cores: 6.0,
+                cpu_limit_cores: 4.0,
+                memory_request_gb: 4.0,
+                memory_limit_gb: 4.0,
+                storage_total_gb: 10.0,
+            },
+            network_policy: TenantNetworkPolicy::default(),
+        },
+    };
+
+    let discord_receiver = DiscordWebhook {
+        name: "test-discord".to_string(),
+        url: Url::Url(url::Url::parse("https://discord.doesnt.exist.com").unwrap()),
+    };
+
+    let high_pvc_fill_rate_over_two_days_alert = high_pvc_fill_rate_over_two_days();
+
+    let additional_rules =
+        AlertManagerRuleGroup::new("pvc-alerts", vec![high_pvc_fill_rate_over_two_days_alert]);
+
+    let service_monitor_endpoint = ServiceMonitorEndpoint {
+        port: Some("80".to_string()),
+        path: Some("/metrics".to_string()),
+        scheme: Some(HTTPScheme::HTTP),
+        ..Default::default()
+    };
+
+    let service_monitor = ServiceMonitor {
+        name: "test-service-monitor".to_string(),
+        selector: Selector {
+            match_labels: HashMap::new(),
+            match_expressions: vec![MatchExpression {
+                key: "test".to_string(),
+                operator: Operator::In,
+                values: vec!["test-service".to_string()],
+            }],
+        },
+        endpoints: vec![service_monitor_endpoint],
+        ..Default::default()
+    };
+
+    let alerting_score = HelmPrometheusAlertingScore {
+        receivers: vec![Box::new(discord_receiver)],
+        rules: vec![Box::new(additional_rules)],
+        service_monitors: vec![service_monitor],
+    };
+
+    harmony_cli::run(
+        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
+        vec![Box::new(tenant), Box::new(alerting_score)],
+        None,
+    )
+    .await
+    .unwrap();
+}

examples/nanodc/src/main.rs

@@ -5,23 +5,22 @@ use std::{
 
 use cidr::Ipv4Cidr;
 use harmony::{
-    hardware::{FirewallGroup, HostCategory, Location, PhysicalHost, SwitchGroup},
+    hardware::{HostCategory, Location, PhysicalHost, SwitchGroup},
     infra::opnsense::OPNSenseManagementInterface,
     inventory::Inventory,
-    maestro::Maestro,
     modules::{
-        http::HttpScore,
-        ipxe::IpxeScore,
+        http::StaticFilesHttpScore,
         okd::{
             bootstrap_dhcp::OKDBootstrapDhcpScore,
             bootstrap_load_balancer::OKDBootstrapLoadBalancerScore, dhcp::OKDDhcpScore,
-            dns::OKDDnsScore,
+            dns::OKDDnsScore, ipxe::OkdIpxeScore,
         },
         tftp::TftpScore,
     },
-    topology::{LogicalHost, UnmanagedRouter, Url},
+    topology::{LogicalHost, UnmanagedRouter},
 };
 use harmony_macros::{ip, mac_address};
+use harmony_types::net::Url;
 
 #[tokio::main]
 async fn main() {
@@ -87,8 +86,7 @@ async fn main() {
     let inventory = Inventory {
         location: Location::new("I am mobile".to_string(), "earth".to_string()),
         switch: SwitchGroup::from([]),
-        firewall: FirewallGroup::from([PhysicalHost::empty(HostCategory::Firewall)
-            .management(Arc::new(OPNSenseManagementInterface::new()))]),
+        firewall_mgmt: Box::new(OPNSenseManagementInterface::new()),
         storage_host: vec![],
         worker_host: vec![
             PhysicalHost::empty(HostCategory::Server)
@@ -126,12 +124,28 @@ async fn main() {
         harmony::modules::okd::load_balancer::OKDLoadBalancerScore::new(&topology);
 
     let tftp_score = TftpScore::new(Url::LocalFolder("./data/watchguard/tftpboot".to_string()));
-    let http_score = HttpScore::new(Url::LocalFolder(
+    let http_score = StaticFilesHttpScore {
+        folder_to_serve: Some(Url::LocalFolder(
             "./data/watchguard/pxe-http-files".to_string(),
-    ));
-    let ipxe_score = IpxeScore::new();
-    let mut maestro = Maestro::initialize(inventory, topology).await.unwrap();
-    maestro.register_all(vec![
+        )),
+        files: vec![],
+        remote_path: None,
+    };
+
+    let kickstart_filename = "inventory.kickstart".to_string();
+    let cluster_pubkey_filename = "cluster_ssh_key.pub".to_string();
+    let harmony_inventory_agent = "harmony_inventory_agent".to_string();
+
+    let ipxe_score = OkdIpxeScore {
+        kickstart_filename,
+        harmony_inventory_agent,
+        cluster_pubkey_filename,
+    };
+
+    harmony_tui::run(
+        inventory,
+        topology,
+        vec![
             Box::new(dns_score),
             Box::new(bootstrap_dhcp_score),
             Box::new(bootstrap_load_balancer_score),
@@ -140,6 +154,8 @@ async fn main() {
             Box::new(http_score),
             Box::new(ipxe_score),
             Box::new(dhcp_score),
-    ]);
-    harmony_tui::init(maestro).await.unwrap();
+        ],
+    )
+    .await
+    .unwrap();
 }

examples/ntfy/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "example-ntfy"
+edition = "2024"
+version.workspace = true
+readme.workspace = true
+license.workspace = true
+
+[dependencies]
+harmony = { version = "0.1.0", path = "../../harmony" }
+harmony_cli = { version = "0.1.0", path = "../../harmony_cli" }
+tokio.workspace = true
+url.workspace = true

examples/ntfy/src/main.rs

@@ -0,0 +1,18 @@
+use harmony::{
+    inventory::Inventory, modules::monitoring::ntfy::ntfy::NtfyScore, topology::K8sAnywhereTopology,
+};
+
+#[tokio::main]
+async fn main() {
+    harmony_cli::run(
+        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
+        vec![Box::new(NtfyScore {
+            namespace: "monitoring".to_string(),
+            host: "localhost".to_string(),
+        })],
+        None,
+    )
+    .await
+    .unwrap();
+}

examples/okd_installation/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "example-okd-install"
+edition = "2024"
+version.workspace = true
+readme.workspace = true
+license.workspace = true
+publish = false
+
+[dependencies]
+harmony = { path = "../../harmony" }
+harmony_cli = { path = "../../harmony_cli" }
+harmony_types = { path = "../../harmony_types" }
+harmony_secret = { path = "../../harmony_secret" }
+harmony_secret_derive = { path = "../../harmony_secret_derive" }
+cidr = { workspace = true }
+tokio = { workspace = true }
+harmony_macros = { path = "../../harmony_macros" }
+log = { workspace = true }
+env_logger = { workspace = true }
+url = { workspace = true }
+serde.workspace = true

examples/okd_installation/env.sh

@@ -0,0 +1,4 @@
+export HARMONY_SECRET_NAMESPACE=example-vms
+export HARMONY_SECRET_STORE=file
+export HARMONY_DATABASE_URL=sqlite://harmony_vms.sqlite RUST_LOG=info 
+export RUST_LOG=info

examples/okd_installation/src/main.rs

@@ -0,0 +1,26 @@
+mod topology;
+
+use crate::topology::{get_inventory, get_topology};
+use harmony::{
+    modules::okd::{installation::OKDInstallationScore, ipxe::OkdIpxeScore},
+    score::Score,
+    topology::HAClusterTopology,
+};
+
+#[tokio::main]
+async fn main() {
+    let inventory = get_inventory();
+    let topology = get_topology().await;
+
+    let scores: Vec<Box<dyn Score<HAClusterTopology>>> = vec![
+        Box::new(OkdIpxeScore {
+            kickstart_filename: "inventory.kickstart".to_string(),
+            harmony_inventory_agent: "cluster_ssh_key.pub".to_string(),
+            cluster_pubkey_filename: "harmony_inventory_agent".to_string(),
+        }),
+        Box::new(OKDInstallationScore {}),
+    ];
+    harmony_cli::run(inventory, topology, scores, None)
+        .await
+        .unwrap();
+}

examples/okd_installation/src/topology.rs

@@ -0,0 +1,77 @@
+use cidr::Ipv4Cidr;
+use harmony::{
+    hardware::{FirewallGroup, HostCategory, Location, PhysicalHost, SwitchGroup},
+    infra::opnsense::OPNSenseManagementInterface,
+    inventory::Inventory,
+    topology::{HAClusterTopology, LogicalHost, UnmanagedRouter},
+};
+use harmony_macros::{ip, ipv4};
+use harmony_secret::{Secret, SecretManager};
+use serde::{Deserialize, Serialize};
+use std::{net::IpAddr, sync::Arc};
+
+#[derive(Secret, Serialize, Deserialize, Debug, PartialEq)]
+struct OPNSenseFirewallConfig {
+    username: String,
+    password: String,
+}
+
+pub async fn get_topology() -> HAClusterTopology {
+    let firewall = harmony::topology::LogicalHost {
+        ip: ip!("192.168.1.1"),
+        name: String::from("opnsense-1"),
+    };
+
+    let config = SecretManager::get::<OPNSenseFirewallConfig>().await;
+    let config = config.unwrap();
+
+    let opnsense = Arc::new(
+        harmony::infra::opnsense::OPNSenseFirewall::new(
+            firewall,
+            None,
+            &config.username,
+            &config.password,
+        )
+        .await,
+    );
+    let lan_subnet = ipv4!("192.168.1.0");
+    let gateway_ipv4 = ipv4!("192.168.1.1");
+    let gateway_ip = IpAddr::V4(gateway_ipv4);
+    harmony::topology::HAClusterTopology {
+        domain_name: "demo.harmony.mcd".to_string(),
+        router: Arc::new(UnmanagedRouter::new(
+            gateway_ip,
+            Ipv4Cidr::new(lan_subnet, 24).unwrap(),
+        )),
+        load_balancer: opnsense.clone(),
+        firewall: opnsense.clone(),
+        tftp_server: opnsense.clone(),
+        http_server: opnsense.clone(),
+        dhcp_server: opnsense.clone(),
+        dns_server: opnsense.clone(),
+        control_plane: vec![LogicalHost {
+            ip: ip!("192.168.1.20"),
+            name: "master".to_string(),
+        }],
+        bootstrap_host: LogicalHost {
+            ip: ip!("192.168.1.10"),
+            name: "bootstrap".to_string(),
+        },
+        workers: vec![],
+        switch: vec![],
+    }
+}
+
+pub fn get_inventory() -> Inventory {
+    Inventory {
+        location: Location::new(
+            "Some virtual machine or maybe a physical machine if you're cool".to_string(),
+            "testopnsense".to_string(),
+        ),
+        switch: SwitchGroup::from([]),
+        firewall_mgmt: Box::new(OPNSenseManagementInterface::new()),
+        storage_host: vec![],
+        worker_host: vec![],
+        control_plane_host: vec![],
+    }
+}

examples/okd_installation/ssh_example_key

@@ -0,0 +1,7 @@
+-----BEGIN OPENSSH PRIVATE KEY-----
+b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
+QyNTUxOQAAACAcemw8pbwuvHFaYynxBbS0Cf3ThYuj1Utr7CDqjwySHAAAAJikacCNpGnA
+jQAAAAtzc2gtZWQyNTUxOQAAACAcemw8pbwuvHFaYynxBbS0Cf3ThYuj1Utr7CDqjwySHA
+AAAECiiKk4V6Q5cVs6axDM4sjAzZn/QCZLQekmYQXS9XbEYxx6bDylvC68cVpjKfEFtLQJ
+/dOFi6PVS2vsIOqPDJIcAAAAEGplYW5nYWJAbGlsaWFuZTIBAgMEBQ==
+-----END OPENSSH PRIVATE KEY-----

examples/okd_installation/ssh_example_key.pub

@@ -0,0 +1 @@
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBx6bDylvC68cVpjKfEFtLQJ/dOFi6PVS2vsIOqPDJIc jeangab@liliane2

examples/okd_pxe/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "example-pxe"
+edition = "2024"
+version.workspace = true
+readme.workspace = true
+license.workspace = true
+publish = false
+
+[dependencies]
+harmony = { path = "../../harmony" }
+harmony_cli = { path = "../../harmony_cli" }
+harmony_types = { path = "../../harmony_types" }
+harmony_secret = { path = "../../harmony_secret" }
+harmony_secret_derive = { path = "../../harmony_secret_derive" }
+cidr = { workspace = true }
+tokio = { workspace = true }
+harmony_macros = { path = "../../harmony_macros" }
+log = { workspace = true }
+env_logger = { workspace = true }
+url = { workspace = true }
+serde.workspace = true

examples/okd_pxe/src/main.rs

@@ -0,0 +1,24 @@
+mod topology;
+
+use crate::topology::{get_inventory, get_topology};
+use harmony::modules::okd::ipxe::OkdIpxeScore;
+
+#[tokio::main]
+async fn main() {
+    let inventory = get_inventory();
+    let topology = get_topology().await;
+
+    let kickstart_filename = "inventory.kickstart".to_string();
+    let cluster_pubkey_filename = "cluster_ssh_key.pub".to_string();
+    let harmony_inventory_agent = "harmony_inventory_agent".to_string();
+
+    let ipxe_score = OkdIpxeScore {
+        kickstart_filename,
+        harmony_inventory_agent,
+        cluster_pubkey_filename,
+    };
+
+    harmony_cli::run(inventory, topology, vec![Box::new(ipxe_score)], None)
+        .await
+        .unwrap();
+}

examples/okd_pxe/src/topology.rs

@@ -0,0 +1,71 @@
+use cidr::Ipv4Cidr;
+use harmony::{
+    config::secret::OPNSenseFirewallCredentials,
+    hardware::{Location, SwitchGroup},
+    infra::opnsense::OPNSenseManagementInterface,
+    inventory::Inventory,
+    topology::{HAClusterTopology, LogicalHost, UnmanagedRouter},
+};
+use harmony_macros::{ip, ipv4};
+use harmony_secret::SecretManager;
+use std::{net::IpAddr, sync::Arc};
+
+pub async fn get_topology() -> HAClusterTopology {
+    let firewall = harmony::topology::LogicalHost {
+        ip: ip!("192.168.1.1"),
+        name: String::from("opnsense-1"),
+    };
+
+    let config = SecretManager::get::<OPNSenseFirewallCredentials>().await;
+    let config = config.unwrap();
+
+    let opnsense = Arc::new(
+        harmony::infra::opnsense::OPNSenseFirewall::new(
+            firewall,
+            None,
+            &config.username,
+            &config.password,
+        )
+        .await,
+    );
+    let lan_subnet = ipv4!("192.168.1.0");
+    let gateway_ipv4 = ipv4!("192.168.1.1");
+    let gateway_ip = IpAddr::V4(gateway_ipv4);
+    harmony::topology::HAClusterTopology {
+        domain_name: "demo.harmony.mcd".to_string(),
+        router: Arc::new(UnmanagedRouter::new(
+            gateway_ip,
+            Ipv4Cidr::new(lan_subnet, 24).unwrap(),
+        )),
+        load_balancer: opnsense.clone(),
+        firewall: opnsense.clone(),
+        tftp_server: opnsense.clone(),
+        http_server: opnsense.clone(),
+        dhcp_server: opnsense.clone(),
+        dns_server: opnsense.clone(),
+        control_plane: vec![LogicalHost {
+            ip: ip!("10.100.8.20"),
+            name: "cp0".to_string(),
+        }],
+        bootstrap_host: LogicalHost {
+            ip: ip!("10.100.8.20"),
+            name: "cp0".to_string(),
+        },
+        workers: vec![],
+        switch: vec![],
+    }
+}
+
+pub fn get_inventory() -> Inventory {
+    Inventory {
+        location: Location::new(
+            "Some virtual machine or maybe a physical machine if you're cool".to_string(),
+            "testopnsense".to_string(),
+        ),
+        switch: SwitchGroup::from([]),
+        firewall_mgmt: Box::new(OPNSenseManagementInterface::new()),
+        storage_host: vec![],
+        worker_host: vec![],
+        control_plane_host: vec![],
+    }
+}

examples/okd_pxe/ssh_example_key

@@ -0,0 +1,7 @@
+-----BEGIN OPENSSH PRIVATE KEY-----
+b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
+QyNTUxOQAAACAcemw8pbwuvHFaYynxBbS0Cf3ThYuj1Utr7CDqjwySHAAAAJikacCNpGnA
+jQAAAAtzc2gtZWQyNTUxOQAAACAcemw8pbwuvHFaYynxBbS0Cf3ThYuj1Utr7CDqjwySHA
+AAAECiiKk4V6Q5cVs6axDM4sjAzZn/QCZLQekmYQXS9XbEYxx6bDylvC68cVpjKfEFtLQJ
+/dOFi6PVS2vsIOqPDJIcAAAAEGplYW5nYWJAbGlsaWFuZTIBAgMEBQ==
+-----END OPENSSH PRIVATE KEY-----

examples/okd_pxe/ssh_example_key.pub

@@ -0,0 +1 @@
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBx6bDylvC68cVpjKfEFtLQJ/dOFi6PVS2vsIOqPDJIc jeangab@liliane2

examples/opnsense/src/main.rs

@@ -8,17 +8,17 @@ use harmony::{
     hardware::{FirewallGroup, HostCategory, Location, PhysicalHost, SwitchGroup},
     infra::opnsense::OPNSenseManagementInterface,
     inventory::Inventory,
-    maestro::Maestro,
     modules::{
         dummy::{ErrorScore, PanicScore, SuccessScore},
-        http::HttpScore,
+        http::StaticFilesHttpScore,
         okd::{dhcp::OKDDhcpScore, dns::OKDDnsScore, load_balancer::OKDLoadBalancerScore},
         opnsense::OPNsenseShellCommandScore,
         tftp::TftpScore,
     },
-    topology::{LogicalHost, UnmanagedRouter, Url},
+    topology::{LogicalHost, UnmanagedRouter},
 };
 use harmony_macros::{ip, mac_address};
+use harmony_types::net::Url;
 
 #[tokio::main]
 async fn main() {
@@ -63,8 +63,7 @@ async fn main() {
             "wk".to_string(),
         ),
         switch: SwitchGroup::from([]),
-        firewall: FirewallGroup::from([PhysicalHost::empty(HostCategory::Firewall)
-            .management(Arc::new(OPNSenseManagementInterface::new()))]),
+        firewall_mgmt: Box::new(OPNSenseManagementInterface::new()),
         storage_host: vec![],
         worker_host: vec![],
         control_plane_host: vec![
@@ -81,11 +80,18 @@ async fn main() {
     let load_balancer_score = OKDLoadBalancerScore::new(&topology);
 
     let tftp_score = TftpScore::new(Url::LocalFolder("./data/watchguard/tftpboot".to_string()));
-    let http_score = HttpScore::new(Url::LocalFolder(
+    let http_score = StaticFilesHttpScore {
+        folder_to_serve: Some(Url::LocalFolder(
             "./data/watchguard/pxe-http-files".to_string(),
-    ));
-    let mut maestro = Maestro::initialize(inventory, topology).await.unwrap();
-    maestro.register_all(vec![
+        )),
+        files: vec![],
+        remote_path: None,
+    };
+
+    harmony_tui::run(
+        inventory,
+        topology,
+        vec![
             Box::new(dns_score),
             Box::new(dhcp_score),
             Box::new(load_balancer_score),
@@ -98,6 +104,8 @@ async fn main() {
             Box::new(SuccessScore {}),
             Box::new(ErrorScore {}),
             Box::new(PanicScore {}),
-    ]);
-    harmony_tui::init(maestro).await.unwrap();
+        ],
+    )
+    .await
+    .unwrap();
 }

examples/rust/.gitignore

@@ -0,0 +1,3 @@
+Dockerfile.harmony
+.harmony_generated
+harmony

examples/rust/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "example-rust"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+harmony = { path = "../../harmony" }
+harmony_cli = { path = "../../harmony_cli" }
+harmony_types = { path = "../../harmony_types" }
+harmony_macros = { path = "../../harmony_macros" }
+tokio = { workspace = true }
+log = { workspace = true }
+env_logger = { workspace = true }
+url = { workspace = true }
+base64.workspace = true

examples/rust/src/main.rs

@@ -0,0 +1,59 @@
+use std::{path::PathBuf, sync::Arc};
+
+use harmony::{
+    inventory::Inventory,
+    modules::{
+        application::{
+            ApplicationScore, RustWebFramework, RustWebapp,
+            features::{ContinuousDelivery, Monitoring},
+        },
+        monitoring::alert_channel::{
+            discord_alert_channel::DiscordWebhook, webhook_receiver::WebhookReceiver,
+        },
+    },
+    topology::K8sAnywhereTopology,
+};
+use harmony_types::net::Url;
+
+#[tokio::main]
+async fn main() {
+    let application = Arc::new(RustWebapp {
+        name: "harmony-example-rust-webapp".to_string(),
+        domain: Url::Url(url::Url::parse("https://rustapp.harmony.example.com").unwrap()),
+        project_root: PathBuf::from("./webapp"), // Relative from 'harmony-path' param
+        framework: Some(RustWebFramework::Leptos),
+    });
+
+    let discord_receiver = DiscordWebhook {
+        name: "test-discord".to_string(),
+        url: Url::Url(url::Url::parse("https://discord.doesnt.exist.com").unwrap()),
+    };
+
+    let webhook_receiver = WebhookReceiver {
+        name: "sample-webhook-receiver".to_string(),
+        url: Url::Url(url::Url::parse("https://webhook-doesnt-exist.com").unwrap()),
+    };
+
+    let app = ApplicationScore {
+        features: vec![
+            Box::new(ContinuousDelivery {
+                application: application.clone(),
+            }),
+            Box::new(Monitoring {
+                application: application.clone(),
+                alert_receiver: vec![Box::new(discord_receiver), Box::new(webhook_receiver)],
+            }),
+            // TODO add backups, multisite ha, etc
+        ],
+        application,
+    };
+
+    harmony_cli::run(
+        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
+        vec![Box::new(app)],
+        None,
+    )
+    .await
+    .unwrap();
+}

examples/rust/webapp/.gitignore

@@ -0,0 +1,14 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb

examples/rust/webapp/Cargo.toml

@@ -0,0 +1,93 @@
+[package]
+name = "harmony-example-rust-webapp"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[workspace]
+
+[dependencies]
+actix-files = { version = "0.6", optional = true }
+actix-web = { version = "4", optional = true, features = ["macros"] }
+console_error_panic_hook = "0.1"
+http = { version = "1.0.0", optional = true }
+leptos = { version = "0.7.0" }
+leptos_meta = { version = "0.7.0" }
+leptos_actix = { version = "0.7.0", optional = true }
+leptos_router = { version = "0.7.0" }
+wasm-bindgen = "=0.2.100"
+
+[features]
+csr = ["leptos/csr"]
+hydrate = ["leptos/hydrate"]
+ssr = [
+  "dep:actix-files",
+  "dep:actix-web",
+  "dep:leptos_actix",
+  "leptos/ssr",
+  "leptos_meta/ssr",
+  "leptos_router/ssr",
+]
+
+# Defines a size-optimized profile for the WASM bundle in release mode
+[profile.wasm-release]
+inherits = "release"
+opt-level = 'z'
+lto = true
+codegen-units = 1
+panic = "abort"
+
+[package.metadata.leptos]
+# The name used by wasm-bindgen/cargo-leptos for the JS/WASM bundle. Defaults to the crate name
+output-name = "harmony-example-rust-webapp"
+# The site root folder is where cargo-leptos generate all output. WARNING: all content of this folder will be erased on a rebuild. Use it in your server setup.
+site-root = "target/site"
+# The site-root relative folder where all compiled output (JS, WASM and CSS) is written
+# Defaults to pkg
+site-pkg-dir = "pkg"
+# [Optional] The source CSS file. If it ends with .sass or .scss then it will be compiled by dart-sass into CSS. The CSS is optimized by Lightning CSS before being written to <site-root>/<site-pkg>/app.css
+style-file = "style/main.scss"
+# Assets source dir. All files found here will be copied and synchronized to site-root.
+# The assets-dir cannot have a sub directory with the same name/path as site-pkg-dir.
+#
+# Optional. Env: LEPTOS_ASSETS_DIR.
+assets-dir = "assets"
+# The IP and port (ex: 127.0.0.1:3000) where the server serves the content. Use it in your server setup.
+site-addr = "0.0.0.0:3000"
+# The port to use for automatic reload monitoring
+reload-port = 3001
+# [Optional] Command to use when running end2end tests. It will run in the end2end dir.
+#   [Windows] for non-WSL use "npx.cmd playwright test"
+#   This binary name can be checked in Powershell with Get-Command npx
+end2end-cmd = "npx playwright test"
+end2end-dir = "end2end"
+#  The browserlist query used for optimizing the CSS.
+browserquery = "defaults"
+# The environment Leptos will run in, usually either "DEV" or "PROD"
+env = "DEV"
+# The features to use when compiling the bin target
+#
+# Optional. Can be over-ridden with the command line parameter --bin-features
+bin-features = ["ssr"]
+
+# If the --no-default-features flag should be used when compiling the bin target
+#
+# Optional. Defaults to false.
+bin-default-features = false
+
+# The features to use when compiling the lib target
+#
+# Optional. Can be over-ridden with the command line parameter --lib-features
+lib-features = ["hydrate"]
+
+# If the --no-default-features flag should be used when compiling the lib target
+#
+# Optional. Defaults to false.
+lib-default-features = false
+
+# The profile to use for the lib target when compiling for release
+#
+# Optional. Defaults to "release".
+lib-profile-release = "wasm-release"

examples/rust/webapp/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

examples/rust/webapp/README.md

@@ -0,0 +1,72 @@
+<picture>
+    <source srcset="https://raw.githubusercontent.com/leptos-rs/leptos/main/docs/logos/Leptos_logo_Solid_White.svg" media="(prefers-color-scheme: dark)">
+    <img src="https://raw.githubusercontent.com/leptos-rs/leptos/main/docs/logos/Leptos_logo_RGB.svg" alt="Leptos Logo">
+</picture>
+
+# Leptos Starter Template
+
+This is a template for use with the [Leptos](https://github.com/leptos-rs/leptos) web framework and the [cargo-leptos](https://github.com/akesson/cargo-leptos) tool.
+
+## Creating your template repo
+
+If you don't have `cargo-leptos` installed you can install it with
+
+`cargo install cargo-leptos --locked`
+
+Then run
+
+`cargo leptos new --git leptos-rs/start-actix`
+
+to generate a new project template (you will be prompted to enter a project name).
+
+`cd {projectname}`
+
+to go to your newly created project.
+
+Of course, you should explore around the project structure, but the best place to start with your application code is in `src/app.rs`.
+
+## Running your project
+
+`cargo leptos watch`  
+By default, you can access your local project at `http://localhost:3000`
+
+## Installing Additional Tools
+
+By default, `cargo-leptos` uses `nightly` Rust, `cargo-generate`, and `sass`. If you run into any trouble, you may need to install one or more of these tools.
+
+1. `rustup toolchain install nightly --allow-downgrade` - make sure you have Rust nightly
+2. `rustup target add wasm32-unknown-unknown` - add the ability to compile Rust to WebAssembly
+3. `cargo install cargo-generate` - install `cargo-generate` binary (should be installed automatically in future)
+4. `npm install -g sass` - install `dart-sass` (should be optional in future)
+
+## Executing a Server on a Remote Machine Without the Toolchain
+After running a `cargo leptos build --release` the minimum files needed are:
+
+1. The server binary located in `target/server/release`
+2. The `site` directory and all files within located in `target/site`
+
+Copy these files to your remote server. The directory structure should be:
+```text
+leptos_start
+site/
+```
+Set the following environment variables (updating for your project as needed):
+```sh
+export LEPTOS_OUTPUT_NAME="leptos_start"
+export LEPTOS_SITE_ROOT="site"
+export LEPTOS_SITE_PKG_DIR="pkg"
+export LEPTOS_SITE_ADDR="127.0.0.1:3000"
+export LEPTOS_RELOAD_PORT="3001"
+```
+Finally, run the server binary.
+
+## Notes about CSR and Trunk:
+Although it is not recommended, you can also run your project without server integration using the feature `csr` and `trunk serve`:
+
+`trunk serve --open --features csr`
+
+This may be useful for integrating external tools which require a static site, e.g. `tauri`.
+
+## Licensing
+
+This template itself is released under the Unlicense. You should replace the LICENSE for your own application with an appropriate license if you plan to release it publicly.