provisioning/schemas/platform/values

Values

User configuration files for provisioning platform services (gitignored).

Purpose

The values directory stores:

• User configurations - Service-specific settings for each deployment mode
• Generated Nickel configs - Output from TypeDialog configuration wizard
• Customizations - User-specific overrides to defaults
• Runtime data - Persisted configuration state

File Organization

values/
├── .gitignore                          # Ignore *.ncl user configs
├── README.md                           # This file
├── orchestrator.solo.ncl               # User config (gitignored)
├── orchestrator.multiuser.ncl
├── orchestrator.cicd.ncl
├── orchestrator.enterprise.ncl
├── control-center.solo.ncl
├── control-center.multiuser.ncl
├── control-center.cicd.ncl
├── control-center.enterprise.ncl
├── mcp-server.solo.ncl
├── mcp-server.multiuser.ncl
├── mcp-server.cicd.ncl
├── mcp-server.enterprise.ncl
├── installer.solo.ncl
├── installer.multiuser.ncl
├── installer.cicd.ncl
├── installer.enterprise.ncl
└── orchestrator.example.ncl            # Example template (tracked)

Configuration Files

Each config file ({service}.{mode}.ncl) is:

• Generated by TypeDialog - Via configure.nu wizard
• User-specific - Contains customizations for that environment
• Gitignored - NOT tracked in version control
• Runtime data - Created/updated by scripts and forms

Example:

# values/orchestrator.solo.ncl (auto-generated, user-editable)
{
  orchestrator = {
    workspace = {
      name = "my-workspace",
      path = "/home/user/workspace",
      enabled = true,
    },
    server = {
      host = "127.0.0.1",
      port = 9090,
      workers = 2,
    },
    storage = {
      backend = 'filesystem,
      path = "/home/user/.provisioning/data",
    },
  },
}

.gitignore Pattern

# values/.gitignore
*.ncl          # Ignore all Nickel config files (user-specific)
!*.example.ncl # EXCEPT example files (tracked for documentation)

This ensures:

• User configs (orchestrator.solo.ncl) are NOT committed
• Example configs (orchestrator.example.ncl) ARE committed
• Each user has their own configs without merge conflicts

Example Template

orchestrator.example.ncl provides a documented template:

# orchestrator.example.ncl
# Example configuration for Orchestrator service
# Copy to orchestrator.{mode}.ncl and customize for your environment

{
  orchestrator = {
    # Workspace Configuration
    workspace = {
      # Name of the workspace
      name = "default",

      # Absolute path to workspace directory
      path = "/var/lib/provisioning/orchestrator",

      # Enable this workspace
      enabled = true,

      # Allow serving multiple workspaces
      multi_workspace = false,
    },

    # HTTP Server Configuration
    server = {
      # Bind address (127.0.0.1 for local only, 0.0.0.0 for network)
      host = "127.0.0.1",

      # Listen port
      port = 9090,

      # Worker thread count
      workers = 4,

      # Keep-alive timeout (seconds)
      keep_alive = 75,
    },

    # Storage Configuration
    storage = {
      # Backend: 'filesystem | 'rocksdb | 'surrealdb | 'postgres
      backend = 'filesystem,

      # Path for filesystem/rocksdb storage
      path = "/var/lib/provisioning/orchestrator/data",
    },

    # Queue Configuration
    queue = {
      # Maximum concurrent tasks
      max_concurrent_tasks = 5,

      # Retry attempts for failed tasks
      retry_attempts = 3,

      # Delay between retries (milliseconds)
      retry_delay = 5000,

      # Task execution timeout (milliseconds)
      task_timeout = 3600000,
    },
  },
}

Configuration Workflow

1. Generate Initial Config

nu scripts/configure.nu orchestrator solo

Creates values/orchestrator.solo.ncl from form input.

2. Edit Configuration

# Manually edit if needed
vi values/orchestrator.solo.ncl

# Or reconfigure with wizard
nu scripts/configure.nu orchestrator solo --backend web

3. Validate Configuration

nu scripts/validate-config.nu values/orchestrator.solo.ncl

4. Generate TOML for Services

nu scripts/generate-configs.nu orchestrator solo

Exports to provisioning/platform/config/orchestrator.solo.toml (consumed by Rust services).

Configuration Composition

User configs are composed with defaults during generation:

defaults/orchestrator-defaults.ncl (base values)
    ↓ &
values/orchestrator.solo.ncl (user customizations)
    ↓
configs/orchestrator.solo.ncl (final generated config)
    ↓
provisioning/platform/config/orchestrator.solo.toml (Rust service config)

Best Practices

1. Start with example - Copy orchestrator.example.ncl as template
2. Document changes - Add inline comments explaining customizations
3. Use TypeDialog - Let wizard handle configuration for you
4. Validate before deploying - Always run validate-config.nu
5. Keep defaults - Only override what you need to change
6. Backup important configs - Save known-good configurations

Sharing Configurations

Since user configs are gitignored, sharing requires:

Option 1: Share via File

# Export current config
cat values/orchestrator.solo.ncl > /tmp/orchestrator-config.ncl

# Import on another system
cp /tmp/orchestrator-config.ncl values/orchestrator.solo.ncl

Option 2: Use Example Template

Share setup instructions instead of raw config:

# Document the setup steps
cat > SETUP.md << EOF
1. Run: nu scripts/configure.nu orchestrator solo
2. Set workspace path: /shared/workspace
3. Set storage backend: postgres
4. Set server workers: 8
EOF

Option 3: Store in Separate Repo

For team configs, use a separate private repository:

# Clone team configs
git clone private-repo/provisioning-configs values/

# Use team configs
cp values/team-orchestrator-solo.ncl values/orchestrator.solo.ncl

File Permissions

User config files should have restricted permissions:

# Secure config file (if contains secrets)
chmod 600 values/orchestrator.solo.ncl

Recovery

If you accidentally delete a user config:

Option 1: Regenerate from TypeDialog

nu scripts/configure.nu orchestrator solo

Option 2: Copy from Backup

cp /backup/provisioning-values/orchestrator.solo.ncl values/

Option 3: Use Example as Base

cp examples/orchestrator-solo.ncl values/orchestrator.solo.ncl
# Customize as needed
nu scripts/configure.nu orchestrator solo --backend web

Troubleshooting

Config File Missing

# Regenerate from defaults
nu scripts/configure.nu orchestrator solo

Config Won't Validate

# Check for syntax errors
nickel eval values/orchestrator.solo.ncl

# Compare with example
diff examples/orchestrator-solo.ncl values/orchestrator.solo.ncl

Changes Not Taking Effect

# Regenerate TOML from Nickel
nu scripts/generate-configs.nu orchestrator solo

# Verify TOML was updated
ls -la provisioning/platform/config/orchestrator.solo.toml

---

Version: 1.0.0 Last Updated: 2025-01-05