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 UI 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.

Orchestor requirements​

Choose your deployment method.

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​

Choose the deployment method that best suits your environment:

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 \
  --set global.registry.username=<username> \ 
  --set global.registry.password=<password>

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

services:
  common:
    imageTag: "25.2.0-beta.3" #latest
    nodeSelector: {}
      # kubernetes.io/arch: amd64
    env: 
      INGEST__DEBUGINFOD_SERVERS: "https://debuginfod.ubuntu.com"
      #ZYMTRACE_SERIAL: "PLACEHOLDER"

# 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

scylla:
  mode: "use_existing"
  use_existing:
    hosts: 
       - node-0.gce-europe-north-1.zymtrace.clusters.scylla.cloud:9142
       - node-1.gce-europe-north-1.zymtrace.clusters.scylla.cloud:9142
       - node-2.gce-europe-north-1.zymtrace.clusters.scylla.cloud:9142
    user: scylla
    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"

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

  hosts:
    ui:
      enabled: true
      host: "zymtrace.company.com"  # Will be accessible via localhost
      paths:
        - path: /
          pathType: Prefix
      annotations: {}
    
    ingest:
      enabled: true
      host: "zymtrace-ingest.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
  1. Access the UI

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

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

Navigate to http://localhost:8080

Ingress Controller​

We recommend using an ingress controller to route HTTP traffic to the UI service and gRPC for the ingest service. Refer to the service ingress.

Upgrade zymtrace backend​

Database migrations in this beta release have not been fully validated. As a result, upgrades are not supported by default.

Forcing an Upgrade​

To upgrade despite this limitation, follow one of the methods below.

Method 1: Using a YAML configuration file​

  1. Create a new upgrade_values.yaml file or modify an existing custom_values.yaml:

    # Required configuration for upgrade
    global:
      forceUpgrade: true
    services:
      common:
        imageTag: <target-version>  # Cannot be empty or latest

  2. Then execute the upgrade command:

    helm upgrade backend zymtrace/backend \
      -n zymtrace --reuse-values \
      -f <upgrade_values.yaml> \
      --atomic --timeout 10m --debug

Method 2: Using command-line flags​

Alternatively, execute the following command:

helm upgrade backend zymtrace/backend \
 --reuse-values \
 --set global.forceUpgrade=true \
 --set services.common.imageTag=<target-version> \
 --atomic --timeout 10m --debug
tip

Retrieve the available tag versions from our public images repository on GitHub.

Management Commands​

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

# 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