Docs/Hearth/Install

Install

A single bash script bootstraps everything: the hearth CLI, every external binary, an age key for secrets, every sibling repo, and the dev compose stack.

Prerequisites

Hearth manages everything else, but these four tools have to be on the host already.

Tool	Why	Install
`git`	Clone repos	system package manager
`docker`	Run the dev stack	https://docs.docker.com/get-docker/
`python3` (≥ 3.10)	Hearth CLI is Python	system package manager
`ssh`	Clone private repos	included with most systems

Everything else (sops, age, age-keygen, kubectl, yq, the hearth CLI itself) is installed automatically into ~/.katforge/.

Run the installer

shell

git clone git@github.com:katforge/hearth.git ~/.katforge/hearth
~/.katforge/hearth/install.sh

The installer is idempotent — running it again is safe and only fixes what's missing.

What it does

Verifies prerequisites — git, docker, python3 ≥ 3.10, ssh.
Verifies your GitHub SSH access — early failure beats a confusing clone error halfway through.
Sets up ~/.katforge/ as the canonical install root for everything that follows. Override with KATFORGE_ROOT=... before running.
Creates ~/.katforge/.venv and installs the hearth Python CLI into it.
Symlinks hearth into ~/.katforge/bin/ and adds that to your PATH via an idempotent block in ~/.bashrc or ~/.zshrc.
Downloads single-file binaries — sops, age, age-keygen, kubectl, yq — into ~/.katforge/bin/.
Generates an age key at ~/.katforge/age.txt and prints your public key.
Clones every sibling repo and package into ~/.katforge/.
Symlinks ~/Projects/katforge → ~/.katforge so editor and terminal habits keep working.
Starts the dev compose stack.

After install

The installer adds ~/.katforge/bin to your PATH and sets SOPS_AGE_KEY_FILE via your shell rc. Existing shells won't see them. Open a new terminal before running any hearth command.

Every KATforge workflow is hearth <command>:

shell

hearth status
hearth secret list dev
hearth team whoami

Get authorized for secrets

The installer generated an age public key. Share it with a maintainer:

shell

hearth team whoami
# → age1abc...

A maintainer adds you:

shell

hearth team add age1abc...

That re-encrypts every secret file to include you as a recipient. Pull, and you can decrypt. See Secrets for the full model.

Configurable env vars

Set these before running install.sh to override defaults.

Variable	Default	Effect
`KATFORGE_ROOT`	`$HOME/.katforge`	Install root. Everything lives under this directory.
`HEARTH_REF`	`main`	Branch or tag of hearth to check out.
`HEARTH_REPO`	`git@github.com:katforge/hearth.git`	Git URL for hearth itself.

Uninstall

shell

rm -rf ~/.katforge ~/Projects/katforge

Then remove the # === BEGIN katforge === block from your ~/.bashrc or ~/.zshrc.

← PreviousHearth Next →Filesystem