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**:
```env
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:
```bash
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`:
   ```go
   module github.com/your-org/crossplane-provider-proxmox
   ```

2. Update all imports in Go files:
   ```bash
   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**:
   ```bash
   docker-compose up -d keycloak
   # Or use Kubernetes: kubectl apply -f gitops/apps/keycloak/
   ```

2. **Configure Environment Variables**:
   ```env
   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](./docs/tenants/IDENTITY_SETUP.md) for detailed instructions.

## Multi-Tenancy Configuration

### Enable Multi-Tenancy

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

### Billing Configuration

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

See [Tenant Management Guide](./docs/tenants/TENANT_MANAGEMENT.md) and [Billing Guide](./docs/tenants/BILLING_GUIDE.md) 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`