jesus/provisioning

Fork 0

Jesús Pérez a4b3c02371

chore: fix docs after fences fix

2026-01-14 04:53:21 +00:00

17 KiB

Raw Blame History

Unified Setup Guide

Quick Answer: Run provisioning setup profile and choose your profile.

Overview

The provisioning system uses a unified profile-based setup that creates type-safe configurations in your platform-specific home directory. No matter which profile you choose, all configurations are validated with Nickel before use.

Three Setup Profiles

| | Profile | Duration | Use Case | Deployment | Security | | | | --------- | ---------- | ---------- | ----------- | ---------- | | | | Developer | <5 min | Local development, testing, learning | Docker Compose (local) | Minimal (local defaults) | | | | Production | ~12 min | Production-ready, HA, team deployments | Kubernetes or SSH | Full (MFA, audit, policies) | | | | CI/CD | <2 min | Automated pipelines, ephemeral setup | Docker Compose (temp) | CI secrets | |

All profiles use Nickel-first architecture: configuration source of truth is type-safe Nickel, validated before use.

Quick Start (Choose Your Profile)

Developer Profile (Recommended for First Time)

# Run unified setup
provisioning setup profile --profile developer

# What happens:
# 1. Detects your OS and system capabilities
# 2. Creates Nickel configs in platform-specific location:
#    • macOS: ~/Library/Application Support/provisioning/
#    • Linux: ~/.config/provisioning/
# 3. Validates all configs with Nickel typecheck
# 4. Starts platform services (orchestrator, control-center, KMS)
# 5. Verifies health checks

# Verify it worked
curl http://localhost:9090/health
curl http://localhost:3000/health
curl http://localhost:3001/health

Expected output:

╔═════════════════════════════════════════════════════╗
║   PROVISIONING SETUP - DEVELOPER PROFILE            ║
╚═════════════════════════════════════════════════════╝

✓ System detected: macOS (aarch64)
✓ Docker available: Yes
✓ Configuration location: ~/Library/Application Support/provisioning/
✓ Config validation: PASSED (Nickel typecheck)
✓ Services started: Orchestrator, Control Center, KMS
✓ Health checks: All green

Setup complete in ~4 minutes!

Production Profile (HA, Security, Team Ready)

# Interactive setup for production
provisioning setup profile --profile production --interactive

# What happens:
# 1. Detects system: OS, CPU (≥4 required), memory (≥8GB recommended)
# 2. Asks for deployment mode: Kubernetes (preferred) or SSH
# 3. Asks for cloud provider: UpCloud, AWS, Hetzner, or local
# 4. Asks for security settings: MFA, audit logging, Cedar policies
# 5. Creates workspace infrastructure
# 6. Creates Nickel configs with production overlays
# 7. Validates all configs (Nickel typecheck)
# 8. Optionally starts services

# Setup with specific provider
provisioning setup profile --profile production --provider upcloud --interactive

# Verify Nickel configs validated
nickel typecheck ~/.config/provisioning/platform/deployment.ncl

Expected config structure:

~/.config/provisioning/
├── system.ncl                    # System detection + capabilities
├── user_preferences.ncl          # User settings (MFA, audit, etc.)
├── platform/
│   ├── deployment.ncl            # Deployment mode (kubernetes, ssh)
│   └── services.ncl              # Service endpoints and timeouts
├── providers/
│   ├── upcloud.ncl               # UpCloud config (RustyVault refs)
│   └── aws.ncl                   # AWS config (RustyVault refs)
├── workspaces/
│   └── infrastructure.ncl        # Infrastructure definitions
└── cedar-policies/
    └── default.cedar             # Authorization policies

CI/CD Profile (Automated, Ephemeral)

# Fully automated setup for pipelines
export PROVISIONING_PROVIDER=local
export PROVISIONING_WORKSPACE=ci-test-${CI_JOB_ID}

provisioning setup profile --profile cicd

# What happens:
# 1. No interaction (reads from env vars)
# 2. Creates ephemeral configs in /tmp/provisioning-ci-${CI_JOB_ID}/
# 3. Validates with Nickel typecheck
# 4. Starts Docker Compose services
# 5. Registers cleanup hook (auto-cleanup on exit)

# In your CI pipeline:
# Services run, tests execute, cleanup automatic

Configuration Locations (Platform-Aware)

Linux (XDG Base Directory)

# Primary location
~/.config/provisioning/

# Or with XDG_CONFIG_HOME override
$XDG_CONFIG_HOME/provisioning/

# Files created during setup
~/.config/provisioning/
├── system.ncl                   # Source of truth (Nickel)
├── user_preferences.ncl         # Source of truth (Nickel)
├── platform/
│   └── deployment.ncl           # Source of truth (Nickel)
└── generated/                   # Optional: For services needing TOML
    └── deployment.toml          # Auto-exported from deployment.ncl

macOS (Application Support)

# Platform-specific location
~/Library/Application Support/provisioning/

# Same structure as Linux
~/Library/Application Support/provisioning/
├── system.ncl                   # Source of truth (Nickel)
├── user_preferences.ncl         # Source of truth (Nickel)
├── platform/
│   └── deployment.ncl           # Source of truth (Nickel)
└── generated/                   # Optional
    └── deployment.toml

Key Principle

Nickel is source of truth - All .ncl files are authoritative, type-safe configurations validated by nickel typecheck. TOML files (if generated) are optional output only, never edited directly.

What Happens During Setup

Step 1: System Detection

Provisioning detects:

OS: macOS or Linux (Darwin detection)
Architecture: aarch64 or x86_64
CPU Count: Number of processors
Memory: Total system RAM in GB
Disk Space: Total available disk

# View detected system
provisioning setup detect --verbose

Step 2: Profile Selection

You choose between:

Developer: Fast local setup, Docker Compose
Production: Full validation, Kubernetes/SSH, HA ready
CI/CD: Ephemeral, automated, no interaction

Step 3: Config Generation (Nickel-Based)

Setup creates Nickel configs using composition:

# Example: system.ncl is composed from:
let helpers = import "../../schemas/platform/common/helpers.ncl"
let defaults = import "../../schemas/platform/defaults/system-defaults.ncl"

helpers.compose_config defaults {} {
  os_name = 'macos,
  cpu_count = 8,
  memory_total_gb = 16,
  setup_date = "2026-01-13T12:00:00Z"
}
| system_schema.SystemConfig  # Type contract validation

Result: Type-safe config, guaranteed valid structure and values.

Step 4: Validation (Mandatory)

All configs are validated:

# Done automatically during setup
nickel typecheck ~/.config/provisioning/system.ncl
nickel typecheck ~/.config/provisioning/platform/deployment.ncl

# You can verify anytime
nickel typecheck ~/.config/provisioning/**/*.ncl

Step 5: Service Bootstrap (Profile-Dependent)

Developer: Starts Docker Compose services locally

docker-compose up -d orchestrator control-center kms

Production: Outputs Kubernetes manifests (doesn't auto-start, you review first)

cat ~/.config/provisioning/platform/deployment.ncl
# Review, then deploy to your cluster
kubectl apply -f generated-from-deployment.ncl

CI/CD: Starts ephemeral Docker Compose in /tmp

# Automatic cleanup on job exit
docker-compose -f /tmp/provisioning-ci-${JOB_ID}/compose.yml up
# Tests run, cleanup automatic on script exit

Profile Comparison Details

Developer Profile

Goal: Working provisioning system in less than 5 minutes, minimal configuration

What gets created:

System config (auto-detected, no prompts)
User preferences (recommended defaults)
Docker Compose deployment (local mode)
Local provider (no credentials needed)

Security:

All configs validated (Nickel typecheck)
Services use secure defaults
No external API keys needed
Passwords auto-generated and stored locally

Time: 3-4 minutes

Example:

provisioning setup profile --profile developer

# Output:
# ✓ Detected: macOS, aarch64, 8 CPU, 16GB RAM
# ✓ Created: ~/.config/provisioning/system.ncl
# ✓ Created: ~/.config/provisioning/platform/deployment.ncl
# ✓ Validated: All configs passed typecheck
# ✓ Started: orchestrator (port 9090)
# ✓ Started: control-center (port 3000)
# ✓ Started: kms (port 3001)
# ✓ Ready in 3 minutes 45 seconds

Production Profile

Goal: HA-ready, validated, secure deployment with full control

What gets created:

System config (auto-detected)
User preferences (security-focused: MFA enabled, audit on)
Kubernetes or SSH deployment (your choice)
Cloud provider config (UpCloud, AWS, Hetzner, or local)
Workspace infrastructure (full IaC definitions)
Cedar authorization policies (fine-grained RBAC)

Security:

All configs validated (Nickel typecheck)
Requires system minimums: 4+ CPU, 8+ GB RAM
MFA enabled by default (can configure)
Audit logging enabled (captures all operations)
Cedar policies for authorization
Credentials stored encrypted (RustyVault)

Time: 10-15 minutes (interactive, many questions)

Example:

provisioning setup profile --profile production --interactive

# Prompts:
# Profile: Production ✓
# Deployment mode? (kubernetes/ssh): kubernetes
# Cloud provider? (upcloud/aws/hetzner/local): upcloud
# Workspace name? my-prod-infra
# Enable MFA? (y/n): y
# Enable audit logging? (y/n): y
# Number of master nodes? (1-5): 3
# Worker node count? (2-10): 5

# Output (15 minutes later):
# ✓ Created: ~/.config/provisioning/system.ncl
# ✓ Created: ~/.config/provisioning/platform/deployment.ncl
# ✓ Created: ~/.config/provisioning/providers/upcloud.ncl
# ✓ Created: workspace-prod-infra/infrastructure.ncl
# ✓ Created: cedar-policies/default.cedar
# ✓ Validated: All configs passed typecheck
# ✓ Services NOT started (you'll deploy to cluster)
# ✓ Ready for Kubernetes deployment

CI/CD Profile

Goal: Minimal setup, no interaction, auto-cleanup for pipelines

What gets created:

System config (minimal, CI environment)
Deployment config (ephemeral, auto-cleanup)
Docker Compose (no Kubernetes overhead)
Runs in /tmp (temporary directory)

Security:

All configs validated (Nickel typecheck)
No persistent state (by design)
Uses CI environment variables for secrets
Auto-cleanup on job completion
No credentials stored locally

Time: Less than 2 minutes

Example:

# In GitHub Actions:
- name: Setup Provisioning
  run: |
    export PROVISIONING_PROVIDER=local
    provisioning setup profile --profile cicd

# Output:
# ✓ Created: /tmp/provisioning-ci-abc123/
# ✓ Validated: All configs passed typecheck
# ✓ Started: Docker Compose services
# ✓ Services ready for tests
# Services will auto-cleanup on job exit

Verification

After Setup, Verify Everything Works

Developer Profile:

# Check configs exist
ls -la ~/.config/provisioning/
ls -la ~/.config/provisioning/platform/

# Verify Nickel validation
nickel typecheck ~/.config/provisioning/system.ncl
nickel typecheck ~/.config/provisioning/platform/deployment.ncl

# Test services
curl http://localhost:9090/health
curl http://localhost:3000/health
curl http://localhost:3001/health

# Expected: HTTP 200 with {"status": "healthy"}

Production Profile:

# Check Nickel configs
nickel typecheck ~/.config/provisioning/system.ncl
nickel typecheck ~/.config/provisioning/platform/deployment.ncl
nickel typecheck ~/.config/provisioning/providers/upcloud.ncl

# View deployment config
cat ~/.config/provisioning/platform/deployment.ncl

# View infrastructure definition
cat workspace-my-prod-infra/infrastructure.ncl

# View authorization policies
cat ~/.config/provisioning/cedar-policies/default.cedar

CI/CD Profile:

# Check temp configs exist
ls -la /tmp/provisioning-ci-*/

# Verify Nickel validation passed
nickel typecheck /tmp/provisioning-ci-*/platform/deployment.ncl

# Services should be running
docker ps | grep provisioning

Troubleshooting

Issue: "Nickel not found"

Cause: Nickel binary not installed

Solution:

# macOS
brew install nickel

# Linux (Arch)
pacman -S nickel

# From source
git clone https://github.com/nickel-lang/nickel
cd nickel && cargo install --path .

# Verify
nickel --version  # Should be 1.5.0+

Issue: "Configuration validation failed"

Cause: Nickel typecheck error in generated config

Solution:

# See detailed error
nickel typecheck ~/.config/provisioning/platform/deployment.ncl --color always

# Common issues:
# - Missing required field (check schema)
# - Wrong type (string vs number)
# - Enum value not in allowed list

# Delete and retry setup
rm -rf ~/.config/provisioning/
provisioning setup profile --profile developer --verbose

Issue: "Docker not available" (Developer Profile)

Cause: Docker not installed or not running

Solution:

# Check Docker
docker --version
docker ps

# macOS: Install Docker Desktop
brew install --cask docker

# Linux: Install Docker
sudo apt-get install docker.io  # Ubuntu/Debian
sudo pacman -S docker           # Arch

# Start Docker
sudo systemctl start docker

# Retry setup
provisioning setup profile --profile developer

Issue: "Services won't start"

Cause: Port already in use, Docker not running, or resource constraints

Solution:

# Check what's using ports 9090, 3000, 3001
lsof -i :9090
lsof -i :3000
lsof -i :3001

# Stop conflicting service or wait for it to release port

# Stop and restart provisioning services
docker-compose down
docker-compose up -d

# Check Docker resources
docker stats
docker system prune  # Free up space if needed

Issue: "Permission denied" on config directory

Cause: Directory created with wrong permissions

Solution:

# Fix permissions (macOS)
chmod 700 ~/Library/Application\ Support/provisioning/

# Fix permissions (Linux)
chmod 700 ~/.config/provisioning/

# Fix nested directories
chmod 700 ~/.config/provisioning/*

# Retry setup
provisioning setup profile --profile developer

Issue: "Wrong configuration being used"

Cause: Services reading from old location or wrong environment variable

Solution:

# Verify service sees new location
echo $PROVISIONING_CONFIG
# Should be: ~/.config/provisioning/platform/deployment.ncl

# Set explicitly if needed
export PROVISIONING_CONFIG=~/.config/provisioning/platform/deployment.ncl
provisioning service restart

# Check what service is actually loading
provisioning service status --verbose

Using Workspace-Specific Overrides

After initial setup, you can customize configs per workspace:

# Create workspace-specific override
mkdir -p workspace-myproject/config
cat > workspace-myproject/config/platform-overrides.ncl <<'EOF'
{
  orchestrator.server.port = 9999,
  orchestrator.workspace.name = "myproject",
  vault-service.storage.path = "./workspace-myproject/data/vault"
}
EOF

# Services will merge this with the base config
provisioning workspace activate myproject
provisioning platform deploy  # Uses merged config

Next Steps

After setup:

Create a Workspace
```
provisioning workspace create myapp
```
Deploy Your First Service
```
provisioning service deploy nginx
```
Configure Monitoring
```
provisioning monitor setup prometheus
```
Set Up CI/CD Integration
```
provisioning ci configure github
```
Learn Advanced Configuration
- See: Setup Profiles Guide
- See: Platform Configuration
- See: Nickel Configuration

Key Concepts

Type-Safe Configuration (Nickel)

All configs use Nickel type contracts:

Field names and types enforced
Enum values validated
Invalid configs caught at nickel typecheck time
No runtime surprises

Platform-Specific Paths

Configs stored in platform-standard locations:

Linux: ~/.config/provisioning/ (XDG Base Directory)
macOS: ~/Library/Application Support/provisioning/
Respects $XDG_CONFIG_HOME override on Linux

Composition Pattern

Configs built from:

Base defaults (provisioning/schemas/platform/defaults/)
Profile overlay (developer/production/cicd specific)
User customization (optional, via Nickel import)

Result: Minimal, validated, reproducible config.

Ephemeral vs. Persistent

Developer/Production: Persistent in home directory
CI/CD: Ephemeral in /tmp, auto-cleanup

Getting Help

# Help for setup
provisioning setup --help

# Help for profiles
provisioning setup profile --help

# Interactive debugging
provisioning setup profile --profile developer --verbose

# Validate configuration
provisioning setup validate

# View detected capabilities
provisioning setup detect --verbose

# Check platform status
provisioning platform status

# View logs
provisioning service logs orchestrator
provisioning service logs control-center
provisioning service logs kms

Ready? Run: provisioning setup profile and choose your profile!

Questions? Check Troubleshooting or Setup Profiles Guide

17 KiB Raw Blame History

Unified Setup Guide

Overview

Three Setup Profiles

Quick Start (Choose Your Profile)

Developer Profile (Recommended for First Time)

Production Profile (HA, Security, Team Ready)

CI/CD Profile (Automated, Ephemeral)

Configuration Locations (Platform-Aware)

Linux (XDG Base Directory)

macOS (Application Support)

Key Principle

What Happens During Setup

Step 1: System Detection

Step 2: Profile Selection

Step 3: Config Generation (Nickel-Based)

Step 4: Validation (Mandatory)

Step 5: Service Bootstrap (Profile-Dependent)

Profile Comparison Details

Developer Profile

Production Profile

CI/CD Profile

Verification

After Setup, Verify Everything Works

Troubleshooting

Issue: "Nickel not found"

Issue: "Configuration validation failed"

Issue: "Docker not available" (Developer Profile)

Issue: "Services won't start"

Issue: "Permission denied" on config directory

Issue: "Wrong configuration being used"

Using Workspace-Specific Overrides

Next Steps

Key Concepts

Type-Safe Configuration (Nickel)

Platform-Specific Paths

Composition Pattern

Ephemeral vs. Persistent

Getting Help

17 KiB

Raw Blame History