Self-Hosting Intelligence

Ensure `kubectl` points to the cluster that will run Intelligence.

```bash title="Terminal"
kubectl config current-context
kubectl auth can-i create namespace --all-namespaces
```

The context shown should be the target cluster, and the permission check should return `yes`. If either is wrong, fix your kubeconfig before proceeding.

These components are cluster-wide and installed once per cluster, independently of the application chart.

<Tabs items={["AWS (EKS)", "On-prem / generic"]}>
  <Tab value="AWS (EKS)">
    ```bash title="Terminal"
    # AWS Load Balancer Controller (kube-system)
    helm repo add eks https://aws.github.io/eks-charts
    helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
      -n kube-system \
      --set clusterName=<YOUR_CLUSTER_NAME>

    # cert-manager
    helm repo add jetstack https://charts.jetstack.io
    helm install cert-manager jetstack/cert-manager \
      -n cert-manager --create-namespace \
      --set installCRDs=true

    # External Secrets Operator
    helm repo add external-secrets https://charts.external-secrets.io
    helm install external-secrets external-secrets/external-secrets \
      -n external-secrets --create-namespace
    ```
  </Tab>
  <Tab value="On-prem / generic">
    ```bash title="Terminal"
    # NGINX Ingress Controller
    helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
    helm install ingress-nginx ingress-nginx/ingress-nginx \
      -n ingress-nginx --create-namespace

    # cert-manager
    helm repo add jetstack https://charts.jetstack.io
    helm install cert-manager jetstack/cert-manager \
      -n cert-manager --create-namespace \
      --set installCRDs=true
    ```
  </Tab>
</Tabs>

After each controller is running, its pods should be `Ready` in their respective namespaces.

Intelligence needs Postgres, Redis, and an OIDC issuer. You can either point the chart at managed services you already run, or enable the bundled Bitnami subcharts for in-cluster Postgres and Redis (appropriate for evaluation and small self-hosted installs).

**Using managed services (recommended for production):**

- Create a Postgres database and user. Record the host, port (default `5432`), database name, username, and password.
- Create a Redis instance with TLS enabled. Record the host, port (default `6379`), and password.
- Configure an OIDC client in your identity provider. Record the issuer URL, client ID, and client secret.

**Using the bundled in-cluster subcharts:**

Set `postgresql.enabled: true` and `redis-subchart.enabled: true` in your values file (covered in the next step). A matching `StorageClass` must exist in the cluster. The bundled Keycloak subchart is available via `keycloak.enabled: true` if you also need a quick OIDC provider for evaluation; do not use the bundled Keycloak for production workloads.

The chart ships with example values files for the two most common shapes. Pull the chart, then copy the example closest to your environment.

```bash title="Terminal"
helm pull oci://ghcr.io/copilotkit/charts/copilot-intelligence --version 0.1.0 --untar

# AWS-flavored (ALB, IRSA, External Secrets from AWS Secrets Manager)
cp copilot-intelligence/values-aws-example.yaml my-values.yaml

# Or on-prem-flavored (nginx, manual Kubernetes Secrets)
cp copilot-intelligence/values-onprem-example.yaml my-values.yaml
```

Edit `my-values.yaml` to set at minimum:

- `database.host`, `database.port`, `database.name` — your Postgres connection
- `redis.host`, `redis.port`, `redis.tls` — your Redis connection
- `auth.issuer` — your OIDC provider's issuer URL
- `auth.existingSecret` — name of the Kubernetes Secret containing `auth-secret`, `auth-client-id`, `auth-client-secret`
- `ingress.ui.host` — the hostname users will load the Intelligence UI on (for example `intelligence.example.com`)
- `ingress.api.host` — an optional dedicated API hostname (defaults to `ingress.ui.host`)
- `ingress.tls` — TLS configuration for the hosts above

See the [Configuration reference](#configuration-reference) section for the full set of values.

You have two paths — External Secrets Operator (recommended) or direct Kubernetes Secrets.

**External Secrets Operator:**

1. Ensure your secret backend (AWS Secrets Manager, Vault, etc.) has entries for the database URL, Redis URL, and auth credentials.
2. Create a `ClusterSecretStore` (or `SecretStore`) that references that backend.
3. In `my-values.yaml`, set `externalSecrets.enabled: true`, `externalSecrets.store.kind`, and `externalSecrets.store.name` to match. The chart generates `ExternalSecret` resources that sync those entries into Kubernetes Secrets at the names `app-api` expects.

**Direct Kubernetes Secrets:**

Set `externalSecrets.enabled: false` in your values file, then create the Secrets manually:

```bash title="Terminal"
kubectl create namespace copilot-intelligence

kubectl create secret generic cpki-db \
  --from-literal=database-url='postgresql://user:pass@host:5432/intelligence' \
  -n copilot-intelligence

kubectl create secret generic cpki-redis \
  --from-literal=redis-url='rediss://:password@host:6379' \
  -n copilot-intelligence

kubectl create secret generic cpki-auth \
  --from-literal=auth-secret='<32+ character random string>' \
  --from-literal=auth-client-id='<OIDC client id>' \
  --from-literal=auth-client-secret='<OIDC client secret>' \
  -n copilot-intelligence
```

The exact Secret names referenced in your values file must match whatever you create.

The chart can run database schema migrations as a pre-install `Job`. This is **disabled by default** (`migrations.enabled: false`). If you want the chart to apply migrations for you on install, set the following in `my-values.yaml`:

```yaml title="my-values.yaml"
migrations:
  enabled: true
```

With this enabled, `helm install` blocks the rollout until the migrations Job reports `Completed`. Leave it disabled if you manage schema migrations out-of-band (for example, via your existing CI/CD or DBA pipeline).

```bash title="Terminal"
helm install copilot-intelligence ./copilot-intelligence \
  -f my-values.yaml \
  -n copilot-intelligence \
  --create-namespace \
  --wait \
  --timeout 10m
```

`--wait` blocks until the `Deployments` report healthy replicas; `--timeout 10m` allows enough time for image pulls and (if you enabled it in the previous step) the initial database migration job.

Check that every pod is `Running` and the ingress is ready:

```bash title="Terminal"
kubectl get pods -n copilot-intelligence
kubectl get ingress -n copilot-intelligence
```

You should see `app-api`, `app-frontend`, and — if enabled — `realtime-gateway` pods running. If you opted into migrations (`migrations.enabled: true`, see the values step above), the migrations `Job` will also appear as `Completed`; if you left migrations disabled, no Job is created.

Confirm the API health check reports `ok`:

```bash title="Terminal"
curl https://<ingress.api.host>/api/health
```

The endpoint returns `200 OK` only when the database is reachable — a failed health check is almost always a database connectivity problem.

Finally, browse to `https://<ingress.ui.host>` and log in via your OIDC provider. A successful login confirms end-to-end wiring.

**Upgrade** — bump the chart version in your `helm pull` command, regenerate example values to diff against, then run:

```bash title="Terminal"
helm upgrade copilot-intelligence ./copilot-intelligence \
  -f my-values.yaml \
  -n copilot-intelligence \
  --wait
```

**Uninstall** — releases leave PersistentVolumes in place by default if you enabled bundled subcharts; delete them manually if you intend to tear down state.

```bash title="Terminal"
helm uninstall copilot-intelligence -n copilot-intelligence
```