Sankofa/CONFIGURATION_GUIDE.md

Configuration Guide

Organization and Domain Configuration

Crossplane API Group

The Crossplane provider uses a configurable API group. Set the following environment variable:

Portal:

NEXT_PUBLIC_CROSSPLANE_API_GROUP=proxmox.sankofa.nexus

Default: proxmox.sankofa.nexus

To use a different organization:

1. Update the Crossplane provider's API group in crossplane-provider-proxmox/apis/v1alpha1/groupversion_info.go
2. Set NEXT_PUBLIC_CROSSPLANE_API_GROUP to match

Git Repository URL

ArgoCD Application (gitops/apps/argocd/application.yaml):

• Uses environment variable substitution: ${GIT_REPO_URL}
• Default: https://github.com/YOUR_ORG/sankofa-phoenix

To configure:

export GIT_REPO_URL=https://github.com/your-org/sankofa-phoenix
kubectl apply -f gitops/apps/argocd/application.yaml

Or edit the file directly before applying.

Go Module Path

File: crossplane-provider-proxmox/go.mod

Current: module github.com/sankofa/crossplane-provider-proxmox

To change:

1. Update go.mod:

   module github.com/your-org/crossplane-provider-proxmox
   

2. Update all imports in Go files:

   find crossplane-provider-proxmox -name "*.go" -exec sed -i 's|github.com/sankofa|github.com/your-org|g' {} \;
   

3. Run go mod tidy

Domain Configuration

All domain placeholders should be replaced with actual domains:

• sankofa.nexus → Your actual domain (currently using sankofa.nexus as placeholder)
• Replace with your actual domain in production
• sankofa.nexus → Your actual domain (if different)

Sovereign Identity Configuration (Keycloak)

Keycloak Setup

Sankofa Phoenix uses Keycloak for sovereign identity management (NO Azure dependencies):

1. Deploy Keycloak:

   docker-compose up -d keycloak
   # Or use Kubernetes: kubectl apply -f gitops/apps/keycloak/
   

2. Configure Environment Variables:

   KEYCLOAK_URL=http://localhost:8080
   KEYCLOAK_REALM=master
   KEYCLOAK_CLIENT_ID=sankofa-api
   KEYCLOAK_CLIENT_SECRET=your-client-secret
   KEYCLOAK_MULTI_REALM=true
   

3. Create Clients:

   • API client: sankofa-api (confidential)
   • Portal client: portal-client (confidential)

4. Multi-Realm Support (Optional):

   • Set KEYCLOAK_MULTI_REALM=true for tenant isolation
   • Each tenant gets its own Keycloak realm automatically

See Identity Setup Guide for detailed instructions.

Multi-Tenancy Configuration

Enable Multi-Tenancy

ENABLE_MULTI_TENANT=true
DEFAULT_TENANT_ID=  # Leave empty for system resources
BLOCKCHAIN_IDENTITY_ENABLED=true

Billing Configuration

BILLING_GRANULARITY=SECOND  # SECOND, MINUTE, HOUR
BLOCKCHAIN_BILLING_ENABLED=true

See Tenant Management Guide and Billing Guide for details.

Environment Variables Summary

Required for Production

• JWT_SECRET - Must be changed from default
• DB_PASSWORD - Must be changed from default
• KEYCLOAK_URL - Actual Keycloak instance
• KEYCLOAK_CLIENT_ID - Keycloak client ID
• KEYCLOAK_CLIENT_SECRET - Keycloak client secret
• NEXT_PUBLIC_* - All public URLs must point to production services

Optional but Recommended

• ENABLE_MULTI_TENANT - Enable multi-tenancy (default: false)
• KEYCLOAK_MULTI_REALM - Enable multi-realm support (default: false)
• BILLING_GRANULARITY - Billing granularity (default: HOUR)
• BLOCKCHAIN_IDENTITY_ENABLED - Enable blockchain identity (default: false)
• BLOCKCHAIN_BILLING_ENABLED - Enable blockchain billing (default: false)
• SENTRY_DSN - Error tracking
• BLOCKCHAIN_* - If using blockchain features
• LOG_LEVEL - Set to info or warn in production

Quick Configuration Checklist

• Update JWT_SECRET in production
• Update DB_PASSWORD in production
• Deploy and configure Keycloak
• Create Keycloak clients (API and Portal)
• Set KEYCLOAK_CLIENT_SECRET in production
• Enable multi-tenancy if needed (ENABLE_MULTI_TENANT=true)
• Configure billing granularity (BILLING_GRANULARITY)
• Set NEXT_PUBLIC_CROSSPLANE_API_GROUP if different from default
• Update Git repository URL in ArgoCD application
• Replace all domain placeholders
• Configure error tracking (Sentry or custom)
• Set up proper logging in production
• Review and update all localhost defaults
• Run database migrations: cd api && npm run db:migrate