Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Add trueforge Helm chart and release pipeline (#57)

Ajayi Dipob3bc1d4338f2
diff --git a/.github/workflows/release-image-and-chart.yml b/.github/workflows/release-image-and-chart.yml
new file mode 100644
index 000000000..14196c7ab
--- /dev/null
+++ b/.github/workflows/release-image-and-chart.yml
@@ -0,0 +1,164 @@
+name: Release image and Helm chart
+
+# Publishing a GitHub Release (tag vX.Y.Z) builds and pushes the server image,
+# then stamps that version into the Helm chart, packages it, pushes it to the
+# JFrog public OCI Helm repo, and attaches the .tgz to the release.
+on:
+ release:
+ types: [published]
+
+# One release at a time so the commit back to main and the chart push cannot race.
+# The group is intentionally tag-independent so releases of different tags
+# serialize instead of running in parallel.
+concurrency:
+ group: release-image-and-chart
+ cancel-in-progress: false
+
+permissions:
+ contents: read
+
+jobs:
+ # Derive the version from the release tag; it is the single source of truth for
+ # the image tag and the chart version/appVersion.
+ prepare:
+ name: Resolve release version
+ runs-on: ubuntu-latest
+ outputs:
+ version: ${{ steps.version.outputs.version }}
+ steps:
+ - name: Resolve version
+ id: version
+ env:
+ TAG: ${{ github.event.release.tag_name }}
+ run: |
+ set -euo pipefail
+ VERSION="${TAG#v}"
+ if ! printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$'; then
+ echo "Release tag '$TAG' is not a semver vX.Y.Z tag" >&2
+ exit 1
+ fi
+ echo "Releasing version $VERSION"
+ echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+ # Build and push the server image (API + UI) via the shared reusable workflow.
+ build:
+ name: Build and push server image
+ needs: [prepare]
+ uses: truefoundry/github-workflows-public/.github/workflows/build.yml@main
+ permissions:
+ id-token: write
+ contents: read
+ with:
+ artifactory_registry_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL }}
+ artifactory_repository_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY }}
+ image_artifact_name: trueforge
+ image_tag: ${{ needs.prepare.outputs.version }}
+ image_context: .
+ dockerfile_path: Dockerfile
+ platforms: linux/amd64,linux/arm64
+ # The chart pulls the server image from JFrog (values.yaml image.repository),
+ # so JFrog is the only publish target; public ECR stays off.
+ enable_jfrog: true
+ enable_public_ecr: false
+ secrets:
+ artifactory_username: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME }}
+ artifactory_password: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD }}
+
+ # Stamp the version into the chart, publish it, and attach the package to the release.
+ release-chart:
+ name: Package and publish Helm chart
+ needs: [prepare, build]
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ env:
+ VERSION: ${{ needs.prepare.outputs.version }}
+ CHART_DIR: charts/trueforge
+ HELM_REGISTRY_URL: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL }}
+ HELM_REGISTRY_USERNAME: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME }}
+ HELM_REGISTRY_PASSWORD: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD }}
+ HELM_CHART_REPOSITORY: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_HELM_REPOSITORY }}
+ steps:
+ # Package from the exact tagged commit so the published chart matches the
+ # release (the image build uses the same tag). main is checked out
+ # separately later, only for the version-bump commit.
+ - name: Check out release tag
+ uses: actions/checkout@v4
+ with:
+ ref: ${{ github.event.release.tag_name }}
+
+ - name: Install yq
+ run: |
+ sudo wget -q https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/bin/yq
+ sudo chmod +x /usr/bin/yq
+
+ - name: Install Helm
+ uses: azure/setup-helm@v4
+ with:
+ version: v3.16.4
+
+ # Pin the released version everywhere the chart references it.
+ - name: Stamp version into chart
+ run: |
+ set -euo pipefail
+ yq -i '.version = strenv(VERSION) | .appVersion = strenv(VERSION)' "$CHART_DIR/Chart.yaml"
+ yq -i '.image.tag = strenv(VERSION)' "$CHART_DIR/values.yaml"
+ echo "Stamped chart to $VERSION"
+
+ - name: Helm registry login
+ run: |
+ helm registry login -u "$HELM_REGISTRY_USERNAME" -p "$HELM_REGISTRY_PASSWORD" "$HELM_REGISTRY_URL"
+
+ # Fetch the postgresql/redis subcharts from the public Bitnami OCI archive,
+ # pinned by Chart.lock. The archive is public (no auth); the images those
+ # subcharts run are separately mirrored to JFrog via values.yaml.
+ - name: Build chart dependencies
+ run: helm dependency build "$CHART_DIR"
+
+ - name: Package and push chart
+ id: package
+ run: |
+ set -euo pipefail
+ CHART_NAME=$(yq -r '.name' "$CHART_DIR/Chart.yaml")
+ helm package "$CHART_DIR" --destination dist
+ PACKAGE="dist/${CHART_NAME}-${VERSION}.tgz"
+ echo "Pushing $PACKAGE to oci://$HELM_CHART_REPOSITORY"
+ helm push "$PACKAGE" "oci://$HELM_CHART_REPOSITORY"
+ echo "package=$PACKAGE" >> "$GITHUB_OUTPUT"
+
+ - name: Attach chart to the GitHub release
+ uses: softprops/action-gh-release@v2
+ with:
+ tag_name: ${{ github.event.release.tag_name }}
+ files: ${{ steps.package.outputs.package }}
+ fail_on_unmatched_files: true
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+ # Sync the checked-in chart on main with the released version. Uses its own
+ # main checkout (packaging above runs against the tag) and stamps main's
+ # current chart files rather than copying the tag's, so unrelated changes
+ # on main are preserved.
+ - name: Check out main for the version bump
+ uses: actions/checkout@v4
+ with:
+ ref: main
+ path: main-checkout
+
+ # Runs last so a rejected push to a protected main never blocks shipping
+ # the artifacts.
+ - name: Commit chart version bump to main
+ working-directory: main-checkout
+ run: |
+ set -euo pipefail
+ yq -i '.version = strenv(VERSION) | .appVersion = strenv(VERSION)' "$CHART_DIR/Chart.yaml"
+ yq -i '.image.tag = strenv(VERSION)' "$CHART_DIR/values.yaml"
+ if git diff --quiet -- "$CHART_DIR"; then
+ echo "Chart already at $VERSION; nothing to commit."
+ exit 0
+ fi
+ git config user.name "github-actions[bot]"
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+ git add "$CHART_DIR/Chart.yaml" "$CHART_DIR/values.yaml"
+ git commit -m "chore(chart): release trueforge $VERSION"
+ git push origin HEAD:main
diff --git a/.gitignore b/.gitignore
index e4809fb91..54635d570 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,6 @@ packages/server/src/catalog/mcpCatalog.gen.ts
packages/server/src/catalog/skillCatalog.gen.ts
packages/server/src/catalog/sandboxCatalog.gen.ts
data/
+# Helm subchart deps are fetched via `helm dependency build` (pinned by the
+# committed Chart.lock); the downloaded .tgz/dirs are not committed.
+charts/*/charts/
diff --git a/.prettierignore b/.prettierignore
index 4dc4f1bd7..270d72ecc 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -3,6 +3,8 @@ dist/
# Fern-generated: formatted by the generator, not by this repo's config.
packages/sdk/
fern/openapi/
+# Downloaded third-party Helm subcharts (Bitnami); not ours to reformat.
+charts/trueforge/charts/
coverage/
.turbo/
pnpm-lock.yaml
diff --git a/RELEASING.md b/RELEASING.md
index 4fac312d1..c77313bc4 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -147,3 +147,91 @@ Publish a real version when CI or teammates need it.
| Sourcemaps/declarationMap decision | packages/harness/tsup.config.ts, tsconfig.build.json |
| CONTRIBUTING / SECURITY / CODE_OF_CONDUCT / CODEOWNERS / CI for external PRs | .github/ |
| Secret-scan history, enable secret scanning + push protection, flip repo public | GitHub settings |
+
+---
+
+# Releasing the server image + Helm chart
+
+A separate pipeline ships the deployable artifacts: the server container image
+(API + UI, built from the root `Dockerfile`) and the `charts/trueforge` Helm
+chart. It is driven by `.github/workflows/release-image-and-chart.yml` and
+triggers when a **GitHub Release** is published (tag `vX.Y.Z`).
+
+## What the release tag drives
+
+The tag is the single source of truth. On `vX.Y.Z` the workflow:
+
+1. **Builds and pushes the image** via the shared reusable workflow
+ `truefoundry/github-workflows-public/.github/workflows/build.yml@main` to the
+ JFrog public Artifactory repo, tagged `X.Y.Z`. The chart pulls the image from
+ JFrog, so JFrog is the only publish target (public ECR is disabled).
+2. **Stamps the chart** — sets `version`, `appVersion`, and `image.tag` in
+ `charts/trueforge` to `X.Y.Z` and commits the bump back to `main`.
+3. **Publishes the chart** — packages `charts/trueforge` and pushes it to the
+ JFrog public OCI Helm repo, then attaches the `.tgz` to the GitHub release.
+
+## Per-release flow
+
+1. Cut the release from `main` (tag `vX.Y.Z`) via the GitHub Releases UI or:
+
+ ```bash
+ gh release create vX.Y.Z --target main --generate-notes
+ ```
+
+2. Watch the run under the repo's Actions tab. The image lands in JFrog, the
+ chart lands in the OCI Helm repo, and the `.tgz` is attached to the release.
+
+> Publishing a `vX.Y.Z` tag also triggers `release.yml` (the npm publish of
+> `@truefoundry/utils-core`), which requires the tag to match
+> `packages/harness/package.json`. Keep that version in lockstep when tagging.
+
+## Required repository configuration
+
+Org/repo **variables**: `TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL`,
+`TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY`,
+`TRUEFOUNDRY_ARTIFACTORY_PUBLIC_HELM_REPOSITORY`.
+
+Org/repo **secrets**: `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME`,
+`TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD`.
+
+## Bundled dependencies
+
+The chart bundles Postgres and Redis as optional Bitnami subcharts, declared in
+`charts/trueforge/Chart.yaml` against the public Bitnami OCI archive
+(`oci://registry-1.docker.io/bitnamicharts`) and pinned by the committed
+`Chart.lock`. The workflow fetches them with `helm dependency build` before
+packaging (the archive is public, no auth). Disable them with
+`postgresql.enabled=false` / `redis.enabled=false` to target external services.
+
+**Images vs charts.** Bitnami left the charts public but relocated their
+container images to `docker.io/bitnamilegacy` (frozen, no security updates). So
+`charts/trueforge/values.yaml` overrides the subchart images to pinned legacy
+tags mirrored to the TrueFoundry JFrog registry, and sets
+`global.security.allowInsecureImages: true` (required once the registry differs
+from Bitnami's default). Mirror the images once per pinned tag:
+
+```bash
+for img in \
+ postgresql:17.6.0-debian-12-r4 \
+ redis:8.2.1-debian-12-r0; do
+ crane copy "docker.io/bitnamilegacy/${img}" "tfy.jfrog.io/tfy-mirror/bitnamilegacy/${img}"
+done
+# If you enable metrics/volumePermissions, also mirror:
+# postgres-exporter:0.17.1-debian-12-r16 os-shell:12-debian-12-r51
+# redis-exporter:1.76.0-debian-12-r0
+```
+
+To bump a bundled version: change the version under `dependencies:` in
+`Chart.yaml`, run `pnpm chart:deps` to refresh `Chart.lock`, then update the
+matching `image.tag` in `values.yaml` and mirror that new legacy tag to JFrog.
+
+## Validating the chart locally
+
+Fetch the subchart deps first (public archive, no auth), then lint/template:
+
+```bash
+pnpm chart:deps # helm dependency build (writes charts/, uses Chart.lock)
+pnpm chart:lint # helm lint with charts/trueforge/ci/lint-values.yaml
+pnpm chart:template # render the manifests
+pnpm chart:package # package to dist/ (gitignored)
+```
diff --git a/charts/trueforge/.helmignore b/charts/trueforge/.helmignore
new file mode 100644
index 000000000..f4a51e721
--- /dev/null
+++ b/charts/trueforge/.helmignore
@@ -0,0 +1,8 @@
+# Patterns to ignore when building packages.
+.DS_Store
+.git/
+.gitignore
+*.tmproj
+.vscode/
+.idea/
+ci/
diff --git a/charts/trueforge/Chart.lock b/charts/trueforge/Chart.lock
new file mode 100644
index 000000000..2b8124b2f
--- /dev/null
+++ b/charts/trueforge/Chart.lock
@@ -0,0 +1,9 @@
+dependencies:
+- name: postgresql
+ repository: oci://registry-1.docker.io/bitnamicharts
+ version: 16.7.27
+- name: redis
+ repository: oci://registry-1.docker.io/bitnamicharts
+ version: 24.0.0
+digest: sha256:6a9a66cd177329b1829c9d3d79c6810b89f4394f0411c3cfcb78cba87ca057e7
+generated: "2026-08-05T20:23:02.606276+01:00"
diff --git a/charts/trueforge/Chart.yaml b/charts/trueforge/Chart.yaml
new file mode 100644
index 000000000..a99b3092b
--- /dev/null
+++ b/charts/trueforge/Chart.yaml
@@ -0,0 +1,31 @@
+apiVersion: v2
+name: trueforge
+description: TrueForge server (API + UI) served from a single container image.
+type: application
+# version (chart) and appVersion are stamped from the release tag by
+# .github/workflows/release-image-and-chart.yml; the committed values are the
+# last release.
+version: 0.0.1
+appVersion: "0.0.1"
+kubeVersion: ">=1.25.0-0"
+home: https://github.com/truefoundry/trueforge
+sources:
+ - https://github.com/truefoundry/trueforge
+maintainers:
+ - name: TrueFoundry
+ url: https://truefoundry.com
+# Postgres and Redis ship as optional bundled dependencies, pulled from the
+# public Bitnami OCI chart archive at build time (`helm dependency build`, pinned
+# via Chart.lock). The charts are still public, but the container images they
+# reference moved to docker.io/bitnamilegacy; values.yaml points those at the
+# TrueFoundry JFrog mirror. Disable either to use an external service via
+# externalPostgres / externalRedis.
+dependencies:
+ - name: postgresql
+ version: "16.7.27"
+ repository: oci://registry-1.docker.io/bitnamicharts
+ condition: postgresql.enabled
+ - name: redis
+ version: "24.0.0"
+ repository: oci://registry-1.docker.io/bitnamicharts
+ condition: redis.enabled
diff --git a/charts/trueforge/README.md b/charts/trueforge/README.md
new file mode 100644
index 000000000..5e44dbff5
--- /dev/null
+++ b/charts/trueforge/README.md
@@ -0,0 +1,101 @@
+# trueforge Helm chart
+
+Deploys the TrueForge server, a single container image that serves both the API
+and the UI (built from the repository-root `Dockerfile`).
+
+The chart version, `appVersion`, and `image.tag` are stamped from the Git tag by
+[`.github/workflows/release-image-and-chart.yml`](../../.github/workflows/release-image-and-chart.yml)
+when a GitHub Release is published, so the committed values reflect the last
+release.
+
+## Dependencies
+
+Postgres and Redis ship as **bundled** dependencies (the Bitnami `postgresql`
+and `redis` charts, pulled from the public Bitnami OCI archive and pinned by
+`Chart.lock`). They are enabled by default, so a basic install only needs
+`server.publicBaseUrl`. The chart wires the server's `POSTGRES_*` and
+`REDIS_URL` env to the bundled services automatically.
+
+The Bitnami **charts** are still public, but the **container images** they
+reference were moved to `docker.io/bitnamilegacy`, so `values.yaml` overrides the
+subchart images to pinned tags mirrored to the TrueFoundry JFrog registry
+(`tfy.jfrog.io/tfy-mirror/bitnamilegacy/...`). This trips Bitnami's registry
+guardrail, so `global.security.allowInsecureImages: true` is set for the
+subcharts to render.
+
+Disable either dependency to point at an external service instead (see below).
+
+## Install
+
+```bash
+helm install trueforge oci://<jfrog-public-helm-repo>/trueforge \
+ --version <x.y.z> \
+ --set server.publicBaseUrl=https://trueforge.example.com
+```
+
+## Required values
+
+| Value | Description |
+| ---------------------- | ---------------------------------------------------------- |
+| `server.publicBaseUrl` | Public origin for MCP OAuth callbacks (`PUBLIC_BASE_URL`). |
+
+## Postgres
+
+Bundled by default (`postgresql.enabled=true`). Set `postgresql.auth.username`,
+`postgresql.auth.password` (or `postgresql.auth.existingSecret`), and
+`postgresql.auth.database`; the server connects to it automatically.
+
+To use an **external** Postgres, set `postgresql.enabled=false` and provide
+`externalPostgres.host` (+ `port`, `database`, `user`) with the password one of
+two ways:
+
+- Set `externalPostgres.password` and the chart renders a `Secret`, or
+- Set `externalPostgres.existingSecret` (and optionally `externalPostgres.passwordKey`,
+ default `password`) to reference a `Secret` you manage.
+
+## Redis
+
+The server always runs peered (`SINGLE_BINARY=false`), so Redis is always
+required. Bundled by default (`redis.enabled=true`, auth disabled). To use an
+**external** Redis, set `redis.enabled=false` and `externalRedis.url`.
+
+## Extra objects
+
+Deploy arbitrary manifests alongside the server (for example an Istio
+`VirtualService`, a `Gateway`, an `Ingress`, or a `NetworkPolicy`) via
+`extraObjects`. Each entry is a full object, rendered through `tpl` so Helm
+templating and chart helpers resolve:
+
+```yaml
+extraObjects:
+ - apiVersion: networking.istio.io/v1
+ kind: VirtualService
+ metadata:
+ name: '{{ include "trueforge.fullname" . }}'
+ spec:
+ hosts:
+ - trueforge.example.com
+ gateways:
+ - istio-system/public-gateway
+ http:
+ - route:
+ - destination:
+ host: '{{ include "trueforge.fullname" . }}'
+ port:
+ number: '{{ .Values.service.port }}'
+```
+
+## Common values
+
+| Value | Default | Description |
+| --------------------- | ----------------------------------- | ------------------------------------- |
+| `replicaCount` | `1` | Number of server replicas. |
+| `image.repository` | `tfy.jfrog.io/tfy-images/trueforge` | Image repository. |
+| `image.tag` | chart `appVersion` | Image tag; stamped on release. |
+| `postgresql.enabled` | `true` | Bundle the Bitnami Postgres subchart. |
+| `redis.enabled` | `true` | Bundle the Bitnami Redis subchart. |
+| `service.type` | `ClusterIP` | Service type. |
+| `service.port` | `8790` | Service port. |
+| `server.port` | `8790` | Container port (`PORT`). |
+| `autoscaling.enabled` | `false` | Enable a HorizontalPodAutoscaler. |
+| `resources` | `{}` | Container resource requests/limits. |
diff --git a/charts/trueforge/ci/lint-values.yaml b/charts/trueforge/ci/lint-values.yaml
new file mode 100644
index 000000000..7b8291645
--- /dev/null
+++ b/charts/trueforge/ci/lint-values.yaml
@@ -0,0 +1,8 @@
+# Minimal values that satisfy the chart's required() checks so `helm lint` and
+# `helm template` render cleanly. Postgres and Redis are bundled by default, so
+# only the public base URL is required. Not packaged (see .helmignore).
+#
+# Requires the subchart dependencies to be present first: run `pnpm chart:deps`
+# (pulls the public Bitnami OCI charts, no auth) before linting/templating.
+server:
+ publicBaseUrl: https://trueforge.example.com
diff --git a/charts/trueforge/templates/NOTES.txt b/charts/trueforge/templates/NOTES.txt
new file mode 100644
index 000000000..b1c86d60c
--- /dev/null
+++ b/charts/trueforge/templates/NOTES.txt
@@ -0,0 +1,19 @@
+TrueForge {{ .Chart.AppVersion }} has been deployed as release {{ .Release.Name }}.
+
+Image: {{ include "trueforge.image" . }}
+
+Reach the server (API + UI) inside the cluster at:
+ http://{{ include "trueforge.fullname" . }}.{{ .Release.Namespace }}.svc:{{ .Values.service.port }}
+
+Port-forward it locally with:
+ kubectl --namespace {{ .Release.Namespace }} port-forward svc/{{ include "trueforge.fullname" . }} 8790:{{ .Values.service.port }}
+
+Then open http://localhost:8790 and check http://localhost:8790/healthz.
+
+Postgres: {{ if .Values.postgresql.enabled }}bundled ({{ include "trueforge.postgres.host" . }}){{ else }}external ({{ include "trueforge.postgres.host" . }}){{ end }}
+Redis: {{ if .Values.redis.enabled }}bundled ({{ include "trueforge.redis.url" . }}){{ else }}external ({{ include "trueforge.redis.url" . }}){{ end }}
+
+{{- if and (not .Values.postgresql.enabled) (not .Values.externalPostgres.host) }}
+
+WARNING: postgresql.enabled is false and externalPostgres.host is empty. Set one so the server can reach Postgres.
+{{- end }}
diff --git a/charts/trueforge/templates/_helpers.tpl b/charts/trueforge/templates/_helpers.tpl
new file mode 100644
index 000000000..5893bf0a9
--- /dev/null
+++ b/charts/trueforge/templates/_helpers.tpl
@@ -0,0 +1,124 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "trueforge.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+*/}}
+{{- define "trueforge.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Chart name and version as used by the chart label.
+*/}}
+{{- define "trueforge.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels.
+*/}}
+{{- define "trueforge.labels" -}}
+helm.sh/chart: {{ include "trueforge.chart" . }}
+{{ include "trueforge.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels.
+*/}}
+{{- define "trueforge.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "trueforge.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Service account name.
+*/}}
+{{- define "trueforge.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "trueforge.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}
+
+{{/*
+Container image reference; tag falls back to the chart appVersion.
+*/}}
+{{- define "trueforge.image" -}}
+{{- printf "%s:%s" .Values.image.repository (.Values.image.tag | default .Chart.AppVersion) }}
+{{- end }}
+
+{{/*
+Postgres connection. Sourced from the bundled Bitnami postgresql subchart when
+postgresql.enabled, otherwise from externalPostgres.
+*/}}
+{{- define "trueforge.postgres.host" -}}
+{{- if .Values.postgresql.enabled -}}
+{{- printf "%s-postgresql" .Release.Name -}}
+{{- else -}}
+{{- required "externalPostgres.host is required when postgresql.enabled is false" .Values.externalPostgres.host -}}
+{{- end -}}
+{{- end }}
+
+{{- define "trueforge.postgres.port" -}}
+{{- if .Values.postgresql.enabled -}}5432{{- else -}}{{ .Values.externalPostgres.port }}{{- end -}}
+{{- end }}
+
+{{- define "trueforge.postgres.user" -}}
+{{- if .Values.postgresql.enabled -}}{{ .Values.postgresql.auth.username }}{{- else -}}{{ .Values.externalPostgres.user }}{{- end -}}
+{{- end }}
+
+{{- define "trueforge.postgres.database" -}}
+{{- if .Values.postgresql.enabled -}}{{ .Values.postgresql.auth.database }}{{- else -}}{{ .Values.externalPostgres.database }}{{- end -}}
+{{- end }}
+
+{{/*
+Name of the Secret holding the Postgres password, and its key.
+- bundled: the subchart's Secret (existingSecret override or <release>-postgresql, key `password`).
+- external existingSecret: that Secret and its passwordKey.
+- external literal password: a Secret this chart renders (see secret.yaml).
+*/}}
+{{- define "trueforge.postgres.secretName" -}}
+{{- if .Values.postgresql.enabled -}}
+{{- default (printf "%s-postgresql" .Release.Name) .Values.postgresql.auth.existingSecret -}}
+{{- else if .Values.externalPostgres.existingSecret -}}
+{{- .Values.externalPostgres.existingSecret -}}
+{{- else -}}
+{{- $_ := required "externalPostgres.password or externalPostgres.existingSecret is required when postgresql.enabled is false" .Values.externalPostgres.password -}}
+{{- printf "%s-postgres" (include "trueforge.fullname" .) -}}
+{{- end -}}
+{{- end }}
+
+{{- define "trueforge.postgres.secretKey" -}}
+{{- if .Values.postgresql.enabled -}}password{{- else -}}{{ .Values.externalPostgres.passwordKey }}{{- end -}}
+{{- end }}
+
+{{/*
+Redis connection URL. The server always runs peered, so a Redis is always
+required: the bundled auth-less standalone master, or externalRedis.url.
+*/}}
+{{- define "trueforge.redis.url" -}}
+{{- if .Values.redis.enabled -}}
+{{- printf "redis://%s-redis-master:6379" .Release.Name -}}
+{{- else -}}
+{{- required "externalRedis.url is required when redis.enabled is false (the server always needs Redis)" .Values.externalRedis.url -}}
+{{- end -}}
+{{- end }}
diff --git a/charts/trueforge/templates/deployment.yaml b/charts/trueforge/templates/deployment.yaml
new file mode 100644
index 000000000..f748d33b2
--- /dev/null
+++ b/charts/trueforge/templates/deployment.yaml
@@ -0,0 +1,106 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: {{ include "trueforge.fullname" . }}
+ labels:
+ {{- include "trueforge.labels" . | nindent 4 }}
+spec:
+ {{- if not .Values.autoscaling.enabled }}
+ replicas: {{ .Values.replicaCount }}
+ {{- end }}
+ selector:
+ matchLabels:
+ {{- include "trueforge.selectorLabels" . | nindent 6 }}
+ template:
+ metadata:
+ labels:
+ {{- include "trueforge.selectorLabels" . | nindent 8 }}
+ {{- with .Values.podLabels }}
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.podAnnotations }}
+ annotations:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ spec:
+ {{- with .Values.imagePullSecrets }}
+ imagePullSecrets:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ serviceAccountName: {{ include "trueforge.serviceAccountName" . }}
+ {{- with .Values.podSecurityContext }}
+ securityContext:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ # Above the server's GRACEFUL_TIMEOUT_SECONDS so SIGKILL does not cut off turn drain.
+ terminationGracePeriodSeconds: {{ add .Values.server.gracefulTimeoutSeconds 5 }}
+ containers:
+ - name: server
+ image: {{ include "trueforge.image" . | quote }}
+ imagePullPolicy: {{ .Values.image.pullPolicy }}
+ {{- with .Values.securityContext }}
+ securityContext:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ ports:
+ - name: http
+ containerPort: {{ .Values.server.port }}
+ protocol: TCP
+ env:
+ - name: NODE_ENV
+ value: production
+ - name: PORT
+ value: {{ .Values.server.port | quote }}
+ - name: PUBLIC_BASE_URL
+ value: {{ required "server.publicBaseUrl is required" .Values.server.publicBaseUrl | quote }}
+ # The server always runs peered against Postgres + Redis.
+ - name: STANDALONE
+ value: "false"
+ - name: GRACEFUL_TIMEOUT_SECONDS
+ value: {{ .Values.server.gracefulTimeoutSeconds | quote }}
+ - name: REDIS_URL
+ value: {{ include "trueforge.redis.url" . | quote }}
+ - name: POSTGRES_HOST
+ value: {{ include "trueforge.postgres.host" . | quote }}
+ - name: POSTGRES_PORT
+ value: {{ include "trueforge.postgres.port" . | quote }}
+ - name: POSTGRES_DB
+ value: {{ include "trueforge.postgres.database" . | quote }}
+ - name: POSTGRES_USER
+ value: {{ include "trueforge.postgres.user" . | quote }}
+ - name: POSTGRES_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: {{ include "trueforge.postgres.secretName" . }}
+ key: {{ include "trueforge.postgres.secretKey" . }}
+ {{- with .Values.server.extraEnv }}
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- with .Values.server.extraEnvFrom }}
+ envFrom:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- with .Values.livenessProbe }}
+ livenessProbe:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- with .Values.readinessProbe }}
+ readinessProbe:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- with .Values.resources }}
+ resources:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- with .Values.nodeSelector }}
+ nodeSelector:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.affinity }}
+ affinity:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.tolerations }}
+ tolerations:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
diff --git a/charts/trueforge/templates/extra-objects.yaml b/charts/trueforge/templates/extra-objects.yaml
new file mode 100644
index 000000000..9122fb7cc
--- /dev/null
+++ b/charts/trueforge/templates/extra-objects.yaml
@@ -0,0 +1,9 @@
+{{- /*
+Arbitrary extra manifests (e.g. an Istio VirtualService). Each entry in
+.Values.extraObjects is a full Kubernetes object, rendered through `tpl` so
+Helm templating and chart helpers work inside them.
+*/ -}}
+{{- range .Values.extraObjects }}
+---
+{{ tpl (toYaml .) $ }}
+{{- end }}
diff --git a/charts/trueforge/templates/hpa.yaml b/charts/trueforge/templates/hpa.yaml
new file mode 100644
index 000000000..cf6061f36
--- /dev/null
+++ b/charts/trueforge/templates/hpa.yaml
@@ -0,0 +1,22 @@
+{{- if .Values.autoscaling.enabled }}
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+ name: {{ include "trueforge.fullname" . }}
+ labels:
+ {{- include "trueforge.labels" . | nindent 4 }}
+spec:
+ scaleTargetRef:
+ apiVersion: apps/v1
+ kind: Deployment
+ name: {{ include "trueforge.fullname" . }}
+ minReplicas: {{ .Values.autoscaling.minReplicas }}
+ maxReplicas: {{ .Values.autoscaling.maxReplicas }}
+ metrics:
+ - type: Resource
+ resource:
+ name: cpu
+ target:
+ type: Utilization
+ averageUtilization: {{ .Values.autoscaling.targetCPUUtilizationPercentage }}
+{{- end }}
diff --git a/charts/trueforge/templates/secret.yaml b/charts/trueforge/templates/secret.yaml
new file mode 100644
index 000000000..982cbc9f5
--- /dev/null
+++ b/charts/trueforge/templates/secret.yaml
@@ -0,0 +1,15 @@
+{{- /*
+Rendered only for external Postgres with a literal password and no existingSecret.
+The bundled postgresql subchart manages its own Secret.
+*/ -}}
+{{- if and (not .Values.postgresql.enabled) .Values.externalPostgres.password (not .Values.externalPostgres.existingSecret) }}
+apiVersion: v1
+kind: Secret
+metadata:
+ name: {{ printf "%s-postgres" (include "trueforge.fullname" .) }}
+ labels:
+ {{- include "trueforge.labels" . | nindent 4 }}
+type: Opaque
+stringData:
+ {{ .Values.externalPostgres.passwordKey }}: {{ .Values.externalPostgres.password | quote }}
+{{- end }}
diff --git a/charts/trueforge/templates/service.yaml b/charts/trueforge/templates/service.yaml
new file mode 100644
index 000000000..c2eb2e642
--- /dev/null
+++ b/charts/trueforge/templates/service.yaml
@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+ name: {{ include "trueforge.fullname" . }}
+ labels:
+ {{- include "trueforge.labels" . | nindent 4 }}
+spec:
+ type: {{ .Values.service.type }}
+ ports:
+ - port: {{ .Values.service.port }}
+ targetPort: http
+ protocol: TCP
+ name: http
+ selector:
+ {{- include "trueforge.selectorLabels" . | nindent 4 }}
diff --git a/charts/trueforge/templates/serviceaccount.yaml b/charts/trueforge/templates/serviceaccount.yaml
new file mode 100644
index 000000000..9b80fd1bc
--- /dev/null
+++ b/charts/trueforge/templates/serviceaccount.yaml
@@ -0,0 +1,12 @@
+{{- if .Values.serviceAccount.create }}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+ name: {{ include "trueforge.serviceAccountName" . }}
+ labels:
+ {{- include "trueforge.labels" . | nindent 4 }}
+ {{- with .Values.serviceAccount.annotations }}
+ annotations:
+ {{- toYaml . | nindent 4 }}
+ {{- end }}
+{{- end }}
diff --git a/charts/trueforge/values.yaml b/charts/trueforge/values.yaml
new file mode 100644
index 000000000..33e4fb4d6
--- /dev/null
+++ b/charts/trueforge/values.yaml
@@ -0,0 +1,167 @@
+# Default values for the trueforge chart.
+
+replicaCount: 1
+
+image:
+ repository: tfy.jfrog.io/tfy-images/trueforge
+ # Tag defaults to the chart appVersion when empty; the release workflow stamps
+ # the released version here.
+ tag: ""
+ pullPolicy: IfNotPresent
+
+imagePullSecrets: []
+nameOverride: ""
+fullnameOverride: ""
+
+serviceAccount:
+ create: true
+ annotations: {}
+ # If empty and create is true, a name is generated from the fullname.
+ name: ""
+
+podAnnotations: {}
+podLabels: {}
+podSecurityContext: {}
+securityContext: {}
+
+service:
+ type: ClusterIP
+ port: 8790
+
+# Server runtime configuration. Keys map to environment variables read in
+# packages/server/src/config.ts.
+server:
+ # Container port the server listens on (PORT).
+ port: 8790
+ # Public origin used for MCP OAuth callbacks (PUBLIC_BASE_URL). Required.
+ publicBaseUrl: ""
+ # Seconds the server is given to drain turns on SIGTERM (GRACEFUL_TIMEOUT_SECONDS).
+ gracefulTimeoutSeconds: 30
+ # The server always runs peered (SINGLE_BINARY=false) against Postgres + Redis.
+ # extraEnv/extraEnvFrom are escape hatches; extraEnv accepts
+ # {name, value} or {name, valueFrom: {secretKeyRef: ...}}.
+ extraEnv: []
+ extraEnvFrom: []
+
+# Bitnami relocated its versioned container images to docker.io/bitnamilegacy and
+# left only rolling `latest` tags under docker.io/bitnami, so the subchart image
+# defaults no longer pull. We source pinned legacy images from the TrueFoundry
+# JFrog mirror instead. Overriding the registry trips Bitnami's image guardrail,
+# so allowInsecureImages must be set for the subcharts to render.
+global:
+ security:
+ allowInsecureImages: true
+
+# --- Bundled Postgres (Bitnami subchart) ---------------------------------------
+# Rendered only when postgresql.enabled is true. The server's POSTGRES_* env is
+# wired to this release automatically. See the Bitnami postgresql chart for the
+# full set of tunables.
+postgresql:
+ enabled: true
+ architecture: standalone
+ # Pinned legacy image mirrored to JFrog (upstream docker.io/bitnami no longer
+ # serves this tag). Bump alongside the postgresql subchart version.
+ image:
+ registry: tfy.jfrog.io
+ repository: tfy-mirror/bitnamilegacy/postgresql
+ tag: 17.6.0-debian-12-r4
+ auth:
+ username: trueforge
+ database: trueforge
+ # Dev default. In production set a strong password or reference a Secret via
+ # `existingSecret` (Bitnami reads the user password from key `password`).
+ password: trueforge
+ existingSecret: ""
+ primary:
+ persistence:
+ enabled: true
+ size: 8Gi
+
+# --- Bundled Redis (Bitnami subchart) ------------------------------------------
+# Rendered only when redis.enabled is true. Auth is disabled so REDIS_URL is a
+# plain redis://host:6379 the server can consume directly.
+redis:
+ enabled: true
+ architecture: standalone
+ # The redis 24.0.0 subchart floats `latest`; pin a legacy tag mirrored to JFrog
+ # for reproducibility (bitnamilegacy has no 8.4.x, so we track 8.2.x here).
+ image:
+ registry: tfy.jfrog.io
+ repository: tfy-mirror/bitnamilegacy/redis
+ tag: 8.2.1-debian-12-r0
+ auth:
+ enabled: false
+ master:
+ persistence:
+ enabled: false
+
+# --- External services (used when the matching bundled dependency is disabled) -
+externalPostgres:
+ host: ""
+ port: 5432
+ database: trueforge
+ user: trueforge
+ # Provide the password one of two ways:
+ # - set `password` and the chart renders a Secret, or
+ # - set `existingSecret` (+ `passwordKey`) to reference an existing Secret.
+ password: ""
+ existingSecret: ""
+ passwordKey: password
+
+externalRedis:
+ # Full connection URL, e.g. redis://redis-master.databases.svc:6379.
+ # Required when redis.enabled is false (the server always needs Redis).
+ url: ""
+
+# Extra raw manifests deployed alongside the server, e.g. an Istio
+# VirtualService, a Gateway, an Ingress, or a NetworkPolicy. Each entry is a
+# full Kubernetes object rendered through `tpl`, so Helm templating works and
+# helpers like `{{ include "trueforge.fullname" . }}` resolve. Example:
+#
+# extraObjects:
+# - apiVersion: networking.istio.io/v1
+# kind: VirtualService
+# metadata:
+# name: '{{ include "trueforge.fullname" . }}'
+# spec:
+# hosts:
+# - trueforge.example.com
+# gateways:
+# - istio-system/public-gateway
+# http:
+# - route:
+# - destination:
+# host: '{{ include "trueforge.fullname" . }}'
+# port:
+# number: '{{ .Values.service.port }}'
+extraObjects: []
+
+resources: {}
+
+livenessProbe:
+ httpGet:
+ path: /healthz
+ port: http
+ initialDelaySeconds: 15
+ periodSeconds: 10
+ timeoutSeconds: 5
+ failureThreshold: 6
+
+readinessProbe:
+ httpGet:
+ path: /healthz
+ port: http
+ initialDelaySeconds: 5
+ periodSeconds: 10
+ timeoutSeconds: 5
+ failureThreshold: 6
+
+autoscaling:
+ enabled: false
+ minReplicas: 1
+ maxReplicas: 5
+ targetCPUUtilizationPercentage: 80
+
+nodeSelector: {}
+tolerations: []
+affinity: {}
diff --git a/package.json b/package.json
index f108a36d9..dc2547b87 100644
--- a/package.json
+++ b/package.json
@@ -32,6 +32,10 @@
"test:store:local": "bash scripts/test-store-local.sh",
"test": "pnpm --filter @truefoundry/utils-core test && pnpm --filter @truefoundry/trueforge-ui test && pnpm --filter @truefoundry/utils test && pnpm --filter frontend test",
"typecheck": "pnpm --filter @truefoundry/utils-core typecheck && pnpm --filter @truefoundry/trueforge-ui typecheck && pnpm --filter @truefoundry/utils typecheck && pnpm --filter frontend typecheck"
+ "chart:deps": "helm dependency build charts/trueforge",
+ "chart:lint": "helm lint charts/trueforge --values charts/trueforge/ci/lint-values.yaml",
+ "chart:template": "helm template trueforge charts/trueforge --values charts/trueforge/ci/lint-values.yaml",
+ "chart:package": "helm package charts/trueforge --destination dist"
},
"devDependencies": {
"@eslint-react/eslint-plugin": "^5.18.0",