Installation Guide

Prerequisites

System Requirements

Control Plane:

Kubernetes 1.29+
3 nodes minimum (HA)
4 vCPU, 8GB RAM per node
100GB storage (SSD recommended)

Edge Node:

3 VMs or K8s nodes
2 vCPU, 4GB RAM per node
50GB storage per node

Network:

TLS 1.3 support
mTLS certificate capability
Internet connectivity (or air-gap setup)

Software Requirements

kubectl 1.29+
Terraform 1.7+ (for infrastructure provisioning)
PostgreSQL 15+ (managed or self-hosted)
Go 1.25+ (for building from source)

Installation Methods

Method 1: Kubernetes (Recommended)

# Clone repository
git clone https://github.com/witlox/sovra.git
cd sovra

# Install with Kustomize
kubectl create namespace sovra
kubectl apply -k infrastructure/kubernetes/base

Method 2: Terraform + Ansible

# Provision infrastructure
cd infrastructure/terraform/control-plane
terraform init
terraform apply

# Configure with Ansible
cd ../../ansible
ansible-playbook -i inventory/production.ini playbooks/deploy-control-plane.yml

Method 3: Build from Source

# Build all packages
make build

# Build binaries to bin/
make build-bin

# Build Docker image
make docker-build

# Deploy
docker-compose up -d

PostgreSQL Setup

Option 1: Managed (Recommended)

Use cloud provider managed PostgreSQL:

AWS RDS
Azure Database for PostgreSQL
GCP Cloud SQL
Exoscale PostgreSQL

Option 2: Self-Hosted

# Deploy PostgreSQL with operator
kubectl apply -f https://github.com/zalando/postgres-operator/releases/download/v1.10.0/postgres-operator.yaml

# Create database
kubectl apply -f infrastructure/kubernetes/postgresql/

Configuration:

apiVersion: acid.zalan.do/v1
kind: postgresql
metadata:
  name: sovra-postgres
spec:
  teamId: sovra
  volume:
    size: 100Gi
  numberOfInstances: 3
  users:
    sovra: []
  databases:
    sovra: sovra
  postgresql:
    version: "15"

Certificate Setup

Generate Root CA

# Generate CA
openssl genrsa -out ca-key.pem 4096
openssl req -new -x509 -days 3650 -key ca-key.pem -out ca.crt

# Store securely (offline storage recommended)

Generate Control Plane Certificates

# Server certificate
openssl genrsa -out server-key.pem 2048
openssl req -new -key server-key.pem -out server.csr
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca-key.pem -CAcreateserial -out server.crt -days 365

Store in Kubernetes Secrets

kubectl create secret tls sovra-tls \
  --cert=server.crt \
  --key=server-key.pem \
  -n sovra

kubectl create secret generic sovra-ca \
  --from-file=ca.crt=ca.crt \
  -n sovra

Configuration

Control Plane Configuration

# config/production.yaml
org_id: org-a
log_level: info

server:
  host: 0.0.0.0
  port: 8080
  tls_enabled: true
  tls_cert_file: /etc/sovra/tls/server.crt
  tls_key_file: /etc/sovra/tls/server.key
  mtls_enabled: true
  tls_ca_file: /etc/sovra/tls/ca.crt

database:
  host: postgres.sovra.svc.cluster.local
  port: 5432
  database: sovra
  username: sovra
  password: ${SOVRA_DATABASE_PASSWORD}
  ssl_mode: require

vault:
  address: https://vault.example.org:8200
  token: ${SOVRA_VAULT_TOKEN}

opa:
  address: http://opa.sovra.svc:8181

Deploy Configuration

kubectl create configmap sovra-config \
  --from-file=config/production.yaml \
  -n sovra

Initialization

Run Init Script

./scripts/init-control-plane.sh

This script:

Initializes PostgreSQL schema
Creates admin user
Generates organization root key
Sets up default policies
Configures initial audit settings

Verify Installation

# Check pod status
kubectl get pods -n sovra

# Check services
kubectl get svc -n sovra

# Test API
curl -k https://sovra.example.org/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.0"
}

Troubleshooting

Database Connection Issues

# Test database connectivity
kubectl run -it --rm debug --image=postgres:15 --restart=Never -- \
  psql -h postgres.sovra.svc.cluster.local -U sovra -d sovra

# Check credentials
kubectl get secret sovra-postgres-password -n sovra -o jsonpath='{.data.password}' | base64 -d

Certificate Issues

# Verify certificate validity
openssl x509 -in server.crt -text -noout

# Check certificate in cluster
kubectl get secret sovra-tls -n sovra -o yaml

Port Conflicts

# Check what's using port 8443
sudo netstat -tulpn | grep 8443

# Update service port if needed
kubectl edit svc api-gateway -n sovra