Skip to content
Shoehorn

Quick Start

Install Shoehorn with Helm. Configure the platform and manage catalog content with the official Terraform provider.

1. Install with Helm

Section titled “1. Install with Helm”

Shoehorn images are public on Docker Hub under shoehorned/. No pull secret needed.

Terminal window
kubectl create namespace shoehorn

Create a minimal values.yaml:

global:
  domain: shoehorn.example.com
  organization:
    name: "Acme Corp"
    slug: "acme-corp"


image:
  tag: "v0.7.0"


auth:
  provider: zitadel
  zitadel:
    externalUrl: https://auth.example.com
    projectId: "<zitadel-project-id>"
    clientId: "<zitadel-client-id>"

Install the chart:

Terminal window
helm install shoehorn oci://ghcr.io/shoehorn-dev/helm-charts/shoehorn \
  --version 0.7.0 \
  --namespace shoehorn \
  -f values.yaml

Full reference: Deploying with Helm. Chart source and changelog: github.com/shoehorn-dev/helm-charts.

2. Verify

Section titled “2. Verify”
Terminal window
kubectl get pods -n shoehorn
kubectl port-forward -n shoehorn svc/api 8080:8080
curl http://localhost:8080/health

Once pods are Running, sign in at https://shoehorn.example.com through your identity provider.

3. Configure the platform with Terraform

Section titled “3. Configure the platform with Terraform”

The official Terraform provider configures the running platform and manages catalog content as code: integrations (GitHub, Okta, Zitadel), tenant settings, IdP group-to-role mappings, K8s agent registration, policies, API keys, teams, and entities.

terraform {
  required_providers {
    shoehorn = {
      source  = "shoehorn-dev/shoehorn"
      version = "~> 0.1"
    }
  }
}


provider "shoehorn" {
  endpoint = "https://shoehorn.example.com"
  api_key  = var.shoehorn_api_key
}


resource "shoehorn_integration" "github" {
  type   = "github"
  config = {
    appId          = "1234567"
    installationId = "98765432"
    organizations  = "acme-corp"
  }
}


resource "shoehorn_team" "platform" {
  slug = "platform"
  name = "Platform Team"
}


resource "shoehorn_group_role_mapping" "admins" {
  group = "shoehorn-admins"
  role  = "admin"
}

Provider docs and the full resource reference: registry.terraform.io/providers/shoehorn-dev/shoehorn/latest.

4. Connect a Kubernetes cluster

Section titled “4. Connect a Kubernetes cluster”

To pull workloads into the catalog, deploy the K8s agent. See K8s Agent.

5. Register your first entity

Section titled “5. Register your first entity”

Via manifest

Section titled “Via manifest”

Drop .shoehorn/manifest.yml in any repo Shoehorn watches:

schemaVersion: 1


service:
  id: my-first-service
  name: My First Service
  type: service
  tier: gold


owner:
  - type: team
    id: platform-team


lifecycle: production


links:
  - name: Repository
    url: https://github.com/your-org/my-first-service
    icon: GitHub

GitHub integration picks up manifests automatically. See Manifests.

Via API

Section titled “Via API”
Terminal window
curl -X POST https://shoehorn.example.com/api/v1/entities \
  -H "Authorization: Bearer $SHOEHORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-service",
    "type": "service",
    "lifecycle": "production",
    "owner": "platform-team"
  }'

Cloud partners

Section titled “Cloud partners”

Cloud partners (UpCloud and others) ship a turnkey Shoehorn deployment via the shoehorn-dev/terraform-shoehorn-modules Terraform modules. Talk to your cloud provider if you want a one-click install rather than running Helm yourself.

Next steps

Section titled “Next steps”