​
Self-Hosted Gentrace

Before deploying Gentrace self-hosted, you’ll need to contact us at [email protected] 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',
});
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

  1. Clone the repository:
git clone https://github.com/gentrace/gentrace-self-hosted
cd gentrace-self-hosted/docker
  1. 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
  2. Execute the following Docker login command. You’ll need to contact [email protected] to get these credentials: 
docker login -u='gentrace+gentracecustomer' -p='<gentrace-provided-password>'
  1. Start the services:
docker compose up -d
  1. Access the services:

​
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.
  1. Add the Gentrace Helm repository:
helm repo add gentrace-self-hosted https://gentrace.github.io/gentrace-self-hosted
helm repo update
  1. 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

  1. Get the Helm Chart:
git clone https://github.com/gentrace/gentrace-self-hosted
cd gentrace-self-hosted
  1. 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
  1. 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
  1. 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'
  1. 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:
  1. Check the changelog for breaking changes
  2. Backup your data:
    • PostgreSQL data
    • ClickHouse data
    • Object storage contents
  3. 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:
  1. Pull the latest images:
docker compose pull
  1. 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:
  1. Replace all environment variables with your actual values
  2. Ensure the databases are accessible from where you’re running the container
  3. 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: