Install

Install the operatorsCopy Anchor Link

Install cert-manager and the CloudNativePG operator with their own charts. Put the operator into cnpg-system, which networkPolicy.cnpgNamespaceSelector expects.

Point DNS at the ingressCopy Anchor Link

Create records for console.example.com and *.example.net that resolve to your Ingress controller's load balancer. DNS and TLS has the details.

Create the sign-in clientCopy Anchor Link

At your OIDC provider, create a confidential client with:

• redirect URI https://console.example.com/auth/oidc/callback;
• the scopes openid profile email groups;
• a group, for example harthelm-admins, for the people who administer Harthelm.

Then store its id and secret:

kubectl create namespace harthelm-system
kubectl label namespace harthelm-system pod-security.kubernetes.io/enforce=restricted
kubectl -n harthelm-system create secret generic harthelm-oidc \
  --from-literal=clientID=<client id> --from-literal=clientSecret=<client secret>

Provider notes are in Sign-in.

Create the master keyCopy Anchor Link

The master key encrypts every stored token and secret: a restored database is useless without it. Core generates one on first start unless you bring your own; create it yourself so it is in your secret store from the start:

kubectl -n harthelm-system create secret generic harthelm-master-key \
  --from-literal=active=k1 --from-literal=key.k1="$(openssl rand -base64 32)"

With masterKey.existingSecret set, core refuses to generate another one. Keep a copy outside the cluster.

Store the licenceCopy Anchor Link

Every installation needs a licence; without one it starts restricted and refuses new teams and workspaces. Put the file into a Secret:

kubectl -n harthelm-system create secret generic harthelm-license --from-file=license=company.license

The values below name it. The preflight checks it with the keys of the release you install. You can also install the licence later in the console or with hart; Licence has the three ways. A licence that names an installation needs its id first: see Order of a fresh install.

Write the valuesCopy Anchor Link

platform:
  host: console.example.com
  workspaceDomain: example.net

# The ingress controller's pods, so limits and audit rows see the real client address.
trustedProxies: [10.0.0.0/16]

routing:
  edge: ingress
  ingress:
    className: public
  tls:
    certManager:
      enabled: true
      issuerRef: {name: letsencrypt-dns, kind: ClusterIssuer, group: cert-manager.io}

oidc:
  issuer: https://id.example.com/
  displayName: Example ID          # the button says "Sign in with Example ID"
  adminGroup: harthelm-admins      # members are cluster admins of Harthelm
  existingSecret: harthelm-oidc

masterKey:
  existingSecret: harthelm-master-key

license:
  existingSecret: harthelm-license

storage:
  class: ""                        # the default StorageClass
  mode: auto

customDomains:
  cnameTarget: edge.example.net    # resolves to your ingress; users CNAME their domains to it
  issuer: {name: letsencrypt-http, kind: ClusterIssuer, group: cert-manager.io}

backup:
  enabled: true
  workspaces:
    enabled: true

Every key is in the chart values reference. The schema is strict: an unknown key or a missing required value fails the render.

Render, then installCopy Anchor Link

helm template harthelm oci://<your registry>/charts/harthelm --version <version> \
  -n harthelm-system -f my-values.yaml > /dev/null
helm install harthelm oci://<your registry>/charts/harthelm --version <version> \
  -n harthelm-system -f my-values.yaml

The preflight Job runs first and fails the install with a list of what is missing: an operator, a Secret, a StorageClass, an issuer, a licence this release accepts. Read it with:

kubectl -n harthelm-system logs job/harthelm-preflight

Then the database comes up, core migrates it (it has up to 5 minutes at the first start) and the routers start.

Prove the network policiesCopy Anchor Link

helm test harthelm -n harthelm-system

A probe checks that the NetworkPolicies are enforced, port ranges included. It fails when they are not. Run it again after every CNI change.

Sign inCopy Anchor Link

Open https://console.example.com and click Sign in with Example ID as a member of harthelm-admins. Every installation starts with the organization Default and its team Default (tenancy.defaultOrg, tenancy.defaultTeam). From here, Team administration shows how to create organizations and teams and invite people.

Check the installationCopy Anchor Link

Sign in with hart as a cluster admin and run the doctor:

hart login --api https://console.example.com
hart admin doctor --capabilities

Every check should pass, the last one, license, included; Troubleshooting explains each one. The console shows what the cluster offers under Platform → Capabilities and, since 1.5.0, runs the checks themselves under Platform → Doctor (The Doctor page).

From Harthelm 1.2 on, hart smoke then walks the path a user takes, end to end: it creates a scratch workspace in a team, writes a small app into it, sets an env var, runs Sync, prepare and Run, waits until the app answers on the workspace's dev URL, and deletes the workspace again (purged with a team admin's key):

hart smoke --team 1

It passes in well under a minute, needs nothing from the internet, and a member with the Developer role may run it too. A failure names the step that failed; --keep leaves the workspace for a look and -o json prints every step. Then create a first workspace as a test user with the Quickstart.