Self-Hosted Gentrace

Important

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:

TypeScript

typescript
import { init } from "@gentrace/core";
 
init({
  apiKey: process.env.GENTRACE_API_KEY ?? "",
  basePath: "https://self-hosted.gentrace.ai/api",
});

Python

python
import gentrace
import os
# Initialize Gentrace
gentrace.init(
    api_key=os.getenv("GENTRACE_API_KEY"),
    host="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:

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

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

3. Execute the following Docker login command. You'll need to contact [email protected] to get these credentials:

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

3. Start the services:

bash
docker compose up -d

4. 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:

bash
docker compose logs -f [service-name]

Reset all data and start fresh:

bash
# 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)

1. Add the Gentrace Helm repository:

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

2. Install the chart:

bash
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:

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

2. Configure Storage Class:

yaml
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

3. Install Istio:

bash
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

4. 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:

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

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

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

Monitoring

Access the Kiali dashboard to visualize service mesh topology:

bash
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:

   bash
   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:

   bash
   # 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:

bash
docker compose pull

2. Restart the services with the new images:

bash
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:

bash
# 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:

• Visit our GitHub repository
• Contact us at [email protected]