> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.governanceaicore.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.governanceaicore.com/_mcp/server.

# Installation & Setup

> Get GovernanceAI installed and configured for your environment

# 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](https://app.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:**

```bash
kubectl create namespace governanceai
```

**Add Helm repository:**

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

**Create values configuration** (`values.yaml`):

```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:**

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

**Verify installation:**

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

#### Step 2: Install via Docker Compose

**Download docker-compose file:**

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

**Configure environment** (`.env`):

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

```bash
docker-compose up -d
```

**Verify services:**

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

```bash
# Connect to PostgreSQL
psql -h $DB_HOST -U $DB_USER -d $DB_NAME

# List tables
\dt
```

#### Step 5: Backup Configuration

**Create backup schedule:**

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

```bash
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](https://status.governanceai.com)
* Dashboard → **Health & Diagnostics**

### On-Premise

**Check Control Plane health:**

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

Expected response:

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

**Check Runtime Engine health:**

```bash
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](./04-authentication.mdx)** - Generate credentials
* **[Quick Start](./05-quick-start.mdx)** - Make your first API call
* **[Integration Guides](../integrations/github-integration.mdx)** - Connect external systems