7.4 KiB
7.4 KiB
\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\norchestrator.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\nVersion: 1.0.0\nLast Updated: 2025-01-05