Self-Hosted Gentrace

Before deploying Gentrace self-hosted, you’ll need to contact us at support@gentrace.ai to obtain the necessary secrets for pulling container images:

For Docker deployments: You’ll need credentials to pull from our Quay.io registry
For Kubernetes deployments: You’ll need an image pull secret to access our container registry

Without these credentials, you won’t be able to pull the required containers from our container registries.

Gentrace offers a self-hosted version that can be deployed either using Docker Compose for development/testing or in your own Kubernetes cluster via a Helm chart for production use. The self-hosted version provides all the features of Gentrace while giving you complete control over your data and infrastructure. The repository is available at gentrace/gentrace-self-hosted.

Overview

The Gentrace self-hosted deployment includes:

Gentrace API Server
Gentrace Web Application Frontend
Gentrace WebSocket Server
PostgreSQL Database
ClickHouse Analytics Database
Kafka Message Queue
Object Storage Integration
Service Mesh Configuration (Kubernetes only)

SDK Configuration

When using Gentrace SDKs with a self-hosted deployment, you must configure the base URL during initialization:

import { init } from 'gentrace';

init({
  apiKey: process.env.GENTRACE_API_KEY ?? '',
  baseURL: 'https://self-hosted.gentrace.ai/api',
});

import gentrace
import os

# Initialize Gentrace
gentrace.init(
    api_key=os.getenv("GENTRACE_API_KEY"),
    base_url="https://self-hosted.gentrace.ai/api",
)

Replace https://self-hosted.gentrace.ai/api with your self-hosted deployment’s API endpoint like http://localhost:3000/api if running locally with Docker.

Docker Deployment (Development)

The Docker deployment is recommended for local development and testing environments. It provides a quick way to get started with Gentrace.

Prerequisites

Docker Engine 20.10.0+
Docker Compose v2.0.0+
4GB RAM minimum
20GB disk space minimum

Quick Start

Clone the repository:

git clone https://github.com/gentrace/gentrace-self-hosted
cd gentrace-self-hosted/docker

Configure environment variables:
- Copy the .env.example to .env
- Set secure values for JWT_SECRET and PRISMA_FIELD_ENCRYPTION_KEY
- Update admin credentials in the environment file
Execute the following Docker login command. You’ll need to contact support@gentrace.ai to get these credentials:

docker login -u='gentrace+gentracecustomer' -p='<gentrace-provided-password>'

Start the services:

docker compose up -d

Access the services:
- Web App: http://localhost:3000
- Kafka UI: http://localhost:8080
- MinIO Console: http://localhost:9001

Docker Services

The Docker deployment includes:

Core Services:
- Web App & API (port 3000)
- WebSocket Server (port 3001)
- Task Runner & Scheduler
Infrastructure:
- PostgreSQL (port 5432)
- ClickHouse (port 8123)
- Kafka (ports 9092, 29092)
- MinIO (ports 9000, 9001)

Docker Troubleshooting

View logs for a specific service:

docker compose logs -f [service-name]

Reset all data and start fresh:

# Note: Using -v will **DELETE** all volumes and data will be permanently lost
docker compose down -v
docker compose up -d

Kubernetes Deployment (Production)

The Kubernetes deployment is recommended for production environments, offering scalability and high availability.

Prerequisites

Kubernetes 1.19+
Helm 3.0+
A configured storage class
Istio service mesh (if mutual TLS is needed)
Access to pull container images
Kubernetes secrets configured

Installation Steps

You can install Gentrace either by cloning the repository or using the Helm chart from Artifact Hub.

Option 1: Using Artifact Hub (Recommended for Production)

Add the Gentrace Helm repository:

helm repo add gentrace-self-hosted https://gentrace.github.io/gentrace-self-hosted
helm repo update

Install the chart:

helm install gentrace gentrace-self-hosted/gentrace-self-hosted -f values.yaml

You can find our Helm chart on Artifact Hub for additional information, versions, and documentation.

Option 2: Using Git Repository

Get the Helm Chart:

git clone https://github.com/gentrace/gentrace-self-hosted
cd gentrace-self-hosted

Configure Storage Class:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gentrace-storage
provisioner: kubernetes.io/gce-pd # Change based on your cloud provider
parameters:
  type: gp3
  fsType: ext4
reclaimPolicy: Retain
allowVolumeExpansion: true
volumeBindingMode: WaitForFirstConsumer

Install Istio:

curl -L https://istio.io/downloadIstio | sh -
cd istio-*
export PATH=$PWD/bin:$PATH
istioctl install --set profile=demo
kubectl label namespace default istio-injection=enabled

Configure Secrets:

Create the necessary Kubernetes secrets for:

Admin credentials
Database credentials (PostgreSQL, ClickHouse)
JWT authentication
Kafka configuration
Object storage access
Prisma field encryption

Example secret configuration:

apiVersion: v1
kind: Secret
metadata:
  name: postgres-credentials
type: Opaque
stringData:
  POSTGRES_USER: 'gentrace'
  POSTGRES_PASSWORD: 'your-secure-password'
  POSTGRES_DB: 'gentrace'
  DATABASE_URL: 'postgresql://gentrace:your-secure-password@postgres:5432/gentrace'

Deploy:

Use the example values.yaml file as a starting point for your configuration. This file contains all the default values and configuration options available. The configuration values present in the values.yaml include:

Database settings
Storage configurations
Service mesh parameters
Resource allocations
Ingress configurations

helm install gentrace ./helm-chart -f values.yaml

Monitoring

Access the Kiali dashboard to visualize service mesh topology:

istioctl dashboard kiali

Updates and Maintenance

To update your self-hosted Gentrace installation:

Check the changelog for breaking changes
Backup your data:
- PostgreSQL data
- ClickHouse data
- Object storage contents

Update the Helm chart: If using Artifact Hub:

helm repo update

# Check available versions
helm search repo gentrace-self-hosted --versions

# Upgrade to specific version (recommended)
helm upgrade gentrace gentrace-self-hosted/gentrace-self-hosted --version <version> -f values.yaml

# Or upgrade to latest version
helm upgrade gentrace gentrace-self-hosted/gentrace-self-hosted -f values.yaml

If using Git repository:

# First, pull the latest changes
git pull origin main

# Then upgrade using the local chart
helm upgrade gentrace ./helm-chart -f values.yaml

You can also install the Helm chart directly from Artifact Hub. First, add the Gentrace Helm repository: For Docker deployments, to update:

Pull the latest images:

docker compose pull

Restart the services with the new images:

docker compose down
docker compose up -d

Manual Migration (Non-Docker/Helm Deployments)

If you’re deploying Gentrace without using Docker Compose or the Helm chart, you’ll need to run the database migrations manually. You can do this by running our migration container:

# DATABASE_URL should be your PostgreSQL connection string in the format:
# postgresql://user:password@host:5432/gentrace
docker run -e DATABASE_URL=<your-postgres-database-url> \
  -e NODE_TLS_REJECT_UNAUTHORIZED="0" \
  -e PRISMA_BINARIES_MIRROR=http://prisma-builds.s3-eu-west-1.amazonaws.com \
  -e PRISMA_ENGINES_CHECKSUM_IGNORE_MISSING="1" \
  -e CLICKHOUSE_HOST=<your-clickhouse-host> \
  -e CLICKHOUSE_PORT=<your-clickhouse-port> \
  -e CLICKHOUSE_PROTOCOL=<your-clickhouse-protocol> \
  -e CLICKHOUSE_DATABASE=<your-clickhouse-database> \
  -e CLICKHOUSE_USER=<your-clickhouse-user> \
  -e CLICKHOUSE_PASSWORD=<your-clickhouse-password> \
  -e NODE_ENV=production \
  -e ENVIRONMENT=production \
  -e JWT_SECRET=<your-jwt-secret> \
  -e PRISMA_FIELD_ENCRYPTION_KEY=<your-encryption-key> \
  -e ADMIN_EMAIL=<admin-email> \
  -e ADMIN_PASSWORD=<admin-password> \
  -e ADMIN_NAME=<admin-name> \
  quay.io/gentrace/core:production \
  "npm run self-hosted:migrate-and-seed"

Make sure to:

Replace all environment variables with your actual values
Ensure the databases are accessible from where you’re running the container
Run this before starting your Gentrace services for the first time or when upgrading to a new version

Support

For detailed deployment instructions and troubleshooting:

Visit our GitHub repository
Contact us at support@gentrace.ai

Getting started

Error analysis

Tracing

Evaluation

Integrations

Administration

Reference

SDK Entities

Self-hosted deployment

Self-Hosted Gentrace

Overview

SDK Configuration

Docker Deployment (Development)

Prerequisites

Quick Start

Docker Services

Docker Troubleshooting

Kubernetes Deployment (Production)

Prerequisites

Installation Steps

Option 1: Using Artifact Hub (Recommended for Production)

Option 2: Using Git Repository

Monitoring

Updates and Maintenance

Manual Migration (Non-Docker/Helm Deployments)

Support

​Self-Hosted Gentrace

​Overview

​SDK Configuration

​Docker Deployment (Development)

​Prerequisites

​Quick Start

​Docker Services

​Docker Troubleshooting

​Kubernetes Deployment (Production)

​Prerequisites

​Installation Steps

​Option 1: Using Artifact Hub (Recommended for Production)

​Option 2: Using Git Repository

​Monitoring

​Updates and Maintenance

​Manual Migration (Non-Docker/Helm Deployments)

​Support

Self-Hosted Gentrace

Overview

SDK Configuration

Docker Deployment (Development)

Prerequisites

Quick Start

Docker Services

Docker Troubleshooting

Kubernetes Deployment (Production)

Prerequisites

Installation Steps

Option 1: Using Artifact Hub (Recommended for Production)

Option 2: Using Git Repository

Monitoring

Updates and Maintenance

Manual Migration (Non-Docker/Helm Deployments)

Support