# Values\n\nUser configuration files for provisioning platform services (gitignored).\n\n## Purpose\n\nThe values directory stores:\n- **User configurations** - Service-specific settings for each deployment mode\n- **Generated Nickel configs** - Output from TypeDialog configuration wizard\n- **Customizations** - User-specific overrides to defaults\n- **Runtime data** - Persisted configuration state\n\n## File Organization\n\n```\nvalues/\n├── .gitignore                          # Ignore *.ncl user configs\n├── README.md                           # This file\n├── orchestrator.solo.ncl               # User config (gitignored)\n├── orchestrator.multiuser.ncl\n├── orchestrator.cicd.ncl\n├── orchestrator.enterprise.ncl\n├── control-center.solo.ncl\n├── control-center.multiuser.ncl\n├── control-center.cicd.ncl\n├── control-center.enterprise.ncl\n├── mcp-server.solo.ncl\n├── mcp-server.multiuser.ncl\n├── mcp-server.cicd.ncl\n├── mcp-server.enterprise.ncl\n├── installer.solo.ncl\n├── installer.multiuser.ncl\n├── installer.cicd.ncl\n├── installer.enterprise.ncl\n└── orchestrator.example.ncl            # Example template (tracked)\n```\n\n## Configuration Files\n\nEach config file (`{service}.{mode}.ncl`) is:\n- **Generated by TypeDialog** - Via `configure.nu` wizard\n- **User-specific** - Contains customizations for that environment\n- **Gitignored** - NOT tracked in version control\n- **Runtime data** - Created/updated by scripts and forms\n\nExample:\n\n```\n# values/orchestrator.solo.ncl (auto-generated, user-editable)\n{\n  orchestrator = {\n    workspace = {\n      name = "my-workspace",\n      path = "/home/user/workspace",\n      enabled = true,\n    },\n    server = {\n      host = "127.0.0.1",\n      port = 9090,\n      workers = 2,\n    },\n    storage = {\n      backend = 'filesystem,\n      path = "/home/user/.provisioning/data",\n    },\n  },\n}\n```\n\n## .gitignore Pattern\n\n```\n# values/.gitignore\n*.ncl          # Ignore all Nickel config files (user-specific)\n!*.example.ncl # EXCEPT example files (tracked for documentation)\n```\n\nThis ensures:\n- User configs (`orchestrator.solo.ncl`) are NOT committed\n- Example configs (`orchestrator.example.ncl`) ARE committed\n- Each user has their own configs without merge conflicts\n\n## Example Template\n\n`orchestrator.example.ncl` provides a documented template:\n\n```\n# orchestrator.example.ncl\n# Example configuration for Orchestrator service\n# Copy to orchestrator.{mode}.ncl and customize for your environment\n\n{\n  orchestrator = {\n    # Workspace Configuration\n    workspace = {\n      # Name of the workspace\n      name = "default",\n\n      # Absolute path to workspace directory\n      path = "/var/lib/provisioning/orchestrator",\n\n      # Enable this workspace\n      enabled = true,\n\n      # Allow serving multiple workspaces\n      multi_workspace = false,\n    },\n\n    # HTTP Server Configuration\n    server = {\n      # Bind address (127.0.0.1 for local only, 0.0.0.0 for network)\n      host = "127.0.0.1",\n\n      # Listen port\n      port = 9090,\n\n      # Worker thread count\n      workers = 4,\n\n      # Keep-alive timeout (seconds)\n      keep_alive = 75,\n    },\n\n    # Storage Configuration\n    storage = {\n      # Backend: 'filesystem | 'rocksdb | 'surrealdb | 'postgres\n      backend = 'filesystem,\n\n      # Path for filesystem/rocksdb storage\n      path = "/var/lib/provisioning/orchestrator/data",\n    },\n\n    # Queue Configuration\n    queue = {\n      # Maximum concurrent tasks\n      max_concurrent_tasks = 5,\n\n      # Retry attempts for failed tasks\n      retry_attempts = 3,\n\n      # Delay between retries (milliseconds)\n      retry_delay = 5000,\n\n      # Task execution timeout (milliseconds)\n      task_timeout = 3600000,\n    },\n  },\n}\n```\n\n## Configuration Workflow\n\n### 1. Generate Initial Config\n\n```\nnu scripts/configure.nu orchestrator solo\n```\n\nCreates `values/orchestrator.solo.ncl` from form input.\n\n### 2. Edit Configuration\n\n```\n# Manually edit if needed\nvi values/orchestrator.solo.ncl\n\n# Or reconfigure with wizard\nnu scripts/configure.nu orchestrator solo --backend web\n```\n\n### 3. Validate Configuration\n\n```\nnu scripts/validate-config.nu values/orchestrator.solo.ncl\n```\n\n### 4. Generate TOML for Services\n\n```\nnu scripts/generate-configs.nu orchestrator solo\n```\n\nExports to `provisioning/platform/config/orchestrator.solo.toml` (consumed by Rust services).\n\n## Configuration Composition\n\nUser configs are composed with defaults during generation:\n\n```\ndefaults/orchestrator-defaults.ncl (base values)\n    ↓ &\nvalues/orchestrator.solo.ncl (user customizations)\n    ↓\nconfigs/orchestrator.solo.ncl (final generated config)\n    ↓\nprovisioning/platform/config/orchestrator.solo.toml (Rust service config)\n```\n\n## Best Practices\n\n1. **Start with example** - Copy `orchestrator.example.ncl` as template\n2. **Document changes** - Add inline comments explaining customizations\n3. **Use TypeDialog** - Let wizard handle configuration for you\n4. **Validate before deploying** - Always run `validate-config.nu`\n5. **Keep defaults** - Only override what you need to change\n6. **Backup important configs** - Save known-good configurations\n\n## Sharing Configurations\n\nSince user configs are gitignored, sharing requires:\n\n### Option 1: Share via File\n\n```\n# Export current config\ncat values/orchestrator.solo.ncl > /tmp/orchestrator-config.ncl\n\n# Import on another system\ncp /tmp/orchestrator-config.ncl values/orchestrator.solo.ncl\n```\n\n### Option 2: Use Example Template\nShare setup instructions instead of raw config:\n\n```\n# Document the setup steps\ncat > SETUP.md << EOF\n1. Run: nu scripts/configure.nu orchestrator solo\n2. Set workspace path: /shared/workspace\n3. Set storage backend: postgres\n4. Set server workers: 8\nEOF\n```\n\n### Option 3: Store in Separate Repo\nFor team configs, use a separate private repository:\n\n```\n# Clone team configs\ngit clone private-repo/provisioning-configs values/\n\n# Use team configs\ncp values/team-orchestrator-solo.ncl values/orchestrator.solo.ncl\n```\n\n## File Permissions\n\nUser config files should have restricted permissions:\n\n```\n# Secure config file (if contains secrets)\nchmod 600 values/orchestrator.solo.ncl\n```\n\n## Recovery\n\nIf you accidentally delete a user config:\n\n### Option 1: Regenerate from TypeDialog\n\n```\nnu scripts/configure.nu orchestrator solo\n```\n\n### Option 2: Copy from Backup\n\n```\ncp /backup/provisioning-values/orchestrator.solo.ncl values/\n```\n\n### Option 3: Use Example as Base\n\n```\ncp examples/orchestrator-solo.ncl values/orchestrator.solo.ncl\n# Customize as needed\nnu scripts/configure.nu orchestrator solo --backend web\n```\n\n## Troubleshooting\n\n### Config File Missing\n\n```\n# Regenerate from defaults\nnu scripts/configure.nu orchestrator solo\n```\n\n### Config Won't Validate\n\n```\n# Check for syntax errors\nnickel eval values/orchestrator.solo.ncl\n\n# Compare with example\ndiff examples/orchestrator-solo.ncl values/orchestrator.solo.ncl\n```\n\n### Changes Not Taking Effect\n\n```\n# Regenerate TOML from Nickel\nnu scripts/generate-configs.nu orchestrator solo\n\n# Verify TOML was updated\nls -la provisioning/platform/config/orchestrator.solo.toml\n```\n\n---\n\n**Version**: 1.0.0\n**Last Updated**: 2025-01-05