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

1# Database configuration
2postgresql:
3  enabled: true
4  auth:
5    password: <strong-password>
6  persistence:
7    size: 100Gi
8
9# Redis configuration
10redis:
11  enabled: true
12  auth:
13    password: <strong-password>
14
15# Ingress configuration
16ingress:
17  enabled: true
18  hosts:
19    - host: governanceai.your-domain.com
20      paths:
21        - path: /
22          pathType: Prefix
23  tls:
24    - secretName: governanceai-tls
25      hosts:
26        - governanceai.your-domain.com
27
28# Control Plane settings
29controlPlane:
30  replicas: 3
31  resources:
32    requests:
33      cpu: 2
34      memory: 4Gi
35    limits:
36      cpu: 4
37      memory: 8Gi
38
39# Runtime Engine settings
40runtime:
41  replicas: 5
42  resources:
43    requests:
44      cpu: 1
45      memory: 2Gi
46    limits:
47      cpu: 2
48      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:

1{
2  "status": "healthy",
3  "version": "1.0.0",
4  "uptime": "24h5m",
5  "components": {
6    "database": "ok",
7    "cache": "ok",
8    "runtime": "ok"
9  }
10}

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