Quick Start Guide

Time: 15 minutes
Prerequisites: Kubernetes cluster, kubectl, Terraform

Overview

This guide walks through:

Deploying Sovra control plane
Connecting an edge node
Creating your first workspace
Federating with a partner

Step 1: Deploy Control Plane

Clone Repository

git clone https://github.com/witlox/sovra.git
cd sovra

Configure

# Copy example configuration
cp config/example.yaml config/production.yaml

# Edit configuration
nano config/production.yaml

Required settings:

organization:
  id: org-a
  name: "Organization A"

database:
  host: postgres.example.com
  port: 5432
  name: sovra
  user: sovra
  
tls:
  ca_cert: /path/to/ca.crt
  server_cert: /path/to/server.crt
  server_key: /path/to/server.key

Deploy to Kubernetes

# Create namespace
kubectl create namespace sovra

# Deploy services
kubectl apply -k infrastructure/kubernetes/base

# Wait for pods
kubectl wait --for=condition=ready pod -l app=sovra -n sovra --timeout=300s

# Verify
kubectl get pods -n sovra

Expected output:

NAME                              READY   STATUS
api-gateway-0               1/1     Running

The api-gateway is a single service that handles all control plane functionality including policy evaluation, key lifecycle, audit, and federation.

Initialize Control Plane

# Run initialization script
./scripts/init-control-plane.sh

# This will:
# - Initialize PostgreSQL schema
# - Generate root CA
# - Create admin credentials
# - Set up initial policies

Save the output - you’ll need the admin credentials.

Step 2: Connect Edge Node

Deploy Vault Cluster

# Configure edge node
cd infrastructure/terraform/edge-node

# Copy variables
cp terraform.tfvars.example terraform.tfvars

# Edit for your cloud provider
nano terraform.tfvars

For AWS:

provider         = "aws"
region           = "eu-central-1"
organization_id  = "org-a"
node_id          = "edge-1"
instance_type    = "t3.medium"
vault_count      = 3

Deploy:

terraform init
terraform apply

Register Edge Node

# Install CLI
curl -s https://api.github.com/repos/witlox/sovra/releases/latest \
  | grep "browser_download_url.*linux_amd64.tar.gz" \
  | cut -d '"' -f 4 | xargs curl -LO
tar xzf sovra_*_linux_amd64.tar.gz
chmod +x sovra
sudo mv sovra /usr/local/bin/sovra

# Configure CLI
sovra config set control-plane https://sovra.example.org
sovra login --admin

# Register edge node
sovra edge-node register \
  --node-id edge-1 \
  --vault-addr https://vault-edge-1.example.org:8200

Verify Connection

sovra edge-node status edge-1

Expected output:

Edge Node: edge-1
Status: Connected
Last Heartbeat: 2s ago
Vault Status: Healthy (3/3 nodes)
Policies: Synced
Audit: Forwarding

Step 3: Create First Workspace

Generate Organization Root Key

# Generate CRK (Customer Root Key)
sovra crk generate \
  --org-id org-a \
  --output org-a-crk.json

# This creates Shamir shares (5-of-3)
# Store shares securely (different locations)

Create Workspace

# Create workspace for internal use
sovra workspace create \
  --name internal-keys \
  --participants org-a \
  --classification CONFIDENTIAL \
  --crk-sign org-a-crk.json

Test Encryption

# Encrypt data
echo "sensitive data" | sovra workspace encrypt \
  --workspace internal-keys \
  --output encrypted.dat

# Decrypt data
sovra workspace decrypt \
  --workspace internal-keys \
  --input encrypted.dat

Output:

sensitive data

View Audit Log

sovra audit query \
  --workspace internal-keys \
  --last 10

Step 4: Federate with Partner

Generate Federation Certificate

# Org A generates federation cert request
sovra federation init \
  --org-id org-a \
  --output org-a-federation-request.json

Exchange Certificates (Out-of-Band)

Send org-a-federation-request.json to Org B via secure channel.

Receive org-b-federation-cert.json from Org B.

Establish Federation

# Import partner certificate
sovra federation import \
  --cert org-b-federation-cert.json \
  --crk-sign org-a-crk.json

# Establish connection
sovra federation establish \
  --partner-id org-b \
  --partner-url https://sovra-org-b.example.org \
  --crk-sign org-a-crk.json

# Verify
sovra federation status org-b

Expected output:

Federation: org-a ↔ org-b
Status: Active
Established: 2026-01-29 12:00:00
Last Health Check: 5s ago
Shared Workspaces: 0

Create Shared Workspace

# Org A creates workspace
sovra workspace create \
  --name joint-research \
  --participants org-a,org-b \
  --classification CONFIDENTIAL \
  --crk-sign org-a-crk.json

# System automatically:
# 1. Generates DEK
# 2. Requests Org B's public key
# 3. Wraps DEK for Org B
# 4. Sends wrapped key to Org B

Org B can now use the workspace:

# Org B encrypts
echo "shared data" | sovra workspace encrypt \
  --workspace joint-research \
  --output shared-encrypted.dat

# Org A decrypts
sovra workspace decrypt \
  --workspace joint-research \
  --input shared-encrypted.dat

Both organizations see audit logs.

Troubleshooting

Control plane pods not starting

# Check logs
kubectl logs -n sovra -l app=api-gateway

# Common issues:
# - Database connection (check credentials)
# - Certificate issues (check TLS config)
# - Resource limits (check node capacity)

Edge node connection fails

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

# Check edge node logs
kubectl logs -n sovra-edge -l app=edge-agent

# Verify certificates
sovra edge-node cert verify edge-1

Federation establishment fails

# Check partner connectivity
curl -k https://sovra-partner.example.org/health

# Verify certificates
sovra federation cert verify org-b

# Check firewall rules (port 8443 for federation)

Questions? See GitHub Discussions