harmony/docs/guides/getting-started.md

# Getting Started Guide

This guide walks you through deploying your first application with Harmony — a PostgreSQL cluster on a local Kubernetes cluster (K3D). By the end, you'll understand the core workflow: compile a Score, run it through the Harmony CLI, and verify the result.

## What you'll deploy

A fully functional PostgreSQL cluster running in a local K3D cluster, managed by the CloudNativePG operator. This demonstrates the full Harmony pattern:

1. Provision a local Kubernetes cluster (K3D)
2. Install the required operator (CloudNativePG)
3. Create a PostgreSQL cluster
4. Expose it as a Kubernetes Service

## Prerequisites

Before you begin, install the following tools:

- **Rust & Cargo:** [Install Rust](https://rust-lang.org/tools/install) (edition 2024)
- **Docker:** [Install Docker](https://docs.docker.com/get-docker/) (required for the local K3D cluster)
- **kubectl:** [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (optional, for inspecting the cluster)

## Step 1: Clone and build

```bash
# Clone the repository
git clone https://git.nationtech.io/nationtech/harmony
cd harmony

# Build the project (this may take a few minutes on first run)
cargo build --release
```

## Step 2: Run the PostgreSQL example

```bash
cargo run -p example-postgresql
```

Harmony will output its progress as it:

1. **Creates a K3D cluster** named `harmony-postgres-example` (first run only)
2. **Installs the CloudNativePG operator** into the cluster
3. **Creates a PostgreSQL cluster** with 1 instance and 1 GiB of storage
4. **Prints connection details** for your new database

Expected output (abbreviated):

```
[+] Cluster created
[+] Installing CloudNativePG operator
[+] Creating PostgreSQL cluster
[+] PostgreSQL cluster is ready
    Namespace: harmony-postgres-example
    Service: harmony-postgres-example-rw
    Username: postgres
    Password: <stored in secret harmony-postgres-example-db-user>
```

## Step 3: Verify the deployment

Check that the PostgreSQL pods are running:

```bash
kubectl get pods -n harmony-postgres-example
```

You should see something like:

```
NAME                                    READY   STATUS    RESTARTS   AGE
harmony-postgres-example-1              1/1     Running   0          2m
```

Get the database password:

```bash
kubectl get secret -n harmony-postgres-example harmony-postgres-example-db-user -o jsonpath='{.data.password}' | base64 -d
```

## Step 4: Connect to the database

Forward the PostgreSQL port to your local machine:

```bash
kubectl port-forward -n harmony-postgres-example svc/harmony-postgres-example-rw 5432:5432
```

In another terminal, connect with `psql`:

```bash
psql -h localhost -p 5432 -U postgres
# Enter the password from Step 4 when prompted
```

Try a simple query:

```sql
SELECT version();
```

## Step 5: Clean up

To delete the PostgreSQL cluster and the local K3D cluster:

```bash
k3d cluster delete harmony-postgres-example
```

Alternatively, just delete the PostgreSQL cluster without removing K3D:

```bash
kubectl delete namespace harmony-postgres-example
```

## How it works

The example code (`examples/postgresql/src/main.rs`) is straightforward:

```rust
use harmony::{
    inventory::Inventory,
    modules::postgresql::{PostgreSQLScore, capability::PostgreSQLConfig},
    topology::K8sAnywhereTopology,
};

#[tokio::main]
async fn main() {
    let postgres = PostgreSQLScore {
        config: PostgreSQLConfig {
            cluster_name: "harmony-postgres-example".to_string(),
            namespace: "harmony-postgres-example".to_string(),
            ..Default::default()
        },
    };

    harmony_cli::run(
        Inventory::autoload(),
        K8sAnywhereTopology::from_env(),
        vec![Box::new(postgres)],
        None,
    )
    .await
    .unwrap();
}
```

- **`Inventory::autoload()`** discovers the local environment (or uses an existing inventory)
- **`K8sAnywhereTopology::from_env()`** connects to K3D if `HARMONY_AUTOINSTALL=true` (the default), or to any Kubernetes cluster via `KUBECONFIG`
- **`harmony_cli::run(...)`** executes the Score against the Topology, managing the full lifecycle

## Connecting to an existing cluster

By default, Harmony provisions a local K3D cluster. To use an existing Kubernetes cluster instead:

```bash
export KUBECONFIG=/path/to/your/kubeconfig
export HARMONY_USE_LOCAL_K3D=false
export HARMONY_AUTOINSTALL=false

cargo run -p example-postgresql
```

## Troubleshooting

### Docker is not running

```
Error: could not create cluster: docker is not running
```

Start Docker and try again.

### K3D cluster creation fails

```
Error: failed to create k3d cluster
```

Ensure you have at least 2 CPU cores and 4 GiB of RAM available for Docker.

### `kubectl` cannot connect to the cluster

```
error: unable to connect to a kubernetes cluster
```

After Harmony creates the cluster, it writes the kubeconfig to `~/.kube/config` or to the path in `KUBECONFIG`. Verify:

```bash
kubectl cluster-info --context k3d-harmony-postgres-example
```

### Port forward fails

```
error: unable to forward port
```

Make sure no other process is using port 5432, or use a different local port:

```bash
kubectl port-forward -n harmony-postgres-example svc/harmony-postgres-example-rw 15432:5432
psql -h localhost -p 15432 -U postgres
```

## Next steps

- [Explore the Scores Catalog](../catalogs/scores.md): See what other Scores are available
- [Explore the Topologies Catalog](../catalogs/topologies.md): See what infrastructure Topologies are supported
- [Read the Core Concepts](../concepts.md): Understand the Score / Topology / Interpret pattern in depth
- [OKD on Bare Metal](../use-cases/okd-on-bare-metal.md): See a complete bare-metal deployment example

## Advanced examples

Once you're comfortable with the basics, these examples demonstrate more advanced use cases. Note that some require specific infrastructure (existing Kubernetes clusters, bare-metal hardware, or multi-cluster environments):

| Example | Description | Prerequisites |
|---------|-------------|---------------|
| `monitoring` | Deploy Prometheus alerting with Discord webhooks | Existing K8s cluster |
| `ntfy` | Deploy ntfy notification server | Existing K8s cluster |
| `tenant` | Create a multi-tenant namespace with quotas | Existing K8s cluster |
| `cert_manager` | Provision TLS certificates | Existing K8s cluster |
| `validate_ceph_cluster_health` | Check Ceph cluster health | Existing Rook/Ceph cluster |
| `okd_pxe` / `okd_installation` | Provision OKD on bare metal | HAClusterTopology, bare-metal hardware |

To run any example:

```bash
cargo run -p example-<example_name>
```