provisioning/schemas/platform/values/README.md

# 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

```plaintext
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:

```nickel
# 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

```plaintext
# 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:

```nickel
# 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

```bash
nu scripts/configure.nu orchestrator solo
```

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

### 2. Edit Configuration

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

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

### 3. Validate Configuration

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

### 4. Generate TOML for Services

```bash
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:

```plaintext
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

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
nu scripts/configure.nu orchestrator solo
```

### Option 2: Copy from Backup

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

### Option 3: Use Example as Base

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

## Troubleshooting

### Config File Missing

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

### Config Won't Validate

```bash
# 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

```bash
# 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