From 2fb3ec67e9841b6084886cdbfbcfab9332160a92 Mon Sep 17 00:00:00 2001
From: Daniel Garcia Rico <daniel@codetogether.com>
Date: Tue, 30 Jun 2026 18:22:00 +0000
Subject: [PATCH 1/4] Publish CodeTogether AI Helm chart

---
 charts/ai/.helmignore                         |  22 ++
 charts/ai/Chart.yaml                          |  21 ++
 charts/ai/README.md                           | 228 +++++++++++++++++
 .../ai/ctai-configuration.properties.template | 150 ++++++++++++
 charts/ai/generate-master-key.sh              | 158 ++++++++++++
 charts/ai/generate-properties-secrets.sh      | 159 ++++++++++++
 charts/ai/templates/NOTES.txt                 |  36 +++
 charts/ai/templates/_helpers.tpl              | 231 ++++++++++++++++++
 charts/ai/templates/deployment.yaml           | 155 ++++++++++++
 charts/ai/templates/ingress-class.yaml        |  10 +
 charts/ai/templates/ingress.yaml              |  51 ++++
 .../ai/templates/secret-ctai-properties.yaml  |  12 +
 charts/ai/templates/secret-master-key.yaml    |  18 ++
 charts/ai/templates/secret-pullimage.yaml     |  12 +
 charts/ai/templates/service.yaml              |  19 ++
 charts/ai/templates/serviceaccount.yaml       |  12 +
 .../ai/templates/tests/test-connection.yaml   |  22 ++
 charts/ai/values.yaml                         | 134 ++++++++++
 18 files changed, 1450 insertions(+)
 create mode 100644 charts/ai/.helmignore
 create mode 100644 charts/ai/Chart.yaml
 create mode 100644 charts/ai/README.md
 create mode 100644 charts/ai/ctai-configuration.properties.template
 create mode 100755 charts/ai/generate-master-key.sh
 create mode 100755 charts/ai/generate-properties-secrets.sh
 create mode 100644 charts/ai/templates/NOTES.txt
 create mode 100644 charts/ai/templates/_helpers.tpl
 create mode 100644 charts/ai/templates/deployment.yaml
 create mode 100644 charts/ai/templates/ingress-class.yaml
 create mode 100644 charts/ai/templates/ingress.yaml
 create mode 100644 charts/ai/templates/secret-ctai-properties.yaml
 create mode 100644 charts/ai/templates/secret-master-key.yaml
 create mode 100644 charts/ai/templates/secret-pullimage.yaml
 create mode 100644 charts/ai/templates/service.yaml
 create mode 100644 charts/ai/templates/serviceaccount.yaml
 create mode 100644 charts/ai/templates/tests/test-connection.yaml
 create mode 100644 charts/ai/values.yaml

diff --git a/charts/ai/.helmignore b/charts/ai/.helmignore
new file mode 100644
index 0000000..a81648f
--- /dev/null
+++ b/charts/ai/.helmignore
@@ -0,0 +1,22 @@
+# Patterns to ignore when building packages.
+.DS_Store
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+.project
+.idea/
+*.tmproj
+.vscode/
+SPEC.md
+values-aitrax.yaml
+values-cluster.yaml
+values-local.yaml
diff --git a/charts/ai/Chart.yaml b/charts/ai/Chart.yaml
new file mode 100644
index 0000000..71962b1
--- /dev/null
+++ b/charts/ai/Chart.yaml
@@ -0,0 +1,21 @@
+apiVersion: v2
+name: codetogether-ai
+description: CodeTogether AI on-premises Kubernetes deployment
+
+type: application
+version: 0.1.0
+appVersion: "0.1.1204"
+
+icon: https://www.codetogether.com/wp-content/uploads/2020/02/codetogether-circle-128.png
+home: https://www.codetogether.com
+
+maintainers:
+  - email: info@codetogether.com
+    name: CodeTogether Inc.
+
+keywords:
+  - codetogether
+  - ctai
+  - ai
+  - aitrax
+  - on-premises
diff --git a/charts/ai/README.md b/charts/ai/README.md
new file mode 100644
index 0000000..a407001
--- /dev/null
+++ b/charts/ai/README.md
@@ -0,0 +1,228 @@
+# Helm Chart for CodeTogether AI
+
+## Summary
+
+This chart deploys CodeTogether AI on a Kubernetes cluster using Helm. Runtime
+configuration is supplied as `ctai-configuration.properties`, and the protected
+storage master key is stored in a separate Kubernetes Secret.
+
+## Prerequisites
+
+- Helm v3.5+
+- Kubernetes v1.19+
+- PostgreSQL reachable from the cluster. This chart does not install Postgres.
+- A DNS-routable HTTPS host for CodeTogether AI, configured as `service_fqdn`.
+- A TLS Secret for Ingress when `ingress.enabled=true`.
+- CodeTogether-provided credentials for `hub.edge.codetogether.com`.
+
+## Install
+
+### 1. Prepare the configuration file
+
+Copy `ctai-configuration.properties.template` to
+`ctai-configuration.properties`, then replace the example values with the values
+for your environment.
+
+```bash
+cp ctai-configuration.properties.template ctai-configuration.properties
+```
+
+Set `service_fqdn` to the public HTTPS URL for the deployment, for example:
+
+```properties
+service_fqdn=https://ai.example.com
+```
+
+Set the external Postgres connection properties:
+
+```properties
+database_url=jdbc:postgresql://postgres.example.internal:5432/codetogether
+database_username=codetogether
+database_password=replace-with-postgres-password
+```
+
+Generate the random properties-file secrets and paste the output into
+`ctai-configuration.properties`:
+
+```bash
+./generate-properties-secrets.sh
+```
+
+The configuration file contains deployment secrets. Store it securely and do
+not commit customer-specific values.
+
+### 2. Configure SSO
+
+Register this redirect URI with your identity provider:
+
+```text
+https://ai.example.com/api/v1/auth/sso/provider/callback
+```
+
+Use the same host as `service_fqdn`. For Google OAuth or Google OIDC, add that
+URI as an Authorized redirect URI in the Google Cloud Console, then set the
+provider values in `ctai-configuration.properties`, for example:
+
+```properties
+sso_provider1_type=google
+sso_provider1=google
+sso_provider1_client_id=replace-with-google-client-id
+sso_provider1_client_secret=replace-with-google-client-secret
+sso_provider1_client_issuer_url=https://accounts.google.com
+```
+
+### 3. Create the TLS Secret
+
+Create the TLS Secret in the namespace where CodeTogether AI will run. The
+default Secret name is `codetogether-ai-tls`.
+
+```bash
+kubectl create namespace codetogether-ai
+kubectl create secret tls codetogether-ai-tls \
+  --namespace codetogether-ai \
+  --key /path/to/tls.key \
+  --cert /path/to/tls.crt
+```
+
+### 4. Create the protected storage master-key Secret
+
+CodeTogether AI uses a 32-byte AES master key to encrypt sensitive values stored
+in Postgres. Generate this key once per deployment environment and database.
+Changing the key after encrypted data exists prevents that data from being
+decrypted.
+
+```bash
+./generate-master-key.sh --k8s-secret-yaml --secret-name ctai-master-key \
+  > ctai-master-key-secret.yaml
+
+kubectl apply -f ctai-master-key-secret.yaml -n codetogether-ai
+```
+
+Save the generated base64 key in your password manager and keep it with your
+Postgres backup procedure.
+
+### 5. Install the chart
+
+```bash
+helm repo add codetogether https://helm.codetogether.io
+helm repo update
+
+helm install codetogether-ai codetogether/codetogether-ai \
+  --namespace codetogether-ai --create-namespace \
+  --set-file ctaiPropertiesFile=./ctai-configuration.properties \
+  --set imageCredentials.username=replace-with-hub-edge-username \
+  --set imageCredentials.password=replace-with-hub-edge-password \
+  --set masterKey.source=secret \
+  --set masterKey.existingSecret=ctai-master-key
+```
+
+Ingress host and TLS are derived from `service_fqdn` in
+`ctai-configuration.properties`. If you also set `service.fqdn` in Helm values,
+it must exactly match `service_fqdn`.
+
+## Configuration
+
+The following table lists the primary configurable parameters and defaults.
+
+| Parameter | Description | Default |
+| --------- | ----------- | ------- |
+| `nameOverride` | Overrides the chart name | `""` |
+| `fullnameOverride` | Overrides the full release name | `""` |
+| `image.repository` | Container image repository | `hub.edge.codetogether.com/releases/codetogether-ai` |
+| `image.pullPolicy` | Image pull policy | `Always` |
+| `image.tag` | Container image tag | `latest` |
+| `image.digest` | Optional image digest; overrides the tag when set | `""` |
+| `imageCredentials.enabled` | Create a pull Secret from registry credentials | `true` |
+| `imageCredentials.registry` | Private registry host | `hub.edge.codetogether.com` |
+| `imageCredentials.username` | Registry username | `my-customer-username` |
+| `imageCredentials.password` | Registry password | `my-customer-password` |
+| `service.fqdn` | Public HTTPS URL; optional with `--set-file`, required for pre-created properties Secrets | `""` |
+| `service.type` | Kubernetes Service type | `ClusterIP` |
+| `service.port` | Service port for nginx / portal | `1080` |
+| `service.annotations` | Kubernetes Service annotations | `{}` |
+| `ctaiPropertiesFile` | Properties file contents, normally set with `--set-file` | `""` |
+| `ctaipropertiessecret.enabled` | Mount a pre-created properties Secret instead of creating one from `ctaiPropertiesFile` | `false` |
+| `ctaipropertiessecret.ref` | Name of the pre-created properties Secret | `""` |
+| `masterKey.source` | Master key source: `secret`, `auto`, or `external` | `secret` |
+| `masterKey.existingSecret` | Pre-created master-key Secret name when `source=secret` | `ctai-master-key` |
+| `masterKey.existingSecretKey` | Key in the master-key Secret | `CTAI_PROTECTED_STORAGE_MASTER_KEY_B64` |
+| `masterKey.existingSecretVersionKey` | Optional version key in the master-key Secret | `CTAI_PROTECTED_STORAGE_MASTER_KEY_VERSION` |
+| `properties.mountPath` | Pod mount path for the properties file | `/opt/ctai/server/config` |
+| `properties.fileName` | Properties filename inside the Secret | `ctai-configuration.properties` |
+| `ingress.enabled` | Create an Ingress resource | `true` |
+| `ingress.annotations` | Ingress annotations | `nginx.ingress.kubernetes.io/proxy-body-size: "16m"` |
+| `ingress.tls.secretName` | TLS Secret for Ingress | `codetogether-ai-tls` |
+| `serviceAccount.create` | Create a ServiceAccount | `true` |
+| `serviceAccount.name` | ServiceAccount name | `codetogether-ai` |
+| `replicaCount` | Deployment replica count | `1` |
+| `readinessProbe.path` | Readiness endpoint on port 1080 | `/healthz` |
+| `livenessProbe.path` | Liveness endpoint on port 8080 | `/actuator/health` |
+| `startupProbe.enabled` | Enable startup probe | `true` |
+
+## Pre-Created Properties Secret
+
+For GitOps workflows, create and manage the properties Secret outside Helm:
+
+```bash
+kubectl create secret generic ctai-properties \
+  --namespace codetogether-ai \
+  --from-file=ctai-configuration.properties=./ctai-configuration.properties
+```
+
+Then install or upgrade with:
+
+```yaml
+ctaipropertiessecret:
+  enabled: true
+  ref: ctai-properties
+
+service:
+  fqdn: https://ai.example.com
+```
+
+When Helm cannot read the properties file through `--set-file`, `service.fqdn`
+is required for Ingress and install notes. It must match `service_fqdn` inside
+the Secret.
+
+## Validation and Troubleshooting
+
+Render the chart locally before installing:
+
+```bash
+helm template codetogether-ai codetogether/codetogether-ai \
+  --set-file ctaiPropertiesFile=./ctai-configuration.properties \
+  --set imageCredentials.username=test \
+  --set imageCredentials.password=test
+```
+
+At runtime, CodeTogether AI validates the mounted configuration before the
+service starts. If validation fails, the pod exits and logs a block beginning
+with `Configuration errors:`.
+
+```bash
+kubectl logs -n codetogether-ai deploy/codetogether-ai
+kubectl logs -n codetogether-ai deploy/codetogether-ai --previous
+```
+
+Common causes include unfilled example values, Postgres connectivity problems,
+missing or changed master-key Secret, an HTTP `service_fqdn`, missing TLS
+Secret, or SSO provider settings that do not match the registered redirect URI.
+
+## Upgrade
+
+```bash
+helm repo update
+helm upgrade codetogether-ai codetogether/codetogether-ai \
+  --namespace codetogether-ai \
+  --set-file ctaiPropertiesFile=./ctai-configuration.properties \
+  --set imageCredentials.username=replace-with-hub-edge-username \
+  --set imageCredentials.password=replace-with-hub-edge-password
+```
+
+The Deployment rolls when the chart-managed properties Secret changes.
+
+## Uninstall
+
+```bash
+helm uninstall codetogether-ai -n codetogether-ai
+```
diff --git a/charts/ai/ctai-configuration.properties.template b/charts/ai/ctai-configuration.properties.template
new file mode 100644
index 0000000..8b74da0
--- /dev/null
+++ b/charts/ai/ctai-configuration.properties.template
@@ -0,0 +1,150 @@
+# =============================================================================
+# CodeTogether — configuration template (manual fill-in)
+# =============================================================================
+#
+# Copy this file, replace placeholder values, and save as:
+#   ctai-configuration.properties
+#
+# Lines starting with # are comments and are ignored when the file is loaded.
+# Each setting uses key=value format (same keys written by the config wizard).
+#
+# Prefer the config wizard when possible — it validates settings, generates
+# secrets, and can test database, SSO, and SMTP connectivity.
+#
+# After editing manually, you can open the saved file in the wizard (Intro →
+# Open existing properties file...) to review or update settings.
+#
+# =============================================================================
+
+# Company display name shown in the application.
+# You can update this later from the dashboard.
+company_name=Example Company
+
+# Public Fully Qualified Domain Name (fqdn) for the CodeTogether service. This hostname must be DNS routable and must use https://.
+service_fqdn=https://example.codetogether.io
+
+# Sender address and display name for outbound mail.
+email_from_address=noreply@example.com
+email_from_name=Example Company
+
+# SMTP server hostname and port (587 is typical with STARTTLS).
+smtp_host=smtp.example.com
+smtp_port=587
+
+# true when the SMTP server requires authentication; false for open relay /
+# IP-allowlisted servers.
+smtp_auth_enabled=false
+# required when smtp_auth_enabled=true
+smtp_username=
+smtp_password=
+
+# STARTTLS: connect on a plain connection first, then upgrade to TLS before
+# sending credentials (typical on port 587).
+smtp_start_tls=true
+
+# Connection timeouts in ISO-8601 duration form (defaults shown).
+smtp_connect_timeout=PT10S
+smtp_read_timeout=PT30S
+
+# PostgreSQL JDBC URL. Pattern: jdbc:postgresql://<hostname[:port]>/<database>
+# Use a dedicated database for CodeTogether rather than reusing an existing one.
+database_url=jdbc:postgresql://postgres.example.internal:5432/codetogether
+database_username=codetogether
+database_password=replace-with-postgres-password
+
+# Schemas for telemetry, platform, and datamart data (defaults shown).
+# Telemetry: developer and AI activity.
+# Datamart: analytics calculated from telemetry.
+# Platform: backend server data.
+database_telemetry_schema=telemetry
+database_platform_schema=platform
+database_datamart_schema=datamart
+
+# Signs short-lived state tokens during GitHub OAuth flows — used when connecting
+# a GitHub App and when creating a new GitHub App via manifest provisioning.
+# Generate a unique random value; do not reuse across deployments.
+# Or run: ./generate-properties-secrets.sh (in this chart directory)
+github_state_secret=replace-with-generated-github-state-secret
+
+# Signs JWT session cookies to secure user sessions after SSO login.
+# Generate a unique random value; must differ from the other deployment secrets.
+# Do not change after login to the dashboard unless you want your login cookies to change
+# Or run: ./generate-properties-secrets.sh (in this chart directory)
+sso_jwt_secret=replace-with-generated-sso-jwt-secret
+
+# Register the full callback URL at your IdP:
+#   https://<service_fqdn>/api/v1/auth/sso/provider/callback
+# Example: https://mycompany.codetogether.com/api/v1/auth/sso/provider/callback
+#
+# -----------------------------------------------------------------------------
+# SSO providers
+# -----------------------------------------------------------------------------
+#
+# Each provider uses a numbered prefix: sso_provider1, sso_provider2, ...
+# Use consecutive integers starting at 1 with no gaps.
+#
+# Required keys per provider (replace N with 1, 2, 3, ...):
+#   sso_providerN_type          Provider kind (see valid types below).
+#   sso_providerN               Provider name (see naming rules below).
+#   sso_providerN_client_id     OAuth client ID from your identity provider.
+#   sso_providerN_client_secret OAuth client secret.
+#
+# Valid sso_providerN_type values:
+#   keycloak, github, google, azure, okta, custom
+#
+# sso_providerN (name field) rules:
+#   - For keycloak, google, azure, okta: use the same string as _type
+#     (e.g. sso_provider1_type=keycloak and sso_provider1=keycloak).
+#   - For github: use github.
+#   - For custom (optional second sign-in provider): use a unique lowercase
+#     name (e.g. customprovidername) or a built-in kind for an alternate
+#     account (github, keycloak, etc.). Only one custom provider is allowed.
+#   - You cannot register two providers with the same registration id
+#     (e.g. two keycloak entries); use custom for a second GitHub or Keycloak.
+#
+# OIDC providers (keycloak, google, azure, okta, and custom with issuer):
+#   sso_providerN_client_issuer_url=<https://issuer-url>
+#
+# GitHub (and custom providers using GitHub OAuth endpoints): set _auth_uri,
+# _token_uri, _info_uri, _jwt_set_uri, and optionally _logout_uri instead of
+# client_issuer_url. Standard GitHub values:
+#   auth:  https://github.com/login/oauth/authorize
+#   token: https://github.com/login/oauth/access_token
+#   info:  https://api.github.com/user
+#   jwks:  https://token.actions.githubusercontent.com/.well-known/jwks
+#   logout: https://github.com/logout
+#
+# Optional keys (omit to use runtime defaults):
+#   sso_providerN_client_authentication_method
+#   sso_providerN_display_label       Custom provider label shown to users.
+#   sso_providerN_name_attribute      Default varies by type (e.g. login for GitHub).
+#   sso_providerN_scopes              Default: openid,email,profile (email,profile for GitHub).
+#   sso_providerN_authorization_grant_type  Default: authorization_code
+#   sso_providerN_role_mapping_claim
+#   sso_providerN_role-mappings       Note: hyphen in the property name.
+#
+# Example — first provider (Keycloak / OIDC):
+sso_provider1_type=keycloak
+sso_provider1=keycloak
+sso_provider1_client_id=replace-with-client-id
+sso_provider1_client_secret=replace-with-client-secret
+sso_provider1_client_issuer_url=https://auth.example.com/realms/codetogether
+
+# Example — second provider (uncomment and renumber if needed):
+# sso_provider2_type=custom
+# sso_provider2=<customprovidername>
+# sso_provider2_client_id=<client-id>
+# sso_provider2_client_secret=<client-secret>
+# sso_provider2_display_label=<Label shown on sign-in button>
+# sso_provider2_client_issuer_url=https://<auth-host>/realms/<realm>
+#
+# Example — GitHub as first provider (use preset URIs; no client_issuer_url):
+# sso_provider1_type=github
+# sso_provider1=github
+# sso_provider1_client_id=<github-oauth-client-id>
+# sso_provider1_client_secret=<github-oauth-client-secret>
+# sso_provider1_auth_uri=https://github.com/login/oauth/authorize
+# sso_provider1_token_uri=https://github.com/login/oauth/access_token
+# sso_provider1_info_uri=https://api.github.com/user
+# sso_provider1_jwt_set_uri=https://token.actions.githubusercontent.com/.well-known/jwks
+# sso_provider1_logout_uri=https://github.com/logout
diff --git a/charts/ai/generate-master-key.sh b/charts/ai/generate-master-key.sh
new file mode 100755
index 0000000..ff3510d
--- /dev/null
+++ b/charts/ai/generate-master-key.sh
@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# Generate or validate the protected storage master key (32-byte AES, base64).
+set -euo pipefail
+
+KEY_B64_ENV="CTAI_PROTECTED_STORAGE_MASTER_KEY_B64"
+KEY_VERSION_ENV="CTAI_PROTECTED_STORAGE_MASTER_KEY_VERSION"
+DEFAULT_SECRET_NAME="ctai-master-key"
+
+usage() {
+  cat <<'EOF'
+Usage: generate-master-key.sh [options]
+
+Generate a protected storage master key for on-prem CodeTogether installs.
+
+The key is a random 32-byte AES key, encoded as standard base64 (44 characters).
+CodeTogether uses it to encrypt sensitive information stored in Postgres (for
+example GitHub app credentials, SMTP passwords, and AI API keys). It is not
+stored in ctai-configuration.properties.
+
+Generate this key once per deployment environment against a particular database
+and configured schemas. If the key changes after
+data has been encrypted, existing secrets in the database cannot be decrypted.
+
+Options:
+  --k8s-secret-yaml     Emit a Kubernetes Secret manifest (recommended for Helm)
+  --secret-name NAME    Secret metadata.name (default: ctai-master-key)
+  --validate B64        Validate an existing base64 key (exit 0 if 32 bytes)
+  -h, --help            Show this help
+
+Examples:
+  ./generate-master-key.sh --k8s-secret-yaml --secret-name ctai-master-key | kubectl apply -f -
+  ./generate-master-key.sh --validate 'bG9jYWwtZGV2ZWxvcG1lbnQtcHJvdGVjdGVkLWtleSE='
+EOF
+}
+
+generate_key_b64() {
+  openssl rand 32 | base64 | tr -d '\n'
+}
+
+validate_key_b64() {
+  local b64="$1"
+  if [[ -z "$b64" ]]; then
+    echo "Error: base64 value is empty" >&2
+    return 1
+  fi
+  local decoded
+  if ! decoded="$(printf '%s' "$b64" | base64 -d 2>/dev/null)"; then
+    echo "Error: invalid base64" >&2
+    return 1
+  fi
+  local len="${#decoded}"
+  if [[ "$len" -ne 32 ]]; then
+    echo "Error: decoded length is ${len} bytes (expected 32)" >&2
+    return 1
+  fi
+  echo "Valid: 32-byte protected storage master key"
+  return 0
+}
+
+emit_k8s_secret_yaml() {
+  local secret_name="$1"
+  local key_b64="$2"
+  cat <<EOF
+apiVersion: v1
+kind: Secret
+metadata:
+  name: ${secret_name}
+type: Opaque
+stringData:
+  ${KEY_B64_ENV}: ${key_b64}
+  ${KEY_VERSION_ENV}: v1
+EOF
+}
+
+print_helm_hint() {
+  local secret_name="$1"
+  cat <<EOF
+
+Next steps (Helm):
+  1. Save the base64 value above in your password manager (disaster recovery).
+  2. Apply the Kubernetes Secret (if you have not already):
+       kubectl apply -f ctai-master-key-secret.yaml -n <namespace>
+  3. Install or upgrade the chart with:
+       --set masterKey.source=secret \\
+       --set masterKey.existingSecret=${secret_name}
+
+Pair this Secret with your Postgres backup — restore both before starting the server.
+EOF
+}
+
+main() {
+  local mode="generate"
+  local secret_name="$DEFAULT_SECRET_NAME"
+  local validate_input=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --k8s-secret-yaml)
+        mode="k8s"
+        shift
+        ;;
+      --secret-name)
+        secret_name="${2:?--secret-name requires a value}"
+        shift 2
+        ;;
+      --validate)
+        mode="validate"
+        validate_input="${2:?--validate requires a base64 value}"
+        shift 2
+        ;;
+      -h|--help)
+        usage
+        exit 0
+        ;;
+      *)
+        echo "Unknown option: $1" >&2
+        usage >&2
+        exit 1
+        ;;
+    esac
+  done
+
+  case "$mode" in
+    validate)
+      validate_key_b64 "$validate_input"
+      ;;
+    k8s)
+      local key_b64
+      key_b64="$(generate_key_b64)"
+      emit_k8s_secret_yaml "$secret_name" "$key_b64"
+      echo "" >&2
+      echo "Generated a new 32-byte AES master key." >&2
+      echo "Save this base64 value in your password manager:" >&2
+      echo "  ${key_b64}" >&2
+      echo "" >&2
+      echo "Apply the manifest above, then point Helm at the Secret:" >&2
+      echo "  kubectl apply -f - -n <namespace>   # pipe this script's stdout" >&2
+      echo "  helm install ... --set masterKey.source=secret --set masterKey.existingSecret=${secret_name}" >&2
+      ;;
+    generate)
+      local key_b64
+      key_b64="$(generate_key_b64)"
+      echo "Protected storage master key (32-byte AES, base64):"
+      echo "  ${key_b64}"
+      echo ""
+      echo "Run this script only once per environment (per database and schemas)."
+      echo "Each run creates a different key."
+      echo "If you already encrypted data with a previous key, you must reuse that key."
+      echo ""
+      echo "Printing the key alone does not configure Helm. To create the Kubernetes"
+      echo "Secret and wire it into the chart, re-run with --k8s-secret-yaml:"
+      echo "  ./generate-master-key.sh --k8s-secret-yaml --secret-name ${secret_name} > ctai-master-key-secret.yaml"
+      print_helm_hint "$secret_name"
+      ;;
+  esac
+}
+
+main "$@"
diff --git a/charts/ai/generate-properties-secrets.sh b/charts/ai/generate-properties-secrets.sh
new file mode 100755
index 0000000..6b7a32c
--- /dev/null
+++ b/charts/ai/generate-properties-secrets.sh
@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# Generate properties-file secrets for ctai-configuration.properties (GitHub state + SSO JWT).
+set -euo pipefail
+
+GITHUB_STATE_BYTES=24
+SSO_JWT_BYTES=32
+MIN_SECRET_BYTES=16
+
+usage() {
+  cat <<'EOF'
+Usage: generate-properties-secrets.sh [options]
+
+Generate random secrets for ctai-configuration.properties.
+
+These values are stored in the properties file (not in a separate Kubernetes
+Secret). They must differ from each other and from the protected storage master
+key.
+
+Output uses URL-safe base64 (no padding), matching the config wizard:
+  github_state_secret — 24 random bytes (GitHub OAuth state signing)
+  sso_jwt_secret      — 32 random bytes (SSO session JWT signing)
+
+Options:
+  --github-state-only   Emit github_state_secret only
+  --sso-jwt-only        Emit sso_jwt_secret only
+  --validate-github V   Validate an existing github_state_secret value
+  --validate-jwt V      Validate an existing sso_jwt_secret value
+  -h, --help            Show this help
+
+Examples:
+  ./generate-properties-secrets.sh
+  ./generate-properties-secrets.sh --validate-github 'abc' --validate-jwt 'def'
+EOF
+}
+
+random_secret_b64url() {
+  local nbytes="$1"
+  openssl rand "$nbytes" | base64 | tr -d '\n' | tr '+/' '-_' | tr -d '='
+}
+
+validate_secret() {
+  local label="$1"
+  local value="$2"
+  local min_bytes="$3"
+
+  if [[ -z "$value" ]]; then
+    echo "Error: ${label} is empty" >&2
+    return 1
+  fi
+  if [[ ${#value} -lt $((min_bytes * 4 / 3)) ]]; then
+    echo "Error: ${label} is too short (use at least ${min_bytes} random bytes)" >&2
+    return 1
+  fi
+  if ! [[ "$value" =~ ^[A-Za-z0-9_-]+$ ]]; then
+    echo "Error: ${label} must use URL-safe base64 characters (A-Za-z0-9_-)" >&2
+    return 1
+  fi
+  echo "Valid: ${label}"
+  return 0
+}
+
+generate_github_state_secret() {
+  random_secret_b64url "$GITHUB_STATE_BYTES"
+}
+
+generate_sso_jwt_secret() {
+  random_secret_b64url "$SSO_JWT_BYTES"
+}
+
+emit_pair() {
+  local github jwt
+  github="$(generate_github_state_secret)"
+  jwt="$(generate_sso_jwt_secret)"
+  while [[ "$github" == "$jwt" ]]; do
+    jwt="$(generate_sso_jwt_secret)"
+  done
+  echo "github_state_secret=${github}"
+  echo "sso_jwt_secret=${jwt}"
+  cat <<EOF >&2
+
+Paste these lines into ctai-configuration.properties (replace the placeholders).
+Store the file securely — it contains deployment secrets.
+Each run of the script generates new values. Only run this and update your
+ctai-configuration.properties unless it is intentional; do not rotate
+sso_jwt_secret after users have logged in unless you intend to invalidate
+existing sessions.
+EOF
+}
+
+main() {
+  local mode="pair"
+  local validate_github=""
+  local validate_jwt=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --github-state-only)
+        mode="github"
+        shift
+        ;;
+      --sso-jwt-only)
+        mode="jwt"
+        shift
+        ;;
+      --validate-github)
+        mode="validate"
+        validate_github="${2:?--validate-github requires a value}"
+        shift 2
+        ;;
+      --validate-jwt)
+        mode="validate"
+        validate_jwt="${2:?--validate-jwt requires a value}"
+        shift 2
+        ;;
+      -h|--help)
+        usage
+        exit 0
+        ;;
+      *)
+        echo "Unknown option: $1" >&2
+        usage >&2
+        exit 1
+        ;;
+    esac
+  done
+
+  case "$mode" in
+    github)
+      echo "github_state_secret=$(generate_github_state_secret)"
+      ;;
+    jwt)
+      echo "sso_jwt_secret=$(generate_sso_jwt_secret)"
+      ;;
+    validate)
+      local status=0
+      if [[ -n "$validate_github" ]]; then
+        validate_secret "github_state_secret" "$validate_github" "$MIN_SECRET_BYTES" || status=1
+      fi
+      if [[ -n "$validate_jwt" ]]; then
+        validate_secret "sso_jwt_secret" "$validate_jwt" "$MIN_SECRET_BYTES" || status=1
+      fi
+      if [[ -z "$validate_github" && -z "$validate_jwt" ]]; then
+        echo "Error: use --validate-github and/or --validate-jwt" >&2
+        usage >&2
+        exit 1
+      fi
+      if [[ -n "$validate_github" && -n "$validate_jwt" && "$validate_github" == "$validate_jwt" ]]; then
+        echo "Error: github_state_secret and sso_jwt_secret must be different" >&2
+        status=1
+      fi
+      exit "$status"
+      ;;
+    pair)
+      emit_pair
+      ;;
+  esac
+}
+
+main "$@"
diff --git a/charts/ai/templates/NOTES.txt b/charts/ai/templates/NOTES.txt
new file mode 100644
index 0000000..07dbbff
--- /dev/null
+++ b/charts/ai/templates/NOTES.txt
@@ -0,0 +1,36 @@
+Application URL:
+{{- if .Values.ingress.enabled }}
+  {{- $host := (urlParse (include "ctai.serviceFqdn" .)).host }}
+  https://{{ $host }}/
+{{- else }}
+  Use: kubectl port-forward svc/{{ include "ctai.fullname" . }} 1080:{{ .Values.service.port }}
+{{- end }}
+
+Health checks:
+  Portal/nginx: GET /healthz on port 1080
+  Backend:      GET /actuator/health on port 8080
+
+{{- if eq (include "ctai.propertiesEnabled" .) "true" }}
+
+Configuration:
+  Wizard properties (including deployment secrets) are mounted at {{ include "ctai.propertiesFilePath" . }}.
+  start-ctai sets CTAI_PROPERTIES_FILE to that path; CustomYamlBuilder reads them at startup.
+{{- else }}
+
+Configuration:
+  Env-only mode (no properties Secret). Pass the wizard file with:
+    --set-file ctaiPropertiesFile=./ctai-configuration.properties
+  or use ctaipropertiessecret for a pre-created Secret.
+{{- end }}
+
+{{- if eq (include "ctai.masterKeyEnvEnabled" .) "true" }}
+
+Protected storage master key:
+  Injected from Secret {{ include "ctai.masterKeySecretName" . }} as CTAI_PROTECTED_STORAGE_MASTER_KEY_B64
+  (not in the properties file).
+{{- if eq .Values.masterKey.source "auto" }}
+  Dev auto mode: back up Secret {{ include "ctai.masterKeySecretName" . }} with your database.
+{{- else }}
+  Production: run ./generate-master-key.sh in this chart directory before install.
+{{- end }}
+{{- end }}
diff --git a/charts/ai/templates/_helpers.tpl b/charts/ai/templates/_helpers.tpl
new file mode 100644
index 0000000..ccff0b2
--- /dev/null
+++ b/charts/ai/templates/_helpers.tpl
@@ -0,0 +1,231 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "ctai.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+*/}}
+{{- define "ctai.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 label
+*/}}
+{{- define "ctai.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "ctai.labels" -}}
+helm.sh/chart: {{ include "ctai.chart" . }}
+{{ include "ctai.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "ctai.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "ctai.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Service account name
+*/}}
+{{- define "ctai.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "ctai.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}
+
+{{/*
+Docker registry pull secret payload
+*/}}
+{{- define "ctai.imagePullSecret" }}
+{{- with .Values.imageCredentials }}
+{{- printf "{\"auths\":{\"%s\":{\"username\":\"%s\",\"password\":\"%s\",\"email\":\"%s\",\"auth\":\"%s\"}}}" .registry .username .password .email (printf "%s:%s" .username .password | b64enc) | b64enc }}
+{{- end }}
+{{- end }}
+
+{{/*
+True when the chart should render a properties Secret (not external ref).
+*/}}
+{{- define "ctai.propertiesFromChart" -}}
+{{- if .Values.ctaipropertiessecret.enabled -}}
+false
+{{- else if .Values.ctaiPropertiesFile -}}
+true
+{{- else -}}
+false
+{{- end -}}
+{{- end }}
+
+{{/*
+True when the deployment should mount properties from a Secret.
+*/}}
+{{- define "ctai.propertiesEnabled" -}}
+{{- if .Values.ctaipropertiessecret.enabled -}}
+true
+{{- else if .Values.ctaiPropertiesFile -}}
+true
+{{- else -}}
+false
+{{- end -}}
+{{- end }}
+
+{{/*
+Secret that holds ctai-configuration.properties
+*/}}
+{{- define "ctai.propertiesSecretName" -}}
+{{- if .Values.ctaipropertiessecret.enabled -}}
+{{- .Values.ctaipropertiessecret.ref -}}
+{{- else -}}
+{{- printf "%s-properties" (include "ctai.fullname" .) -}}
+{{- end -}}
+{{- end }}
+
+{{/*
+Full path passed to CTAI_PROPERTIES_FILE
+*/}}
+{{- define "ctai.propertiesFilePath" -}}
+{{- printf "%s/%s" .Values.properties.mountPath .Values.properties.fileName -}}
+{{- end }}
+
+{{/*
+True when deployment should inject CTAI_PROTECTED_STORAGE_MASTER_KEY_B64 from a Secret.
+*/}}
+{{- define "ctai.masterKeyEnvEnabled" -}}
+{{- if eq .Values.masterKey.source "secret" -}}
+{{- if .Values.masterKey.existingSecret -}}true{{- else -}}false{{- end -}}
+{{- else if eq .Values.masterKey.source "auto" -}}
+true
+{{- else -}}
+false
+{{- end -}}
+{{- end }}
+
+{{/*
+True when the chart should render secret-master-key.yaml (auto-generate only).
+*/}}
+{{- define "ctai.masterKeyRenderSecret" -}}
+{{- if eq .Values.masterKey.source "auto" -}}true{{- else -}}false{{- end -}}
+{{- end }}
+
+{{/*
+Secret that holds the protected-storage master key.
+*/}}
+{{- define "ctai.masterKeySecretName" -}}
+{{- if eq .Values.masterKey.source "secret" -}}
+{{- .Values.masterKey.existingSecret -}}
+{{- else -}}
+{{- printf "%s-master-key" (include "ctai.fullname" .) -}}
+{{- end -}}
+{{- end }}
+
+{{/*
+Raw properties text available to Helm at template time (--set-file only).
+Not available when ctaipropertiessecret points at a pre-created Secret.
+*/}}
+{{- define "ctai.rawPropertiesContent" -}}
+{{- if .Values.ctaiPropertiesFile -}}
+{{- .Values.ctaiPropertiesFile -}}
+{{- end -}}
+{{- end }}
+
+{{/*
+Parse service_fqdn= from properties file text.
+*/}}
+{{- define "ctai.serviceFqdnFromContent" -}}
+{{- $line := regexFind "(?m)^service_fqdn=[^\\r\\n#]+" (.content | default "") -}}
+{{- if not $line -}}
+{{- "" -}}
+{{- else -}}
+{{- trimPrefix "service_fqdn=" $line | trim -}}
+{{- end -}}
+{{- end }}
+
+{{/*
+service_fqdn from properties file (empty when unavailable).
+*/}}
+{{- define "ctai.serviceFqdnFromProperties" -}}
+{{- $content := include "ctai.rawPropertiesContent" . -}}
+{{- if $content -}}
+{{- include "ctai.serviceFqdnFromContent" (dict "content" $content) -}}
+{{- else -}}
+{{- "" -}}
+{{- end -}}
+{{- end }}
+
+{{/*
+Public service URL for Ingress and env-only installs.
+Prefers explicit service.fqdn; otherwise service_fqdn from properties.
+Fails when missing, mismatched, or invalid.
+*/}}
+{{- define "ctai.serviceFqdn" -}}
+{{- $explicit := .Values.service.fqdn | default "" | trim -}}
+{{- $derived := include "ctai.serviceFqdnFromProperties" . | trim -}}
+{{- if and $explicit $derived (ne $explicit $derived) -}}
+{{- fail (printf "service.fqdn (%s) does not match service_fqdn in properties (%s)" $explicit $derived) -}}
+{{- end -}}
+{{- $url := "" -}}
+{{- if $explicit -}}
+{{- $url = $explicit -}}
+{{- else if $derived -}}
+{{- $url = $derived -}}
+{{- else if .Values.ctaipropertiessecret.enabled -}}
+{{- fail "ctaipropertiessecret is enabled but service.fqdn is not set. Helm cannot read service_fqdn from a pre-created Secret at template time — set service.fqdn to the same value as service_fqdn in that Secret." -}}
+{{- else -}}
+{{- fail "Public URL is required: set service_fqdn in ctai-configuration.properties (--set-file) or set service.fqdn for env-only installs." -}}
+{{- end -}}
+{{- $parsed := urlParse $url -}}
+{{- if not $parsed.host -}}
+{{- fail (printf "service URL %q is not a valid URL with a host (from service.fqdn or service_fqdn in properties)" $url) -}}
+{{- end -}}
+{{- $url -}}
+{{- end }}
+
+{{/*
+Fail helm template when properties contain unfilled <placeholder> values or URL is invalid.
+*/}}
+{{- define "ctai.validateConfiguration" -}}
+{{- $content := include "ctai.rawPropertiesContent" . -}}
+{{- if $content -}}
+{{- if regexMatch "(?m)^[^#\\n].*<[^>]+>" $content -}}
+{{- fail "ctai-configuration.properties contains unfilled placeholders (non-comment lines with <...>). Copy ctai-configuration.properties.template, replace every placeholder, and try again." -}}
+{{- end -}}
+{{- end -}}
+{{- $_ := include "ctai.serviceFqdn" . -}}
+{{- end }}
+
+{{/*
+Host:port for CTAI_SERVICE_EXTERNAL_IDENTIFIER from the resolved service URL.
+*/}}
+{{- define "ctai.externalIdentifier" -}}
+{{- $parsed := urlParse (include "ctai.serviceFqdn" .) -}}
+{{- if $parsed.port -}}
+{{- printf "%s:%s" $parsed.host ($parsed.port | toString) -}}
+{{- else -}}
+{{- $parsed.host -}}
+{{- end -}}
+{{- end }}
diff --git a/charts/ai/templates/deployment.yaml b/charts/ai/templates/deployment.yaml
new file mode 100644
index 0000000..6e34fa3
--- /dev/null
+++ b/charts/ai/templates/deployment.yaml
@@ -0,0 +1,155 @@
+{{- include "ctai.validateConfiguration" . -}}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "ctai.fullname" . }}
+  labels:
+    {{- include "ctai.labels" . | nindent 4 }}
+spec:
+  replicas: {{ .Values.replicaCount }}
+  selector:
+    matchLabels:
+      {{- include "ctai.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      annotations:
+        {{- if eq (include "ctai.propertiesEnabled" .) "true" }}
+        checksum/properties: {{ include (print $.Template.BasePath "/secret-ctai-properties.yaml") . | sha256sum }}
+        {{- end }}
+        {{- if eq (include "ctai.masterKeyRenderSecret" .) "true" }}
+        checksum/master-key: {{ include (print $.Template.BasePath "/secret-master-key.yaml") . | sha256sum }}
+        {{- end }}
+        {{- with .Values.podAnnotations }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      labels:
+        {{- include "ctai.selectorLabels" . | nindent 8 }}
+    spec:
+      {{- if .Values.imageCredentials.pullSecret }}
+      imagePullSecrets:
+        - name: {{ .Values.imageCredentials.pullSecret }}
+      {{- else if .Values.imageCredentials.enabled }}
+      imagePullSecrets:
+        - name: {{ include "ctai.fullname" . }}-pull-secret
+      {{- end }}
+      serviceAccountName: {{ include "ctai.serviceAccountName" . }}
+      {{- with .Values.podSecurityContext }}
+      securityContext:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.initContainers }}
+      initContainers:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: {{ .Chart.Name }}
+          securityContext:
+            {{- toYaml .Values.securityContext | nindent 12 }}
+          image: "{{ .Values.image.repository }}{{ if .Values.image.digest }}@{{ .Values.image.digest }}{{ else }}:{{ .Values.image.tag | default .Chart.AppVersion }}{{ end }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          env:
+            {{- if eq (include "ctai.propertiesEnabled" .) "true" }}
+            - name: CTAI_PROPERTIES_FILE
+              value: {{ include "ctai.propertiesFilePath" . | quote }}
+            {{- else }}
+            {{- $parsed := urlParse (include "ctai.serviceFqdn" .) }}
+            - name: CTAI_SERVICE_EXTERNAL_PROTOCOL
+              value: {{ $parsed.scheme | quote }}
+            - name: CTAI_SERVICE_EXTERNAL_IDENTIFIER
+              value: {{ include "ctai.externalIdentifier" . | quote }}
+            {{- end }}
+            {{- if eq (include "ctai.masterKeyEnvEnabled" .) "true" }}
+            - name: CTAI_PROTECTED_STORAGE_MASTER_KEY_B64
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "ctai.masterKeySecretName" . }}
+                  key: {{ .Values.masterKey.existingSecretKey | default "CTAI_PROTECTED_STORAGE_MASTER_KEY_B64" }}
+            - name: CTAI_PROTECTED_STORAGE_MASTER_KEY_VERSION
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "ctai.masterKeySecretName" . }}
+                  key: {{ .Values.masterKey.existingSecretVersionKey | default "CTAI_PROTECTED_STORAGE_MASTER_KEY_VERSION" }}
+                  optional: true
+            {{- end }}
+            {{- with .Values.extraEnvVars }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+          {{- if eq (include "ctai.propertiesEnabled" .) "true" }}
+          volumeMounts:
+            - name: ctai-properties
+              mountPath: {{ include "ctai.propertiesFilePath" . }}
+              subPath: {{ .Values.properties.fileName }}
+              readOnly: true
+            {{- with .Values.extraVolumeMounts }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+          {{- else if .Values.extraVolumeMounts }}
+          volumeMounts:
+            {{- toYaml .Values.extraVolumeMounts | nindent 12 }}
+          {{- end }}
+          ports:
+            - name: http
+              containerPort: 1080
+              protocol: TCP
+            - name: backend
+              containerPort: 8080
+              protocol: TCP
+          {{- if .Values.startupProbe.enabled }}
+          startupProbe:
+            httpGet:
+              path: {{ .Values.startupProbe.path }}
+              port: {{ .Values.startupProbe.port }}
+            initialDelaySeconds: {{ .Values.startupProbe.initialDelaySeconds }}
+            periodSeconds: {{ .Values.startupProbe.periodSeconds }}
+            timeoutSeconds: {{ .Values.startupProbe.timeoutSeconds }}
+            failureThreshold: {{ .Values.startupProbe.failureThreshold }}
+          {{- end }}
+          readinessProbe:
+            httpGet:
+              path: {{ .Values.readinessProbe.path }}
+              port: {{ .Values.readinessProbe.port }}
+            initialDelaySeconds: {{ .Values.readinessProbe.initialDelaySeconds }}
+            periodSeconds: {{ .Values.readinessProbe.periodSeconds }}
+            timeoutSeconds: {{ .Values.readinessProbe.timeoutSeconds }}
+            successThreshold: {{ .Values.readinessProbe.successThreshold }}
+            failureThreshold: {{ .Values.readinessProbe.failureThreshold }}
+          livenessProbe:
+            httpGet:
+              path: {{ .Values.livenessProbe.path }}
+              port: {{ .Values.livenessProbe.port }}
+            initialDelaySeconds: {{ .Values.livenessProbe.initialDelaySeconds }}
+            periodSeconds: {{ .Values.livenessProbe.periodSeconds }}
+            timeoutSeconds: {{ .Values.livenessProbe.timeoutSeconds }}
+            successThreshold: {{ .Values.livenessProbe.successThreshold }}
+            failureThreshold: {{ .Values.livenessProbe.failureThreshold }}
+          {{- with .Values.resources }}
+          resources:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+        {{- with .Values.extraContainers }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      {{- if eq (include "ctai.propertiesEnabled" .) "true" }}
+      volumes:
+        - name: ctai-properties
+          secret:
+            secretName: {{ include "ctai.propertiesSecretName" . }}
+        {{- with .Values.extraVolumes }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      {{- else if .Values.extraVolumes }}
+      volumes:
+        {{- toYaml .Values.extraVolumes | nindent 8 }}
+      {{- 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/ai/templates/ingress-class.yaml b/charts/ai/templates/ingress-class.yaml
new file mode 100644
index 0000000..7b61fc9
--- /dev/null
+++ b/charts/ai/templates/ingress-class.yaml
@@ -0,0 +1,10 @@
+{{- if and .Values.ingress.enabled (eq .Values.ingress.className "codetogether-nginx") }}
+apiVersion: networking.k8s.io/v1
+kind: IngressClass
+metadata:
+  labels:
+    app.kubernetes.io/component: controller
+  name: codetogether-nginx
+spec:
+  controller: k8s.io/ingress-nginx
+{{- end }}
diff --git a/charts/ai/templates/ingress.yaml b/charts/ai/templates/ingress.yaml
new file mode 100644
index 0000000..6b677cf
--- /dev/null
+++ b/charts/ai/templates/ingress.yaml
@@ -0,0 +1,51 @@
+{{- include "ctai.validateConfiguration" . -}}
+{{- if .Values.ingress.enabled }}
+{{- $fullName := include "ctai.fullname" . }}
+{{- $svcPort := .Values.service.port }}
+{{- $host := (urlParse (include "ctai.serviceFqdn" .)).host }}
+{{- $kver := .Capabilities.KubeVersion.Version | default .Capabilities.KubeVersion.GitVersion }}
+{{- $hasIngressV1 := .Capabilities.APIVersions.Has "networking.k8s.io/v1/Ingress" }}
+{{- $isIngressV1 := or $hasIngressV1 (semverCompare ">=1.19-0" $kver) }}
+{{- if $isIngressV1 }}
+apiVersion: networking.k8s.io/v1
+{{- else }}
+apiVersion: networking.k8s.io/v1beta1
+{{- end }}
+kind: Ingress
+metadata:
+  name: {{ $fullName }}
+  labels:
+    {{- include "ctai.labels" . | nindent 4 }}
+  {{- with .Values.ingress.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  {{- if and .Values.ingress.className $isIngressV1 }}
+  ingressClassName: {{ .Values.ingress.className }}
+  {{- end }}
+  {{- if .Values.ingress.tls }}
+  tls:
+    - hosts:
+        - {{ $host | quote }}
+      secretName: {{ .Values.ingress.tls.secretName }}
+  {{- end }}
+  rules:
+    - host: {{ $host | quote }}
+      http:
+        paths:
+          - path: /
+            {{- if $isIngressV1 }}
+            pathType: Prefix
+            {{- end }}
+            backend:
+              {{- if $isIngressV1 }}
+              service:
+                name: {{ $fullName }}
+                port:
+                  number: {{ $svcPort }}
+              {{- else }}
+              serviceName: {{ $fullName }}
+              servicePort: {{ $svcPort }}
+              {{- end }}
+{{- end }}
diff --git a/charts/ai/templates/secret-ctai-properties.yaml b/charts/ai/templates/secret-ctai-properties.yaml
new file mode 100644
index 0000000..652cb3e
--- /dev/null
+++ b/charts/ai/templates/secret-ctai-properties.yaml
@@ -0,0 +1,12 @@
+{{- if eq (include "ctai.propertiesFromChart" .) "true" }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "ctai.propertiesSecretName" . }}
+  labels:
+    {{- include "ctai.labels" . | nindent 4 }}
+type: Opaque
+stringData:
+  {{ .Values.properties.fileName }}: |-
+{{ .Values.ctaiPropertiesFile | nindent 4 }}
+{{- end }}
diff --git a/charts/ai/templates/secret-master-key.yaml b/charts/ai/templates/secret-master-key.yaml
new file mode 100644
index 0000000..f81cc02
--- /dev/null
+++ b/charts/ai/templates/secret-master-key.yaml
@@ -0,0 +1,18 @@
+{{- if eq (include "ctai.masterKeyRenderSecret" .) "true" }}
+{{- $secretName := include "ctai.masterKeySecretName" . -}}
+{{- $existing := (lookup "v1" "Secret" .Release.Namespace $secretName) -}}
+{{- $keyB64 := .Values.masterKey.existingSecretKey | default "CTAI_PROTECTED_STORAGE_MASTER_KEY_B64" -}}
+{{- $keyVersion := .Values.masterKey.existingSecretVersionKey | default "CTAI_PROTECTED_STORAGE_MASTER_KEY_VERSION" -}}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ $secretName }}
+  labels:
+    {{- include "ctai.labels" . | nindent 4 }}
+  annotations:
+    helm.sh/resource-policy: keep
+type: Opaque
+stringData:
+  {{ $keyB64 }}: {{ if $existing }}{{ index $existing.data $keyB64 | b64dec | quote }}{{ else if .Values.masterKey.masterKeyB64 }}{{ .Values.masterKey.masterKeyB64 | quote }}{{ else }}{{ randBytes 32 | b64enc | b64dec | quote }}{{ end }}
+  {{ $keyVersion }}: {{ if $existing }}{{ index $existing.data $keyVersion | b64dec | default "v1" | quote }}{{ else }}{{ .Values.masterKey.masterKeyVersion | default "v1" | quote }}{{ end }}
+{{- end }}
diff --git a/charts/ai/templates/secret-pullimage.yaml b/charts/ai/templates/secret-pullimage.yaml
new file mode 100644
index 0000000..a4423a2
--- /dev/null
+++ b/charts/ai/templates/secret-pullimage.yaml
@@ -0,0 +1,12 @@
+{{- if .Values.imageCredentials.pullSecret }}
+{{- else if .Values.imageCredentials.enabled }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "ctai.fullname" . }}-pull-secret
+  labels:
+    {{- include "ctai.labels" . | nindent 4 }}
+type: kubernetes.io/dockerconfigjson
+data:
+  .dockerconfigjson: {{ template "ctai.imagePullSecret" . }}
+{{- end }}
diff --git a/charts/ai/templates/service.yaml b/charts/ai/templates/service.yaml
new file mode 100644
index 0000000..5b30529
--- /dev/null
+++ b/charts/ai/templates/service.yaml
@@ -0,0 +1,19 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "ctai.fullname" . }}
+  labels:
+    {{- include "ctai.labels" . | nindent 4 }}
+  {{- with .Values.service.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  type: {{ .Values.service.type }}
+  ports:
+    - port: {{ .Values.service.port }}
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    {{- include "ctai.selectorLabels" . | nindent 4 }}
diff --git a/charts/ai/templates/serviceaccount.yaml b/charts/ai/templates/serviceaccount.yaml
new file mode 100644
index 0000000..0cdbb60
--- /dev/null
+++ b/charts/ai/templates/serviceaccount.yaml
@@ -0,0 +1,12 @@
+{{- if .Values.serviceAccount.create }}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ include "ctai.serviceAccountName" . }}
+  labels:
+    {{- include "ctai.labels" . | nindent 4 }}
+  {{- with .Values.serviceAccount.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+{{- end }}
diff --git a/charts/ai/templates/tests/test-connection.yaml b/charts/ai/templates/tests/test-connection.yaml
new file mode 100644
index 0000000..5e62d6b
--- /dev/null
+++ b/charts/ai/templates/tests/test-connection.yaml
@@ -0,0 +1,22 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: "{{ include "ctai.fullname" . }}-test-connection"
+  labels:
+    {{- include "ctai.labels" . | nindent 4 }}
+  annotations:
+    "helm.sh/hook": test
+spec:
+  restartPolicy: Never
+  containers:
+    - name: wget
+      image: busybox:1.36
+      command: ['wget']
+      args: ['{{ printf "http://%s:%d/healthz" (include "ctai.fullname" .) (int .Values.service.port) }}']
+  {{- if .Values.imageCredentials.pullSecret }}
+  imagePullSecrets:
+    - name: {{ .Values.imageCredentials.pullSecret }}
+  {{- else if .Values.imageCredentials.enabled }}
+  imagePullSecrets:
+    - name: {{ include "ctai.fullname" . }}-pull-secret
+  {{- end }}
diff --git a/charts/ai/values.yaml b/charts/ai/values.yaml
new file mode 100644
index 0000000..bae3a71
--- /dev/null
+++ b/charts/ai/values.yaml
@@ -0,0 +1,134 @@
+# Default values for CodeTogether AI on Kubernetes.
+# Based on charts/intel from CodeTogether-Deployment; adapted for the ct-ai
+# codetogether-ai customer image and start-ctai entrypoint.
+#
+# Kubernetes required version: v1.19+
+#
+# Configuration modes (pick one):
+#   1. Properties file (recommended):
+#        helm install ctai . \
+#          --set-file ctaiPropertiesFile=./ctai-configuration.properties
+#   2. Pre-created Secret (GitOps):
+#        ctaipropertiessecret.enabled=true, ctaipropertiessecret.ref=...
+#   3. Env-only — leave properties empty; set service.fqdn and extraEnvVars.
+nameOverride: ""
+fullnameOverride: ""
+
+image:
+  repository: hub.edge.codetogether.com/releases/codetogether-ai
+  pullPolicy: Always
+  tag: "latest"
+  digest: ""
+
+imageCredentials:
+  # pullSecret: "my-customer-pull-secret"
+  enabled: true
+  registry: hub.edge.codetogether.com
+  username: "my-customer-username"
+  password: "my-customer-password"
+  email: unused
+
+# Public HTTPS URL (same meaning as service_fqdn in ctai-configuration.properties).
+# Optional when using --set-file: service_fqdn is read from the properties file
+# instead. Required for GitOps (pre-created properties Secret) and env-only installs.
+service:
+  fqdn: ""
+  annotations: {}
+  type: ClusterIP
+  port: 1080
+
+# Properties file contents. Set at install time with --set-file:
+#   --set-file ctaiPropertiesFile=./ctai-configuration.properties
+ctaiPropertiesFile: ""
+
+# Protected-storage master key — delivered via dedicated Secret as CTAI_PROTECTED_STORAGE_MASTER_KEY_B64,
+# not in the properties file. Production workflow:
+#   1. Run generate-master-key.sh on your workstation and kubectl apply the Secret.
+#   2. Set masterKey.existingSecret to that Secret name (default: ctai-master-key).
+masterKey:
+  source: secret       # secret (production) | auto (dev only) | external (advanced — chart does not inject)
+  existingSecret: ctai-master-key
+  existingSecretKey: CTAI_PROTECTED_STORAGE_MASTER_KEY_B64
+  existingSecretVersionKey: CTAI_PROTECTED_STORAGE_MASTER_KEY_VERSION
+  # Used only when source=auto for non-production testing.
+  masterKeyB64: ""
+  masterKeyVersion: v1
+
+# Use a pre-created Secret instead of chart-generated properties.
+# Secret must contain key: ctai-configuration.properties
+ctaipropertiessecret:
+  enabled: false
+  ref: ""
+
+properties:
+  # Matches Dockerfile layout and start-ctai CTAI_CONFIGURATION_HOME.
+  mountPath: /opt/ctai/server/config
+  fileName: ctai-configuration.properties
+
+ingress:
+  enabled: true
+  annotations:
+    # OTLP telemetry batches can exceed the nginx-ingress 1MB default body size
+    # and get rejected with 413 before reaching the backend. Raise the limit so
+    # tracker uploads land. The in-pod nginx already allows 32m, so the ingress
+    # hop is the binding constraint. Overlays may add deployment-specific
+    # annotations (e.g. external-dns); Helm deep-merges them with this default.
+    nginx.ingress.kubernetes.io/proxy-body-size: "16m"
+  # className: codetogether-nginx
+  tls:
+    secretName: codetogether-ai-tls
+
+serviceAccount:
+  create: true
+  annotations: {}
+  name: "codetogether-ai"
+
+podAnnotations: {}
+podSecurityContext:
+  fsGroup: 2200
+
+securityContext:
+  runAsNonRoot: true
+  runAsUser: 2200
+  runAsGroup: 2200
+  allowPrivilegeEscalation: false
+
+resources: {}
+
+readinessProbe:
+  path: /healthz
+  port: http
+  initialDelaySeconds: 30
+  periodSeconds: 30
+  timeoutSeconds: 10
+  successThreshold: 1
+  failureThreshold: 6
+
+livenessProbe:
+  path: /actuator/health
+  port: backend
+  initialDelaySeconds: 90
+  periodSeconds: 30
+  timeoutSeconds: 10
+  successThreshold: 1
+  failureThreshold: 6
+
+startupProbe:
+  enabled: true
+  path: /actuator/health
+  port: backend
+  initialDelaySeconds: 30
+  periodSeconds: 10
+  timeoutSeconds: 10
+  failureThreshold: 30
+
+initContainers: []
+nodeSelector: {}
+tolerations: []
+affinity: {}
+replicaCount: 1
+
+extraEnvVars: []
+extraVolumes: []
+extraVolumeMounts: []
+extraContainers: []

From d00abfb99c13c04baf1ee9b5c10a04b396d42d04 Mon Sep 17 00:00:00 2001
From: Daniel Garcia Rico <daniel@codetogether.com>
Date: Tue, 30 Jun 2026 18:53:36 +0000
Subject: [PATCH 2/4] Address CodeTogether AI chart review nits

---
 .github/workflows/helm-template-check.yml |  9 +++++++++
 charts/ai/README.md                       | 11 +++++++++++
 charts/ai/values.yaml                     |  4 ++--
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/helm-template-check.yml b/.github/workflows/helm-template-check.yml
index 5ebbc90..df5e251 100644
--- a/.github/workflows/helm-template-check.yml
+++ b/.github/workflows/helm-template-check.yml
@@ -32,6 +32,15 @@ jobs:
         run: |
           helm template intel ./charts/intel --values ./charts/intel/values.yaml
 
+      - name: Validate AI Chart
+        run: |
+          helm lint ./charts/ai
+          helm template test ./charts/ai \
+            --set-file ctaiPropertiesFile=./charts/ai/ctai-configuration.properties.template \
+            --set service.fqdn=https://example.codetogether.io \
+            --set imageCredentials.username=test \
+            --set imageCredentials.password=test
+
       - name: Validate Live Chart
         run: |
           helm template live ./charts/live --values ./charts/live/values.yaml
diff --git a/charts/ai/README.md b/charts/ai/README.md
index a407001..6a5da3d 100644
--- a/charts/ai/README.md
+++ b/charts/ai/README.md
@@ -120,6 +120,17 @@ Ingress host and TLS are derived from `service_fqdn` in
 `ctai-configuration.properties`. If you also set `service.fqdn` in Helm values,
 it must exactly match `service_fqdn`.
 
+By default, the chart does not set `ingress.className`, matching the
+CodeTogether Intel chart. Clusters without a default IngressClass should set one
+explicitly:
+
+```bash
+--set ingress.className=nginx
+```
+
+If you set `ingress.className=codetogether-nginx`, the chart also creates a
+matching `IngressClass`.
+
 ## Configuration
 
 The following table lists the primary configurable parameters and defaults.
diff --git a/charts/ai/values.yaml b/charts/ai/values.yaml
index bae3a71..5ae934f 100644
--- a/charts/ai/values.yaml
+++ b/charts/ai/values.yaml
@@ -71,8 +71,8 @@ ingress:
     # OTLP telemetry batches can exceed the nginx-ingress 1MB default body size
     # and get rejected with 413 before reaching the backend. Raise the limit so
     # tracker uploads land. The in-pod nginx already allows 32m, so the ingress
-    # hop is the binding constraint. Overlays may add deployment-specific
-    # annotations (e.g. external-dns); Helm deep-merges them with this default.
+    # hop is the binding constraint. Additional ingress annotations
+    # (e.g. external-dns hostname) merge with this default.
     nginx.ingress.kubernetes.io/proxy-body-size: "16m"
   # className: codetogether-nginx
   tls:

From af74119775e6ce6cf84bfbc5dd0506f9a20dc0b2 Mon Sep 17 00:00:00 2001
From: Daniel Garcia Rico <daniel@codetogether.com>
Date: Tue, 30 Jun 2026 19:07:10 +0000
Subject: [PATCH 3/4] Clarify CodeTogether AI chart install docs

---
 charts/ai/README.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/charts/ai/README.md b/charts/ai/README.md
index 6a5da3d..d43f195 100644
--- a/charts/ai/README.md
+++ b/charts/ai/README.md
@@ -170,6 +170,12 @@ The following table lists the primary configurable parameters and defaults.
 | `livenessProbe.path` | Liveness endpoint on port 8080 | `/actuator/health` |
 | `startupProbe.enabled` | Enable startup probe | `true` |
 
+`image.tag` controls which container image the Deployment pulls at install or
+upgrade time. `appVersion` in `Chart.yaml` is chart metadata only; it does not
+pin the running image unless you set `image.tag` or `image.digest`. Most
+installations can use the default `latest` tag and receive hub.edge updates on
+`helm upgrade` after the registry tag moves.
+
 ## Pre-Created Properties Secret
 
 For GitOps workflows, create and manage the properties Secret outside Helm:
@@ -202,10 +208,13 @@ Render the chart locally before installing:
 ```bash
 helm template codetogether-ai codetogether/codetogether-ai \
   --set-file ctaiPropertiesFile=./ctai-configuration.properties \
+  --set service.fqdn=https://ai.example.com \
   --set imageCredentials.username=test \
   --set imageCredentials.password=test
 ```
 
+`service.fqdn` must match `service_fqdn` in the properties file when both are set.
+
 At runtime, CodeTogether AI validates the mounted configuration before the
 service starts. If validation fails, the pod exits and logs a block beginning
 with `Configuration errors:`.
@@ -230,6 +239,18 @@ helm upgrade codetogether-ai codetogether/codetogether-ai \
   --set imageCredentials.password=replace-with-hub-edge-password
 ```
 
+Using `latest` is fine for most installs. Pin a known GA build only when change
+control requires a fixed container version:
+
+```bash
+helm upgrade codetogether-ai codetogether/codetogether-ai \
+  --namespace codetogether-ai \
+  --set-file ctaiPropertiesFile=./ctai-configuration.properties \
+  --set imageCredentials.username=replace-with-hub-edge-username \
+  --set imageCredentials.password=replace-with-hub-edge-password \
+  --set image.tag=0.1.1204
+```
+
 The Deployment rolls when the chart-managed properties Secret changes.
 
 ## Uninstall

From 327e6a85adea2d84298519abee15564f50c44868 Mon Sep 17 00:00:00 2001
From: Daniel Garcia Rico <daniel@codetogether.com>
Date: Tue, 30 Jun 2026 20:29:32 +0000
Subject: [PATCH 4/4] Document AI chart Postgres prerequisites

---
 charts/ai/README.md                           | 34 +++++++++++++++++++
 .../ai/ctai-configuration.properties.template |  6 ++--
 2 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/charts/ai/README.md b/charts/ai/README.md
index d43f195..565cd4f 100644
--- a/charts/ai/README.md
+++ b/charts/ai/README.md
@@ -15,6 +15,34 @@ storage master key is stored in a separate Kubernetes Secret.
 - A TLS Secret for Ingress when `ingress.enabled=true`.
 - CodeTogether-provided credentials for `hub.edge.codetogether.com`.
 
+## PostgreSQL Prerequisites
+
+This chart does not install Postgres. Provide an external database reachable
+from the cluster and configure it in `ctai-configuration.properties`.
+
+Before the first pod starts, run the database grants as a Postgres admin. A
+dedicated application user is recommended:
+
+```sql
+GRANT ALL PRIVILEGES ON DATABASE <db> TO <app_user>;
+GRANT CREATE ON DATABASE <db> TO <app_user>;
+ALTER DATABASE <db> OWNER TO <app_user>;
+ALTER ROLE <app_user> BYPASSRLS;
+```
+
+`BYPASSRLS` matches the production application role shape. CodeTogether uses
+row-level security on platform tables, including `oauth2_cache`, where SSO
+stores OAuth state. Without it, SSO redirects can fail because OAuth state
+cannot be inserted or read.
+
+Managed Postgres superusers, such as DigitalOcean's `doadmin`, bypass RLS but
+are not recommended for production application connections. If your provider
+requires SSL, append `?sslmode=require` to the JDBC URL, for example:
+
+```properties
+database_url=jdbc:postgresql://postgres.example.internal:5432/codetogether?sslmode=require
+```
+
 ## Install
 
 ### 1. Prepare the configuration file
@@ -71,6 +99,8 @@ sso_provider1_client_secret=replace-with-google-client-secret
 sso_provider1_client_issuer_url=https://accounts.google.com
 ```
 
+Before testing SSO, complete the [PostgreSQL prerequisites](#postgresql-prerequisites).
+
 ### 3. Create the TLS Secret
 
 Create the TLS Secret in the namespace where CodeTogether AI will run. The
@@ -227,6 +257,10 @@ kubectl logs -n codetogether-ai deploy/codetogether-ai --previous
 Common causes include unfilled example values, Postgres connectivity problems,
 missing or changed master-key Secret, an HTTP `service_fqdn`, missing TLS
 Secret, or SSO provider settings that do not match the registered redirect URI.
+If login fails after returning from Google or another identity provider with
+`authorization_request_not_found`, check that the database user has `BYPASSRLS`
+and that the registered OAuth redirect URI exactly matches
+`{service_fqdn}/api/v1/auth/sso/provider/callback`.
 
 ## Upgrade
 
diff --git a/charts/ai/ctai-configuration.properties.template b/charts/ai/ctai-configuration.properties.template
index 8b74da0..7b78b54 100644
--- a/charts/ai/ctai-configuration.properties.template
+++ b/charts/ai/ctai-configuration.properties.template
@@ -72,9 +72,11 @@ github_state_secret=replace-with-generated-github-state-secret
 # Or run: ./generate-properties-secrets.sh (in this chart directory)
 sso_jwt_secret=replace-with-generated-sso-jwt-secret
 
-# Register the full callback URL at your IdP:
-#   https://<service_fqdn>/api/v1/auth/sso/provider/callback
+# Register the full callback URL at your IdP. Full callback URL:
+#   {service_fqdn}/api/v1/auth/sso/provider/callback
+# It must match your IdP registration exactly.
 # Example: https://mycompany.codetogether.com/api/v1/auth/sso/provider/callback
+sso_redirect_uri=/api/v1/auth/sso/provider/callback
 #
 # -----------------------------------------------------------------------------
 # SSO providers