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

Option 1: SaaS (Recommended for Most)

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
2
postgresql:
3
  enabled: true
4
  auth:
5
    password: <strong-password>
6
  persistence:
7
    size: 100Gi
8
9
# Redis configuration
10
redis:
11
  enabled: true
12
  auth:
13
    password: <strong-password>
14
15
# Ingress configuration
16
ingress:
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
29
controlPlane:
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
40
runtime:
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:

• Status Page
• Dashboard → Health & Diagnostics

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

• Authentication & API Keys - Generate credentials
• Quick Start - Make your first API call
• Integration Guides - Connect external systems