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:
TypeScript
typescript
import {init } from "@gentrace/core";init ({apiKey :process .env .GENTRACE_API_KEY ?? "",basePath : "https://self-hosted.gentrace.ai/api",});
Python
python
import gentraceimport os# Initialize Gentracegentrace.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
- Clone the repository:
bash
git clone https://github.com/gentrace/gentrace-self-hostedcd gentrace-self-hosted/docker
Configure environment variables:
- Copy the
.env.example
to.env
- Set secure values for
JWT_SECRET
andPRISMA_FIELD_ENCRYPTION_KEY
- Update admin credentials in the environment file
- Copy the
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>'
- Start the services:
bash
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:
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 lostdocker compose down -vdocker 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:
bash
helm repo add gentrace-self-hosted https://gentrace.github.io/gentrace-self-hostedhelm repo update
- 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
- Get the Helm Chart:
bash
git clone https://github.com/gentrace/gentrace-self-hostedcd gentrace-self-hosted
- Configure Storage Class:
yaml
apiVersion: storage.k8s.io/v1kind: StorageClassmetadata:name: gentrace-storageprovisioner: kubernetes.io/gce-pd # Change based on your cloud providerparameters:type: gp3fsType: ext4reclaimPolicy: RetainallowVolumeExpansion: truevolumeBindingMode: WaitForFirstConsumer
- Install Istio:
bash
curl -L https://istio.io/downloadIstio | sh -cd istio-*export PATH=$PWD/bin:$PATHistioctl install --set profile=demokubectl 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:
yaml
apiVersion: v1kind: Secretmetadata:name: postgres-credentialstype: OpaquestringData: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
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:
Check the changelog for breaking changes
Backup your data:
- PostgreSQL data
- ClickHouse data
- Object storage contents
Update the Helm chart:
If using Artifact Hub:
bashhelm repo update# Check available versionshelm 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 versionhelm upgrade gentrace gentrace-self-hosted/gentrace-self-hosted -f values.yamlIf using Git repository:
bash# First, pull the latest changesgit pull origin main# Then upgrade using the local charthelm 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:
bash
docker compose pull
- Restart the services with the new images:
bash
docker compose downdocker 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/gentracedocker 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 [email protected]