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.

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​

Choose the deployment method that best suits your environment:

Deploy with Kubernetes​

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

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: "<Version />" #latest
    nodeSelector: {}
      # kubernetes.io/arch: amd64
    env: 
      INGEST__DEBUGINFOD_SERVERS: "https://debuginfod.ubuntu.com"

# 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"

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"  
      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
  1. Access the UI

You may now configure your existing ingress controller to access the zymtrace ui/gateway service, 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 gRPC traffic to the ui/gateway. This service automatically routes request from the agent. Refer to the service ingress.

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