Skip to navigation
Getting Started

Installation & Setup

Installation & Setup

This guide covers installation options and initial configuration for GovernanceAI.

Prerequisites

Before starting, ensure you have:

  • For SaaS: An active internet connection and a GovernanceAI account
  • For On-Premise:
    • Kubernetes 1.24+ or Docker Compose
    • Minimum 4 CPU cores and 8GB RAM
    • PostgreSQL 12+ database
    • Redis 6.0+ for caching
    • TLS certificate for HTTPS

Deployment Options

The simplest way to get started with GovernanceAI.

Step 1: Create Account

  • Visit GovernanceAI.com
  • Click Sign Up
  • Enter your email and password
  • Verify your email address
  • You’ll be redirected to your organization dashboard

Step 2: Create Your Organization

  • On the welcome screen, click Create Organization
  • Enter your organization name
  • Select your primary use case (LLM Governance, AI Agent Control, Compliance, etc.)
  • Click Create

Step 3: Invite Team Members

  • Go to Settings → Team Members
  • Click Invite Member
  • Enter email addresses (comma-separated for multiple)
  • Select their role (Admin, Editor, Viewer)
  • Click Send Invitations

Step 4: Generate API Keys

  • Go to Settings → API Keys
  • Click Create New Key
  • Name your key (e.g., “Production Runtime”)
  • Select scope (Runtime, Control Plane, or Both)
  • Click Generate
  • Copy and store securely - You won’t see it again

Step 5: Configure Your First Integration (Optional)

  • Go to Integrations
  • Click Connect GitHub, Jira, etc.
  • Follow the OAuth flow
  • Authorize GovernanceAI access
  • Configure which repositories/projects to scan

Option 2: On-Premise Deployment

For organizations requiring data residency, air-gapped deployment, or custom integrations.

Prerequisites Checklist

  • Kubernetes cluster ready (or Docker Compose)
  • PostgreSQL database accessible
  • Redis instance accessible
  • Valid TLS certificate
  • Firewall rules configured
  • Backup strategy in place

Step 1: Install via Kubernetes

Create namespace:

kubectl create namespace governanceai

Add Helm repository:

helm repo add governanceai https://charts.governanceai.com
helm repo update

Create values configuration (values.yaml):

# Database configuration
postgresql:
  enabled: true
  auth:
    password: <strong-password>
  persistence:
    size: 100Gi
# Redis configuration
redis:
  enabled: true
  auth:
    password: <strong-password>
# Ingress configuration
ingress:
  enabled: true
  hosts:
    - host: governanceai.your-domain.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: governanceai-tls
      hosts:
        - governanceai.your-domain.com
# Control Plane settings
controlPlane:
  replicas: 3
  resources:
    requests:
      cpu: 2
      memory: 4Gi
    limits:
      cpu: 4
      memory: 8Gi
# Runtime Engine settings
runtime:
  replicas: 5
  resources:
    requests:
      cpu: 1
      memory: 2Gi
    limits:
      cpu: 2
      memory: 4Gi

Install GovernanceAI:

helm install governanceai governanceai/governanceai \
  --namespace governanceai \
  -f values.yaml

Verify installation:

kubectl get pods -n governanceai
kubectl logs -n governanceai deployment/governanceai-controlplane

Step 2: Install via Docker Compose

Download docker-compose file:

curl -O https://downloads.governanceai.com/docker-compose.yml

Configure environment (.env):

# Database
DB_HOST=postgres
DB_PORT=5432
DB_NAME=governanceai
DB_USER=postgres
DB_PASSWORD=<strong-password>
# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=<strong-password>
# TLS
TLS_CERT_PATH=/etc/certs/tls.crt
TLS_KEY_PATH=/etc/certs/tls.key
# Admin user
ADMIN_EMAIL=admin@your-domain.com
ADMIN_PASSWORD=<strong-password>

Start services:

docker-compose up -d

Verify services:

docker-compose ps
docker-compose logs -f controlplane

Step 3: Initial Admin Configuration

  • Access Control Plane: https://governanceai.your-domain.com
  • Login with admin credentials from .env
  • Complete onboarding:
    • Change admin password
    • Configure SMTP for email notifications
    • Set up SSO (optional but recommended)
    • Configure backup settings

Step 4: Database Initialization

GovernanceAI will automatically initialize the database schema on first startup.

Verify initialization:

# Connect to PostgreSQL
psql -h $DB_HOST -U $DB_USER -d $DB_NAME
# List tables
\dt

Step 5: Backup Configuration

Create backup schedule:

# Example: Daily backups at 2 AM UTC
0 2 * * * pg_dump -h $DB_HOST -U $DB_USER $DB_NAME | gzip > /backups/db-$(date +%Y%m%d).sql.gz

Test backup restoration:

gunzip -c /backups/db-latest.sql.gz | psql -h $DB_HOST -U $DB_USER $DB_NAME

Health Checks

SaaS

GovernanceAI monitors system health automatically. Check status at:

On-Premise

Check Control Plane health:

curl -k https://governanceai.your-domain.com/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": "24h5m",
  "components": {
    "database": "ok",
    "cache": "ok",
    "runtime": "ok"
  }
}

Check Runtime Engine health:

curl -k https://runtime.governanceai.your-domain.com/health \
  -H "Authorization: Bearer <app-api-key>"

Troubleshooting

Cannot access dashboard

Check:

  • Internet connection is active
  • Firewall allows HTTPS (port 443)
  • DNS resolves correctly: nslookup governanceai.your-domain.com
  • TLS certificate is valid: openssl s_client -connect governanceai.your-domain.com:443

API calls failing with 401

Check:

  • API key is correct and not expired
  • API key scope includes required operations
  • Authorization header format: Authorization: Bearer <key>

Database connection errors

Check:

  • PostgreSQL service is running: pg_isready -h $DB_HOST
  • Credentials are correct
  • Network connectivity: telnet $DB_HOST 5432
  • SSL/TLS requirements if applicable

Performance issues

Check:

  • Database query performance: Check PostgreSQL logs
  • Redis memory usage: redis-cli info memory
  • CPU/Memory usage: kubectl top nodes (Kubernetes) or docker stats (Docker)
  • Check for slow policies

Next Steps