1. Prerequisites
Five things you need before you install. Have them ready and the install itself takes minutes.
Required
Section titled “Required”| Thing | Minimum |
|---|---|
| Kubernetes cluster | v1.28+, one node, a default storage class |
| Helm or Terraform | Helm 4.0+ for the chart path, Terraform 1.5+ for the module path |
kubectl | configured against the cluster |
| DNS | a domain or subdomain pointing at the cluster’s ingress IP (e.g. shoehorn.acme.com) |
| Identity provider | one of Zitadel, Okta, or Entra ID. Set up the OIDC application before you start. |
| GitHub App | Shoehorn discovers your repositories, reads .shoehorn/manifest.yml files, and tracks PR activity for engineering insights. Create the GitHub App and install it on your org before you start. See GitHub integration. |
Optional
Section titled “Optional”| Thing | Why |
|---|---|
| Forge GitHub App | A separate GitHub App used by Forge workflows that create repositories, write files, or open pull requests. Only needed if you plan to use Forge for self-service automation. |
| Cert-manager | Issues TLS certs for the ingress. See TLS with cert-manager. |
| External Postgres | Use your managed Postgres instead of the chart-deployed one. The Helm chart and the Terraform module both support it. |
Heads-up on cluster size
Section titled “Heads-up on cluster size”Every service ships with a single replica by default. That fits a small cluster (one or two nodes) just fine. Scale the stateless services up (API, Web, Worker, Crawler, Forge) when you want HA. Two replicas plus a surge for rolling upgrades is the usual starting point; tune to your SLO and cluster capacity.