Version: 2026.09

Istari Platform Installation

Istari Platform installation process consists of two parts:

Secrets: The Istari Platform requires a few secrets to be created in the Kubernetes cluster. These secrets are used to store sensitive information related to the Istari Platform and its components.
Istari Platform Helm Chart: The Istari Platform is installed using a Helm chart. The Helm chart contains all the necessary configurations and resources required to deploy the Istari Platform in a Kubernetes cluster.

Secrets

info

Make sure to replace <customer_istari_fqdn> with the actual domain used for the Istari Digital platform, e.g. istari.customer_domain.com.

Frontend Service Secret

The Istari Platform requires a secret for the frontend service. This secret is used to store sensitive information related to file storage and access. The secret should be created in the Kubernetes cluster where the Istari Platform is deployed.

istari-frontend-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: istari-frontend
stringData:
  ISTARI_REGISTRY_URL: "https://registry.<customer_istari_fqdn>"
  VITE_DOCUMENTATION_URL: "https://docs.istaridigital.com"
  VITE_DOMAIN: "<customer_istari_fqdn>"
  VITE_FILE_AUTH_ENDPOINT: "https://registry.<customer_istari_fqdn>"
  VITE_FS_URL: "https://registry.<customer_istari_fqdn>"
  # Leave commented out. From chart 6.0 the chart supplies this value itself,
  # as https://api.<common.mainFqdn> (or common.apiFqdnOverride), routing the frontend's registry traffic
  # through <base>/registry instead of the direct endpoint above. Uncomment
  # only to override the chart's value: a key set here wins over the one the
  # chart injects, so a stale value survives disabling the gateway.
  # VITE_ISTARI_DIGITAL_API_URL: "https://api.<customer_istari_fqdn>"
  VITE_LOGOUT_REDIRECT_URI: "https://<customer_istari_fqdn>"
  VITE_REDIRECT_URI: "https://<customer_istari_fqdn>"
  VITE_UI_URL: "https://<customer_istari_fqdn>"
  VITE_ZITADEL_AUTHORITY: "https://zitadel.<customer_istari_fqdn>"
  ZITADEL_CLOUD_URL: "https://zitadel.<customer_istari_fqdn>"
  VITE_CLIENT_ID: "<zitadel_client_id>"
  VITE_ZITADEL_CLIENT_ID: "<zitadel_client_id>"
  ZITADEL_CLOUD_CLIENT_ID: "<zitadel_client_id>"
  # Set VITE_ITAR to "true" if your platform will be hosting ITAR/CUI data 
  VITE_ITAR: "false"
  # Following values are required as is
  BASE_URL: ""
  ZITADEL_CLOUD_REQUEST_SCOPE: "openid profile email offline_access urn:zitadel:iam:org:project:id:zitadel:aud"
  VITE_SENTRY_ENABLED: "false"
  VITE_SENTRY_AUTH_TOKEN: ""
  VITE_SENTRY_DSN: ""

info

Make sure to replace <customer_istari_fqdn> with the actual domain used for the Istari Digital platform, e.g. istari.customer_domain.com.

Note the following:

zitadel_domain is obtained from the Zitadel Install step
zitadel_client_id is obtained from the Zitadel Install step - Create an OIDC Application for Frontend
The Notifications inbox is available in the sidebar once NATS eventing is configured. See Notifications.
VITE_ISTARI_DIGITAL_API_URL stays commented out above. From chart 6.0 the chart sets it for you, to https://api.<customer_istari_fqdn> (from common.mainFqdn, or the host in common.apiFqdnOverride), so set it in this Secret only to override that value. See API Gateway for what enabling the gateway changes.

You will then create the secret by running the following command:

kubectl apply -f istari-frontend-secret.yaml

Registry Service Secret

warning

What is currently referred to as "fileservice" will be renamed to "registry-service" as part of a future release. In preparation for this we have chosen to use the subdomain registry below.

The Istari Platform requires a secret for fileservice. This secret is used to store sensitive information related to file storage and access. The secret should be created in the Kubernetes cluster where the Istari Platform is deployed.

info

Istari Digital needs to grant access to license holder and license key to the customer. Please reach out to your Istari Digital Customer Success representative if you do not already have these.

istari-fileservice-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: istari-fileservice
stringData:
  FILE_SERVICE_AUTHZED_HOST: "spicedb" # Change to host if setting FILE_SERVICE_AUTHZED_NO_TLS to "false"
  FILE_SERVICE_AUTHZED_NO_TLS: "true" # Set this to "false" if you want to require TLS with SpiceDB
  FILE_SERVICE_AUTHZED_PORT: "50051" # Change to 443 if setting FILE_SERVICE_AUTHZED_NO_TLS to "false"
  FILE_SERVICE_AUTHZED_TOKEN: "<spicedb_preshared_key>"
  FILE_SERVICE_CORS_ALLOW_ORIGINS: '["https://<customer_istari_fqdn>", "https://v2.<customer_istari_fqdn>"]'
  FILE_SERVICE_DATABASE_URL: "postgresql://registry:<password>@<rds_host>:5432/registry"
  FILE_SERVICE_LICENSE_HOLDER: "<license_holder>"
  FILE_SERVICE_LICENSE_KEY: "<license_key>"
  FILE_SERVICE_OBJECT_STORE_SCHEME_NAME: "s3"  # Set to `wasbs` if using Windows Azure Blob Storage instead of AWS S3
  FILE_SERVICE_OBJECT_STORE_ACCESS_KEY: "<AWS_S3_access_key OR Azure_storage_account_name>"
  FILE_SERVICE_OBJECT_STORE_SECRET_KEY: "<AWS_S3_secret_key OR Azure_storage_container_access_key>"
  FILE_SERVICE_OBJECT_STORE_NAME: "<AWS_S3_bucket OR Azure_storage_container>"
  FILE_SERVICE_OBJECT_STORE_ENDPOINT_URL: "https://<AWS_S3_endpoint_url OR Azure_endpoint_url>" # See https://docs.aws.amazon.com/general/latest/gr/s3.html and https://learn.microsoft.com/en-us/azure/storage/common/storage-account-overview#standard-endpoints
  FILE_SERVICE_OBJECT_STORE_REGION: "<AWS_S3_region>" # Not used with Azure Blob Storage
  FILE_SERVICE_ZITADEL_DOMAIN: "https://zitadel.<customer_istari_fqdn>"
  FILE_SERVICE_ZITADEL_JWKS_URL: "https://zitadel.<customer_istari_fqdn>/oauth/v2/keys"  # Deprecated as of 2025.07.1 release
  FILE_SERVICE_ZITADEL_CLIENT_ID: "<zitadel_client_id>"
  FILE_SERVICE_ZITADEL_PROJECT_ID: "<zitadel_project_id>"
  FILE_SERVICE_ZITADEL_PROJECT_GRANT_ID: "<zitadel_project_grant_id>"
  FILE_SERVICE_ZITADEL_SECRET: "<zitadel_secret>"
  FILE_SERVICE_ZITADEL_USER_MANAGER_SECRET: "<zitadel_user_manager_secret>"
  FILE_SERVICE_NATS_TOKEN: "<nats_auth_token>" # Must match NATS_AUTH_TOKEN in the istari-nats secret (see NATS Secret below)
  FILE_SERVICE_FEATURE_FLAGS__EVENTING_ENABLED: "true" # Enables eventing functionality (powered by NATS)
  # Following values are required as is
  FILE_SERVICE_HOST: "0.0.0.0"
  FILE_SERVICE_PORT: "8000"
  FILE_SERVICE_SENTRY_ENABLED: "false"
  FILE_SERVICE_USE_SINGLETON_AUTHZED_PERMISSION_MANAGER: "false"

warning

FILE_SERVICE_CORS_ALLOW_ORIGINS is written as a JSON array. Make sure to use double quotes for the JSON array.

Note the following:

customer_istari_fqdn is the domain used for the Istari Digital platform, e.g. `istari.customer_domain.com.
zitadel_client_id is obtained from the Zitadel Config step
zitadel_project_id and zitadel_project_grant_id are both obtained from the Zitadel Config step
zitadel_secret is obtained from the Zitadel Config step
zitadel_user_manager_secret is obtained from the Zitadel Config step
AWS_S3_access_key or Azure_storage_account_name are obtained from the AWS or Azure Object Store Configuration step
AWS_S3_bucket or Azure_storage_container are obtained from the AWS or Azure Object Store Configuration step
AWS_S3_endpoint_url or Azure_endpoint_url are obtained from the AWS or Azure Object Store Configuration step
AWS_S3_region is obtained from the Object Store Configuration step
spicedb_preshared_key is obtained from the SpiceDB Install step
password is obtained from the AWS or Azure PostgreSQL Install step and is associated with the DB user registry_service
nats_auth_token is a strong, randomly generated value you create. It must be identical to the NATS_AUTH_TOKEN in the NATS Secret below.

You will then create the secret by running the following command:

kubectl apply -f istari-fileservice-secret.yaml

NATS Secret

The Istari Platform uses NATS for messaging, which powers eventing functionality in the registry service (fileservice). Create a Kubernetes secret named istari-nats to hold the NATS authentication token.

NATS authenticates connections using a shared token. Choose a single secret value (the "NATS auth token") and provide it in two places, which must match:

The istari-nats secret, under the key NATS_AUTH_TOKEN (read by NATS).
The istari-fileservice secret, under the key FILE_SERVICE_NATS_TOKEN (read by the registry service — see the Registry Service Secret above).

Create the istari-nats secret, replacing <nats_auth_token> with a strong, randomly generated value that matches FILE_SERVICE_NATS_TOKEN in the fileservice secret:

istari-nats-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: istari-nats
stringData:
  NATS_AUTH_TOKEN: "<nats_auth_token>"

You will then create the secret by running the following command:

kubectl apply -f istari-nats-secret.yaml

Optional: MCP Secret

By default the Istari Platform Helm chart does not enable MCP functionality. The MCP Service is also what lets Istari AI Chat read platform data, so enable it if you plan to offer AI Chat. Should you wish to do so you must first create an additional Kubernetes secret named istari-mcp. This file should contain the following, with items in <> replaced with values specific to your install (described below):

istari-mcp-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: istari-mcp
stringData:
  ISTARI_DIGITAL_MCP_SERVICE_BASE_URL: "https://mcp.<customer_istari_fqdn>"
  ISTARI_DIGITAL_ZITADEL_CLIENT_ID: "<zitadel_client_id>"
  ISTARI_DIGITAL_ZITADEL_CLIENT_SECRET: "<zitadel_client_secret>"
  ISTARI_DIGITAL_ZITADEL_ISSUER: "https://zitadel.<customer_istari_fqdn>"
  ISTARI_DIGTIAL_FRONTEND_BASE_URL: "https://<customer_istari_fqdn>"

Note the following:

customer_istari_fqdn is the domain used for the Istari Digital platform, e.g. `istari.customer_domain.com.
zitadel_client_id and zitadel_client_secret are obtained from the Zitadel Configuration & Secrets - MCP Service Application step.

You will then create the secret by running the following command:

kubectl apply -f istari-mcp-secret.yaml

Optional: Identity Service Secret

By default the Istari Platform Helm chart does not enable the Identity Service. Should you wish to do so (see Scenario 10) you must first create an additional Kubernetes secret named istari-identity. This file should contain the following, with items in <> replaced with values specific to your install (described below):

istari-identity-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: istari-identity
stringData:
  ISTARI_DIGITAL_IDENTITY_SERVICE_DATABASE_URL: "postgresql://<db_user>:<db_password>@<db_host>:5432/<db_name>"
  ISTARI_DIGITAL_IDENTITY_SERVICE_SIGNING_KEY: "<signing_key>"
  ISTARI_DIGITAL_IDENTITY_SERVICE_TOKEN_ENCRYPTION_KEY: "<token_encryption_key>"
  ISTARI_DIGITAL_IDENTITY_SERVICE_CORS_ALLOWED_ORIGINS: "https://<customer_istari_fqdn>"
  ISTARI_DIGITAL_IDENTITY_SERVICE_ENFORCE_CLIENT_REGISTRATION: "true"
  ISTARI_DIGITAL_IDENTITY_SERVICE_OIDC_SCOPES: "openid profile email offline_access urn:zitadel:iam:org:project:id:zitadel:aud urn:zitadel:iam:user:resourceowner"
  # Optional — fallback tenant for Zitadel instance-level admins:
  ISTARI_DIGITAL_IDENTITY_SERVICE_JWT_DEFAULT_TENANT_ID: "<zitadel_org_id>"

Note the following:

Create a new, dedicated PostgreSQL database for the Identity Service and use its connection string as the ISTARI_DIGITAL_IDENTITY_SERVICE_DATABASE_URL. The database name is your choice.
ENFORCE_CLIENT_REGISTRATION: "true" makes the Identity Service refuse a sign-in from a client it has not registered, or one that asks to return to an address outside that client's allowlist. Without it, such sign-ins are only logged, which leaves the sign-in flow open to phishing pages that pose as a platform client and to stolen authorization codes sent to an attacker's address. It is safe from the first install: the frontend and MCP service sign in under the client IDs the Identity Service registers at startup, with allowlists derived from common.mainFqdn. If people reach the frontend or MCP service at another address, add it to the allowlist; see Overriding the redirect allowlists.
signing_key and token_encryption_key are the $SIGNING_KEY and $TOKEN_ENCRYPTION_KEY values from Identity Service — Generate Keys.
With the provisioner (provisioner.enabled: true, as in Scenario 10), the secret carries no client credentials: the provisioner generates the registry's and the MCP service's credentials, and the Identity Service registers the registry, frontend and MCP service from them at startup — see How the Platform Clients Are Registered. Without the provisioner, add the keys listed in Chart install without the provisioner to the secrets it names: this one, the registry's (istari-fileservice) and, if deployed, the MCP service's (istari-mcp).
zitadel_org_id is your Zitadel organization's numeric ID — see Finding your Zitadel organization ID.
The YAML above leaves out the values that register the Identity Service with Zitadel: its OIDC client ID, private key, issuer and base URL, and the Zitadel management key. Which of them you add here depends on how you registered it:
- Zitadel Configurator 1.10.0 or later: none. The Configurator delivers them in its own secret, zitadel-identity-service-env.
- Configurator 1.8.2 to 1.9.x: only the management key, ISTARI_DIGITAL_IDENTITY_SERVICE_ZITADEL_MANAGER_KEY. Create it by hand (step 4). The install or upgrade fails without it, unless you turn off the chart's import of Zitadel organizations.
- No Configurator, or one older than 1.8.2: all of them, as Register Zitadel by hand describes.

You will then create the secret by running the following command:

kubectl apply -f istari-identity-secret.yaml

Docker pull secret

The docker-pull-secret should have been created in the Docker Pull Secret step. If you have not created it yet, do so before proceeding.

Verify the secrets

Make sure to verify that the required secrets were created successfully and are listed in the output of the above command.

kubectl describe secret istari-frontend
kubectl describe secret istari-fileservice
kubectl describe secret istari-nats
kubectl describe secret docker-pull-secret

Istari Platform Helm Chart

The Istari Platform is installed using a Helm chart. The Helm chart contains all the necessary configurations and resources required to deploy the Istari Platform in a Kubernetes cluster.

Download Helm Chart

info

Your organization needs registry credentials for istaridigital.jfrog.io. Obtain the JFrog service account username and a token from the Istari Customer Portal (for example using Generate ready-to-use commands on a Helm chart asset).
Use those values for ISTARI_ARTIFACTORY_USERNAME and ISTARI_ARTIFACTORY_PASSWORD in the commands below (the password is the generated token).
This access is required to pull the Istari Digital Helm chart and to create the docker pull secret for EKS in the next steps.

To download the Istari Digital Helm chart in .tgz format, run the following command:

ISTARI_ARTIFACTORY_USERNAME=
ISTARI_ARTIFACTORY_PASSWORD=
helm pull oci://istaridigital.jfrog.io/customer-charts/istari-platform --version X.X.X --username ${ISTARI_ARTIFACTORY_USERNAME} --password ${ISTARI_ARTIFACTORY_PASSWORD}

info

Use the service account username and token from the Customer Portal for ISTARI_ARTIFACTORY_USERNAME and ISTARI_ARTIFACTORY_PASSWORD.

Helm Chart Installation

Create an istari-values.yaml file. It must set common.mainFqdn, the domain people use to reach the platform: every host and URL the chart emits derives from it, and the chart refuses to install without it. The Istari Platform also uses NATS for messaging, so enable the NATS subchart:

istari-values.yaml
common:
  mainFqdn: "<customer_istari_fqdn>"   # required: the domain you use to access the platform

# Enable NATS messaging (powers eventing in the registry service)
nats:
  enabled: true

<customer_istari_fqdn> is a bare host such as istari.example.com, with no https:// and no path.

When nats.enabled: true, the chart deploys NATS in-cluster and automatically injects the FILE_SERVICE_NATS_URL environment variable into the fileservice Pods so they can connect to it. The NATS auth token is sourced from the istari-nats and istari-fileservice secrets you created above. NATS runs in-cluster and is reached over the internal nats://nats:4222 address, so no external DNS or routing configuration is required.

Install the Istari Platform with this values file:

helm upgrade --install -f istari-values.yaml istari istari-platform-X.X.X.tgz

Verify the Istari Platform installation

Deployments

kubectl get deployments

The output should look like this:

NAME                              READY   UP-TO-DATE   AVAILABLE   AGE
istari-fileservice                1/1     2            2           1m
istari-frontend                   1/1     2            2           1m

Services

kubectl get services

The output should look like this:

NAME                              TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                                 AGE
istari-fileservice                ClusterIP   172.20.1.1       <none>        80/TCP                                  1m
istari-frontend                   ClusterIP   172.20.1.2       <none>        80/TCP                                  1m
istari-secure-connection          ClusterIP   172.20.1.3       <none>        80/TCP                                  1m
nats                              ClusterIP   172.20.1.4       <none>        4222/TCP                                1m
nats-headless                     ClusterIP   None             <none>        4222/TCP,6222/TCP,8222/TCP              1m
spicedb                           ClusterIP   172.20.1.5       <none>        50051/TCP,8443/TCP,9090/TCP,50053/TCP   1m

Pods

kubectl get pods

The output should look like this:

NAME                                             READY   STATUS    RESTARTS        AGE
istari-fileservice-5676c75c54-4d4sw              1/1     Running   0               1m
istari-fileservice-5676c75c54-m29jc              1/1     Running   0               1m
istari-frontend-7c4597c78b-45mhn                 1/1     Running   0               1m
istari-frontend-7c4597c78b-86whn                 1/1     Running   0               1m
nats-0                                           2/2     Running   0               1m
nats-1                                           2/2     Running   0               1m
nats-2                                           2/2     Running   0               1m

DNS Routes

Set up Routes records so that:

Setup <customer_istari_fqdn> route to the istari-frontend service on port 80.
Setup registry.<customer_istari_fqdn> route to the istari-fileservice service on port 80.

Istari Platform Helm Chart Configuration

Beyond enabling NATS, you can use the istari-values.yaml file to further configure the Istari Platform according to your needs.

The default values for the Istari Platform Helm chart are available in the Appendix: Helm Chart Default Values. It is recommended to only add the options you wish to override the defaults for in an istari-values.yaml file.

The following are a number of scenarios where you might wish to override these defaults, and examples of how you would accomplish this by modifying your istari-values.yaml file.

warning

The scenario snippets below are additive — each shows only the keys relevant to that scenario. Merge them into the same istari-values.yaml you created during installation (the one that sets nats.enabled: true). Do not use a scenario snippet as your complete configuration, or NATS will be disabled (the chart currently defaults nats.enabled to false).

Scenario 1: Istari Platform with Model Context Protocol (MCP) Service enabled

This configuration enables the MCP Service, and requires multiple steps.

Create MCP Secret

If you have not already done so, create the istari-mcp secret using these instructions.

Verify MCP Secret

You may verify that the istari-mcp secret was successfully created using this command:

kubectl describe secret istari-mcp

Update istari-values.yaml

Add the following values to your istari-values.yaml file to enable.

istari-values.yaml
# Istari Platform with MCP Service
mcp:
  enabled: true

  # # Uncomment the following and update with necessary values if self-hosting the docker image
  # registry: "istaridigital.jfrog.io/main-docker-local"
  # image: "mcp-service"

Install the Istari Platform

Then, install/upgrade the Istari Platform Helm chart with the custom istari-values.yaml file:

helm upgrade --install -f istari-values.yaml istari istari-platform-X.X.X.tgz

Set Up DNS & Route

Then set up a route so that the subdomain mcp.<customer_istari_fqdn> forwards traffic to the istari-mcp service on port 80.

warning

Your LLM will need to be able to connect to the Istari Platform and new MCP subdomain on port 443. Please update security groups and/or any other network configuration accordingly as needed.

Scenario 2: Support for Self-Signed TLS Certs

warning

This is a newly added feature which is still in beta mode.

By default the Istari Platform uses Red Hat's list of trusted public Certificate Issuers when determining whether a TLS cert is valid. If instead using self-signed certs issued from a private Certificate Issuer, it is possible to use the Helm chart to update the Istari Platform containers so that they trust one or more of these. You will need a PEM-encoded trust bundle, which should not contain secret information and is typically provided alongside the self-signed private TLS cert.

Begin by adding the following example to your istari-values.yaml file and then replace everything from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- with the complete contents of your trust bundle, which will contain one or more certificates. This contented must be indented and be located directly below the trustedCertBundle: |- line in order to work properly, as in the original example.

istari-values.yaml
# Trusted certificate bundle for when using a self-signed certificate.
# This is a PEM-encoded certificate bundle. AWS, Azure, and GCP root certs will also automatically be trusted.
trustedCertBundle: |-
  -----BEGIN CERTIFICATE-----
  MIID1z...
  ...
  -----END CERTIFICATE-----

You may then install Istari Platform Helm chart with the custom istari-values.yaml file using the following command:

helm upgrade --install -f istari-values.yaml istari istari-platform-X.X.X.tgz

Scenario 3: Istari Platform with HPA enabled

This configuration enables Horizontal Pod Autoscaling (HPA) for both the file service and frontend service. The HPA will automatically scale the number of replicas based on CPU and memory utilization.

istari-values.yaml
# Istari Platform with HPA enabled
fileservice:
  autoscaling:
    enabled: true
    minReplicas: 1
    maxReplicas: 2
    averageCPUUtilization: 80
    averageMemoryValue: 80

frontend:
  autoscaling:
    enabled: true
    minReplicas: 1
    maxReplicas: 2
    averageCPUUtilization: 80
    averageMemoryValue: 80