Skip to main content

Install Zymtrace Backend

This guide provides detailed instructions for installing and managing the zymtrace backend in an on-premises environment using Helm charts and Docker Compose.

The backend consists of databases, webservices and the gateway service. Please refer to the architecture section for specifics.

tip

Please review the prerequisites before beginning, particularly if you are working in an airgapped environment.

Orchestrator requirements​

Choose your deployment method.

Kubernetes​

For Kubernetes deployment, ensure you have:

  • Kubernetes cluster (v1.20 or later)
  • Helm 3.x installed
  • Ingress controller for out-of-cluster access (optional, but recommended)

Deploy zymtrace backend​

Preserve your values on upgrade

When using --set (e.g. updating image tags), always add --reset-then-reuse-values to avoid resetting your chart values to defaults.

  • Use --reset-then-reuse-values when upgrading with --set (e.g. image tags, license updates)
  • Use -f <values-file> when doing a full deployment — no reuse flag needed in that case

Choose the deployment method that best suits your environment:

Deploy with Kubernetes​

Artifact Hub

Helm Chart Source

The Helm chart source code is available on GitHub: zystem-io/zymtrace-charts

Deploy using Helm Charts.

  1. Add the zymtrace Helm repository
helm repo add zymtrace https://helm.zystem.io

# List available charts and versions
helm search repo zymtrace --versions
  1. Install the backend components
helm install backend zymtrace/backend \
  --namespace zymtrace \
  --create-namespace

Alternatively, use helm upgrade --install to install or upgrade in one command:

helm upgrade --install backend zymtrace/backend \
  --namespace zymtrace \
  --create-namespace \
  --reset-then-reuse-values \
  --debug \
  --atomic

Or use a custom values file for more detailed configuration:

Using custom values 
# custom-values.yaml

# Global Configuration
global:
  imagePullPolicy: IfNotPresent
  dataRetentionDays: 7  # Default retention period in days

  # Optional: reference an existing Kubernetes Secret for the license key
  # instead of passing it inline (recommended for production).
  # If not set, falls back to the licenseKey value above.
  # Create the secret first (run once before deploying):
  #   kubectl create secret generic zymtrace-license \
  #     --namespace zymtrace \
  #     --from-literal=license-key="<your-license-key>"
  # licenseKeySecretName: "zymtrace-license"
  # licenseKeySecretKey: "license-key"
  #
  # Note: the chart does not pre-check that the secret exists (this would require
  # cluster read privileges at render time). If the secret is missing, pods will
  # fail to start — check pod health after deploying: kubectl get pods -n zymtrace

services:
  common:
    imageTag: "<Version />" #latest
    nodeSelector: {}
      # kubernetes.io/arch: amd64

# custom-values.yaml
clickhouse:
  mode: "use_existing" # "create" or "use_existing"
  use_existing:
    host: zymtrace.eu-west-2.aws.clickhouse.cloud
    user: default 
    password: password
    database: zymtrace
    secure: true

postgres:
  mode: "use_existing"
  use_existing:
    host: zymtrace.pg.local:5432
    user: zymtrace
    password: password
    database: "zymtrace"
    secure: true

storage:
  mode: "use_existing"
  use_existing:
    type: "s3"
    minio:
      endpoint: "http://minio.zymtrace-db.svc.cluster.local:9000"
      user: "minio"
      password: "minio123" 
    s3:
      accessKey: "IAM_USER_KEY"
      secretKey: "SECRET"
      region: "eu-west-2"

# Optional: add annotations and labels to any backend Service
# Useful for AWS Load Balancer Controller, Linkerd, Prometheus scraping, etc.
# services:
#   ingest:
#     service:
#       annotations:
#         prometheus.io/scrape: "true"
#         service.beta.kubernetes.io/aws-load-balancer-type: "external"
#       labels:
#         app: zymtrace

ingress:
  enabled: true
  className: "nginx"  # Matches your IngressClass name
  annotations: 
    nginx.ingress.kubernetes.io/ssl-redirect: "true" # required tls both services 

  hosts:
    gateway:
      enabled: true
      host: "zymtrace.company.com"  
      paths:
        - path: /
          pathType: Prefix
      annotations: 
        nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
        nginx.ingress.kubernetes.io/proxy-body-size: "0"
        nginx.ingress.kubernetes.io/client-body-buffer-size: "1M"

  # Start without TLS for initial testing
  tls: []
   
helm install backend zymtrace/backend \
   --namespace zymtrace \
   -f custom-values.yaml

Or with upgrade --install:

helm upgrade --install backend zymtrace/backend \
   --namespace zymtrace \
   -f custom-values.yaml \
   --debug \
   --atomic
  1. Access the UI

You may now configure your existing ingress controller to access the zymtrace gateway service, or simply test it by port-forwarding the gateway service:

kubectl port-forward svc/zymtrace-gateway 8080:80 -n zymtrace

Navigate to http://localhost:8080

Using Existing Kubernetes Secrets​

Instead of passing sensitive values inline in your values file, you can reference existing Kubernetes Secrets. This is recommended for production deployments and for environments that manage secrets externally (e.g. AWS Secrets Manager, HashiCorp Vault, Sealed Secrets).

License Key​

Create the secret once before deploying:

kubectl create secret generic zymtrace-license \
  --namespace zymtrace \
  --from-literal=license-key="<your-license-key>"

Then reference it in your values file instead of setting licenseKey inline:

global:
  licenseKeySecretName: "zymtrace-license"
  licenseKeySecretKey: "license-key"

Token Signing Keys​

kubectl create secret generic zymtrace-signing-keys \
  --namespace zymtrace \
  --from-literal=private-key="-----BEGIN PRIVATE KEY-----
<your-private-key>
-----END PRIVATE KEY-----" \
  --from-literal=public-key="-----BEGIN PUBLIC KEY-----
<your-public-key>
-----END PUBLIC KEY-----"
auth:
  validation:
    keys:
      privateKeySecretName: "zymtrace-signing-keys"
      privateKeySecretKey: "private-key"
      publicKeySecretName: "zymtrace-signing-keys"
      publicKeySecretKey: "public-key"

If these values are not set, the chart falls back to the inline licenseKey / privateKey / publicKey values.

Check pod health after deploying

The chart does not pre-check that referenced secrets exist — doing so would require cluster read privileges at render time. If a secret is missing, pods will fail to start. Always verify after deploying:

kubectl get pods -n zymtrace

Ingress Controller​

We recommend using an ingress controller to route gRPC traffic to the gateway. This service automatically routes request from the agent. Refer to the service ingress.

Enhanced Security with mTLS​

For production environments requiring additional security, you can enable mutual TLS (mTLS) authentication. This provides bidirectional certificate-based authentication between clients and the gateway. Refer to the mTLS configuration guide for detailed setup instructions.

Management Commands​

Use these commands to monitor and maintain your zymtrace backend deployment:

Kubernetes Management​

# View all resources in the namespace
kubectl get all -n zymtrace

# Check pod status
kubectl get pods -n zymtrace

# View service status
kubectl get services -n zymtrace

# Check deployment status
kubectl get deployments -n zymtrace

# View logs for a specific pod
kubectl logs -n zymtrace <pod-name>

# Delete the namespace and all resources
kubectl delete namespace zymtrace