2025-12-11 21:50:42 +00:00
<!DOCTYPE HTML>
< html lang = "en" class = "ayu sidebar-visible" dir = "ltr" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
2026-01-08 09:55:37 +00:00
< title > Home - Provisioning Platform Documentation< / title >
2025-12-11 21:50:42 +00:00
<!-- Custom HTML head -->
< meta name = "description" content = "Complete documentation for the Provisioning Platform - Infrastructure automation with Nushell, KCL, and Rust" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" >
< link rel = "icon" href = "favicon.svg" >
< link rel = "shortcut icon" href = "favicon.png" >
< link rel = "stylesheet" href = "css/variables.css" >
< link rel = "stylesheet" href = "css/general.css" >
< link rel = "stylesheet" href = "css/chrome.css" >
< link rel = "stylesheet" href = "css/print.css" media = "print" >
<!-- Fonts -->
< link rel = "stylesheet" href = "FontAwesome/css/font-awesome.css" >
< link rel = "stylesheet" href = "fonts/fonts.css" >
<!-- Highlight.js Stylesheets -->
< link rel = "stylesheet" id = "highlight-css" href = "highlight.css" >
< link rel = "stylesheet" id = "tomorrow-night-css" href = "tomorrow-night.css" >
< link rel = "stylesheet" id = "ayu-highlight-css" href = "ayu-highlight.css" >
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
< script >
const path_to_root = "";
const default_light_theme = "ayu";
const default_dark_theme = "navy";
< / script >
<!-- Start loading toc.js asap -->
< script src = "toc.js" > < / script >
< / head >
< body >
< div id = "mdbook-help-container" >
< div id = "mdbook-help-popup" >
< h2 class = "mdbook-help-title" > Keyboard shortcuts< / h2 >
< div >
< p > Press < kbd > ←< / kbd > or < kbd > →< / kbd > to navigate between chapters< / p >
< p > Press < kbd > S< / kbd > or < kbd > /< / kbd > to search in the book< / p >
< p > Press < kbd > ?< / kbd > to show this help< / p >
< p > Press < kbd > Esc< / kbd > to hide this help< / p >
< / div >
< / div >
< / div >
< div id = "body-container" >
<!-- Work around some values being stored in localStorage wrapped in quotes -->
< script >
try {
let theme = localStorage.getItem('mdbook-theme');
let sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') & & theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') & & sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
< / script >
<!-- Set the theme before any content is loaded, prevents flash -->
< script >
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('ayu')
html.classList.add(theme);
html.classList.add("js");
< / script >
< input type = "checkbox" id = "sidebar-toggle-anchor" class = "hidden" >
<!-- Hide / unhide sidebar before it is displayed -->
< script >
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
< / script >
< nav id = "sidebar" class = "sidebar" aria-label = "Table of contents" >
<!-- populated by js -->
< mdbook-sidebar-scrollbox class = "sidebar-scrollbox" > < / mdbook-sidebar-scrollbox >
< noscript >
< iframe class = "sidebar-iframe-outer" src = "toc.html" > < / iframe >
< / noscript >
< div id = "sidebar-resize-handle" class = "sidebar-resize-handle" >
< div class = "sidebar-resize-indicator" > < / div >
< / div >
< / nav >
< div id = "page-wrapper" class = "page-wrapper" >
< div class = "page" >
< div id = "menu-bar-hover-placeholder" > < / div >
< div id = "menu-bar" class = "menu-bar sticky" >
< div class = "left-buttons" >
< label id = "sidebar-toggle" class = "icon-button" for = "sidebar-toggle-anchor" title = "Toggle Table of Contents" aria-label = "Toggle Table of Contents" aria-controls = "sidebar" >
< i class = "fa fa-bars" > < / i >
< / label >
< button id = "theme-toggle" class = "icon-button" type = "button" title = "Change theme" aria-label = "Change theme" aria-haspopup = "true" aria-expanded = "false" aria-controls = "theme-list" >
< i class = "fa fa-paint-brush" > < / i >
< / button >
< ul id = "theme-list" class = "theme-popup" aria-label = "Themes" role = "menu" >
< li role = "none" > < button role = "menuitem" class = "theme" id = "default_theme" > Auto< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "light" > Light< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "rust" > Rust< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "coal" > Coal< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "navy" > Navy< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "ayu" > Ayu< / button > < / li >
< / ul >
< button id = "search-toggle" class = "icon-button" type = "button" title = "Search (`/`)" aria-label = "Toggle Searchbar" aria-expanded = "false" aria-keyshortcuts = "/ s" aria-controls = "searchbar" >
< i class = "fa fa-search" > < / i >
< / button >
< / div >
< h1 class = "menu-title" > Provisioning Platform Documentation< / h1 >
< div class = "right-buttons" >
< a href = "print.html" title = "Print this book" aria-label = "Print this book" >
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
< a href = "https://github.com/provisioning/provisioning-platform" title = "Git repository" aria-label = "Git repository" >
< i id = "git-repository-button" class = "fa fa-github" > < / i >
< / a >
< a href = "https://github.com/provisioning/provisioning-platform/edit/main/provisioning/docs/src/README.md" title = "Suggest an edit" aria-label = "Suggest an edit" >
< i id = "git-edit-button" class = "fa fa-edit" > < / i >
< / a >
< / div >
< / div >
< div id = "search-wrapper" class = "hidden" >
< form id = "searchbar-outer" class = "searchbar-outer" >
< input type = "search" id = "searchbar" name = "searchbar" placeholder = "Search this book ..." aria-controls = "searchresults-outer" aria-describedby = "searchresults-header" >
< / form >
< div id = "searchresults-outer" class = "searchresults-outer hidden" >
< div id = "searchresults-header" class = "searchresults-header" > < / div >
< ul id = "searchresults" >
< / ul >
< / div >
< / div >
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
< script >
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
< / script >
< div id = "content" class = "content" >
< main >
< p align = "center" >
< img src = "resources/provisioning_logo.svg" alt = "Provisioning Logo" width = "300" / >
< / p >
< p align = "center" >
< img src = "resources/logo-text.svg" alt = "Provisioning" width = "500" / >
< / p >
< h1 id = "provisioning-platform-documentation" > < a class = "header" href = "#provisioning-platform-documentation" > Provisioning Platform Documentation< / a > < / h1 >
2026-01-08 09:55:37 +00:00
< p > < strong > Last Updated< / strong > : 2025-01-02 (Phase 3.A Cleanup Complete)
< strong > Status< / strong > : ✅ Primary documentation source (145 files consolidated)< / p >
2025-12-11 21:50:42 +00:00
< p > Welcome to the comprehensive documentation for the Provisioning Platform - a modern, cloud-native infrastructure automation system built with Nushell, KCL, and Rust.< / p >
2026-01-08 09:55:37 +00:00
< blockquote >
< p > < strong > Note< / strong > : Architecture Decision Records (ADRs) and high-level design documentation are in < code > docs/< / code > directory. This location contains all user-facing, operational, and product documentation.< / p >
< / blockquote >
2025-12-11 21:50:42 +00:00
< hr / >
< h2 id = "quick-navigation" > < a class = "header" href = "#quick-navigation" > Quick Navigation< / a > < / h2 >
< h3 id = "-getting-started" > < a class = "header" href = "#-getting-started" > 🚀 Getting Started< / a > < / h3 >
< div class = "table-wrapper" > < table > < thead > < tr > < th > Document< / th > < th > Description< / th > < th > Audience< / th > < / tr > < / thead > < tbody >
2026-01-08 09:55:37 +00:00
< tr > < td > < strong > < a href = "getting-started/installation-guide.html" > Installation Guide< / a > < / strong > < / td > < td > Install and configure the system< / td > < td > New Users< / td > < / tr >
< tr > < td > < strong > < a href = "getting-started/getting-started.html" > Getting Started< / a > < / strong > < / td > < td > First steps and basic concepts< / td > < td > New Users< / td > < / tr >
< tr > < td > < strong > < a href = "getting-started/quickstart-cheatsheet.html" > Quick Reference< / a > < / strong > < / td > < td > Command cheat sheet< / td > < td > All Users< / td > < / tr >
2025-12-11 21:50:42 +00:00
< tr > < td > < strong > < a href = "guides/from-scratch.html" > From Scratch Guide< / a > < / strong > < / td > < td > Complete deployment walkthrough< / td > < td > New Users< / td > < / tr >
< / tbody > < / table >
< / div >
< h3 id = "-user-guides" > < a class = "header" href = "#-user-guides" > 📚 User Guides< / a > < / h3 >
< div class = "table-wrapper" > < table > < thead > < tr > < th > Document< / th > < th > Description< / th > < / tr > < / thead > < tbody >
2026-01-08 09:55:37 +00:00
< tr > < td > < strong > < a href = "infrastructure/cli-reference.html" > CLI Reference< / a > < / strong > < / td > < td > Complete command reference< / td > < / tr >
< tr > < td > < strong > < a href = "infrastructure/workspace-setup.html" > Workspace Management< / a > < / strong > < / td > < td > Workspace creation and management< / td > < / tr >
< tr > < td > < strong > < a href = "infrastructure/workspace-switching-guide.html" > Workspace Switching< / a > < / strong > < / td > < td > Switch between workspaces< / td > < / tr >
< tr > < td > < strong > < a href = "infrastructure/infrastructure-management.html" > Infrastructure Management< / a > < / strong > < / td > < td > Server, taskserv, cluster operations< / td > < / tr >
< tr > < td > < strong > < a href = "operations/service-management-guide.html" > Service Management< / a > < / strong > < / td > < td > Platform service lifecycle management< / td > < / tr >
< tr > < td > < strong > < a href = "integration/oci-registry-guide.html" > OCI Registry< / a > < / strong > < / td > < td > OCI artifact management< / td > < / tr >
< tr > < td > < strong > < a href = "integration/gitea-integration-guide.html" > Gitea Integration< / a > < / strong > < / td > < td > Git workflow and collaboration< / td > < / tr >
< tr > < td > < strong > < a href = "operations/coredns-guide.html" > CoreDNS Guide< / a > < / strong > < / td > < td > DNS management< / td > < / tr >
< tr > < td > < strong > < a href = "testing/test-environment-usage.html" > Test Environments< / a > < / strong > < / td > < td > Containerized testing< / td > < / tr >
< tr > < td > < strong > < a href = "development/extension-development.html" > Extension Development< / a > < / strong > < / td > < td > Create custom extensions< / td > < / tr >
2025-12-11 21:50:42 +00:00
< / tbody > < / table >
< / div >
< h3 id = "-architecture" > < a class = "header" href = "#-architecture" > 🏗️ Architecture< / a > < / h3 >
< div class = "table-wrapper" > < table > < thead > < tr > < th > Document< / th > < th > Description< / th > < / tr > < / thead > < tbody >
< tr > < td > < strong > < a href = "architecture/system-overview.html" > System Overview< / a > < / strong > < / td > < td > High-level architecture< / td > < / tr >
2026-01-08 09:55:37 +00:00
< tr > < td > < strong > < a href = "architecture/multi-repo-architecture.html" > Multi-Repo Architecture< / a > < / strong > < / td > < td > Repository structure and OCI distribution< / td > < / tr >
2025-12-11 21:50:42 +00:00
< tr > < td > < strong > < a href = "architecture/design-principles.html" > Design Principles< / a > < / strong > < / td > < td > Architectural philosophy< / td > < / tr >
< tr > < td > < strong > < a href = "architecture/integration-patterns.html" > Integration Patterns< / a > < / strong > < / td > < td > System integration patterns< / td > < / tr >
< tr > < td > < strong > < a href = "architecture/orchestrator-integration-model.html" > Orchestrator Model< / a > < / strong > < / td > < td > Hybrid orchestration architecture< / td > < / tr >
< / tbody > < / table >
< / div >
< h3 id = "-architecture-decision-records-adrs" > < a class = "header" href = "#-architecture-decision-records-adrs" > 📋 Architecture Decision Records (ADRs)< / a > < / h3 >
< div class = "table-wrapper" > < table > < thead > < tr > < th > ADR< / th > < th > Title< / th > < th > Status< / th > < / tr > < / thead > < tbody >
2026-01-08 09:55:37 +00:00
< tr > < td > < strong > < a href = "architecture/adr/adr-001-project-structure.html" > ADR-001< / a > < / strong > < / td > < td > Project Structure Decision< / td > < td > Accepted< / td > < / tr >
< tr > < td > < strong > < a href = "architecture/adr/adr-002-distribution-strategy.html" > ADR-002< / a > < / strong > < / td > < td > Distribution Strategy< / td > < td > Accepted< / td > < / tr >
< tr > < td > < strong > < a href = "architecture/adr/adr-003-workspace-isolation.html" > ADR-003< / a > < / strong > < / td > < td > Workspace Isolation< / td > < td > Accepted< / td > < / tr >
< tr > < td > < strong > < a href = "architecture/adr/adr-004-hybrid-architecture.html" > ADR-004< / a > < / strong > < / td > < td > Hybrid Architecture< / td > < td > Accepted< / td > < / tr >
< tr > < td > < strong > < a href = "architecture/adr/adr-005-extension-framework.html" > ADR-005< / a > < / strong > < / td > < td > Extension Framework< / td > < td > Accepted< / td > < / tr >
< tr > < td > < strong > < a href = "architecture/adr/adr-006-provisioning-cli-refactoring.html" > ADR-006< / a > < / strong > < / td > < td > CLI Refactoring< / td > < td > Accepted< / td > < / tr >
2025-12-11 21:50:42 +00:00
< / tbody > < / table >
< / div >
< h3 id = "-api-documentation" > < a class = "header" href = "#-api-documentation" > 🔌 API Documentation< / a > < / h3 >
< div class = "table-wrapper" > < table > < thead > < tr > < th > Document< / th > < th > Description< / th > < / tr > < / thead > < tbody >
2026-01-08 09:55:37 +00:00
< tr > < td > < strong > < a href = "api-reference/rest-api.html" > REST API< / a > < / strong > < / td > < td > HTTP API endpoints< / td > < / tr >
< tr > < td > < strong > < a href = "api-reference/websocket.html" > WebSocket API< / a > < / strong > < / td > < td > Real-time event streams< / td > < / tr >
< tr > < td > < strong > < a href = "development/extensions.html" > Extensions API< / a > < / strong > < / td > < td > Extension integration APIs< / td > < / tr >
< tr > < td > < strong > < a href = "api-reference/sdks.html" > SDKs< / a > < / strong > < / td > < td > Client libraries< / td > < / tr >
< tr > < td > < strong > < a href = "api-reference/integration-examples.html" > Integration Examples< / a > < / strong > < / td > < td > API usage examples< / td > < / tr >
2025-12-11 21:50:42 +00:00
< / tbody > < / table >
< / div >
< h3 id = "-development" > < a class = "header" href = "#-development" > 🛠️ Development< / a > < / h3 >
< div class = "table-wrapper" > < table > < thead > < tr > < th > Document< / th > < th > Description< / th > < / tr > < / thead > < tbody >
< tr > < td > < strong > < a href = "development/README.html" > Development README< / a > < / strong > < / td > < td > Developer overview< / td > < / tr >
< tr > < td > < strong > < a href = "development/implementation-guide.html" > Implementation Guide< / a > < / strong > < / td > < td > Implementation details< / td > < / tr >
2026-01-08 09:55:37 +00:00
< tr > < td > < strong > < a href = "development/quick-provider-guide.html" > Provider Development< / a > < / strong > < / td > < td > Create cloud providers< / td > < / tr >
< tr > < td > < strong > < a href = "development/taskserv-developer-guide.html" > Taskserv Development< / a > < / strong > < / td > < td > Create task services< / td > < / tr >
2025-12-11 21:50:42 +00:00
< tr > < td > < strong > < a href = "development/extensions.html" > Extension Framework< / a > < / strong > < / td > < td > Extension system< / td > < / tr >
2026-01-08 09:55:37 +00:00
< tr > < td > < strong > < a href = "development/command-handler-guide.html" > Command Handlers< / a > < / strong > < / td > < td > CLI command development< / td > < / tr >
2025-12-11 21:50:42 +00:00
< / tbody > < / table >
< / div >
< h3 id = "-troubleshooting" > < a class = "header" href = "#-troubleshooting" > 🐛 Troubleshooting< / a > < / h3 >
< div class = "table-wrapper" > < table > < thead > < tr > < th > Document< / th > < th > Description< / th > < / tr > < / thead > < tbody >
2026-01-08 09:55:37 +00:00
< tr > < td > < strong > < a href = "troubleshooting/troubleshooting-guide.html" > Troubleshooting Guide< / a > < / strong > < / td > < td > Common issues and solutions< / td > < / tr >
2025-12-11 21:50:42 +00:00
< / tbody > < / table >
< / div >
< h3 id = "-how-to-guides" > < a class = "header" href = "#-how-to-guides" > 📖 How-To Guides< / a > < / h3 >
< div class = "table-wrapper" > < table > < thead > < tr > < th > Document< / th > < th > Description< / th > < / tr > < / thead > < tbody >
< tr > < td > < strong > < a href = "guides/from-scratch.html" > From Scratch< / a > < / strong > < / td > < td > Complete deployment from zero< / td > < / tr >
< tr > < td > < strong > < a href = "guides/update-infrastructure.html" > Update Infrastructure< / a > < / strong > < / td > < td > Safe update procedures< / td > < / tr >
< tr > < td > < strong > < a href = "guides/customize-infrastructure.html" > Customize Infrastructure< / a > < / strong > < / td > < td > Layer and template customization< / td > < / tr >
< / tbody > < / table >
< / div >
< h3 id = "-configuration" > < a class = "header" href = "#-configuration" > 🔐 Configuration< / a > < / h3 >
< div class = "table-wrapper" > < table > < thead > < tr > < th > Document< / th > < th > Description< / th > < / tr > < / thead > < tbody >
< tr > < td > < strong > < a href = "configuration/workspace-config-architecture.html" > Workspace Config Architecture< / a > < / strong > < / td > < td > Configuration architecture< / td > < / tr >
< / tbody > < / table >
< / div >
< h3 id = "-quick-references" > < a class = "header" href = "#-quick-references" > 📦 Quick References< / a > < / h3 >
< div class = "table-wrapper" > < table > < thead > < tr > < th > Document< / th > < th > Description< / th > < / tr > < / thead > < tbody >
2026-01-08 09:55:37 +00:00
< tr > < td > < strong > < a href = "getting-started/quickstart-cheatsheet.html" > Quickstart Cheatsheet< / a > < / strong > < / td > < td > Command shortcuts< / td > < / tr >
< tr > < td > < strong > < a href = "quick-reference/oci.html" > OCI Quick Reference< / a > < / strong > < / td > < td > OCI operations< / td > < / tr >
2025-12-11 21:50:42 +00:00
< / tbody > < / table >
< / div >
< hr / >
< h2 id = "documentation-structure" > < a class = "header" href = "#documentation-structure" > Documentation Structure< / a > < / h2 >
2026-01-08 09:55:37 +00:00
< pre > < code class = "language-plaintext" > provisioning/docs/src/
2025-12-11 21:50:42 +00:00
├── README.md (this file) # Documentation hub
2026-01-08 09:55:37 +00:00
├── getting-started/ # Getting started guides
│ ├── installation-guide.md
│ ├── getting-started.md
│ └── quickstart-cheatsheet.md
2025-12-11 21:50:42 +00:00
├── architecture/ # System architecture
2026-01-08 09:55:37 +00:00
│ ├── adr/ # Architecture Decision Records
2025-12-11 21:50:42 +00:00
│ ├── design-principles.md
│ ├── integration-patterns.md
2026-01-08 09:55:37 +00:00
│ ├── system-overview.md
│ └── ... (and 10+ more architecture docs)
├── infrastructure/ # Infrastructure guides
2025-12-11 21:50:42 +00:00
│ ├── cli-reference.md
2026-01-08 09:55:37 +00:00
│ ├── workspace-setup.md
│ ├── workspace-switching-guide.md
│ └── infrastructure-management.md
├── api-reference/ # API documentation
2025-12-11 21:50:42 +00:00
│ ├── rest-api.md
│ ├── websocket.md
2026-01-08 09:55:37 +00:00
│ ├── integration-examples.md
│ └── sdks.md
2025-12-11 21:50:42 +00:00
├── development/ # Developer guides
│ ├── README.md
│ ├── implementation-guide.md
2026-01-08 09:55:37 +00:00
│ ├── quick-provider-guide.md
│ ├── taskserv-developer-guide.md
│ └── ... (15+ more developer docs)
2025-12-11 21:50:42 +00:00
├── guides/ # How-to guides
│ ├── from-scratch.md
│ ├── update-infrastructure.md
│ └── customize-infrastructure.md
2026-01-08 09:55:37 +00:00
├── operations/ # Operations guides
│ ├── service-management-guide.md
│ ├── coredns-guide.md
│ └── ... (more operations docs)
├── security/ # Security docs
├── integration/ # Integration guides
├── testing/ # Testing docs
2025-12-11 21:50:42 +00:00
├── configuration/ # Configuration docs
2026-01-08 09:55:37 +00:00
├── troubleshooting/ # Troubleshooting guides
└── quick-reference/ # Quick references
```plaintext
---
## Key Concepts
### Infrastructure as Code (IaC)
The provisioning platform uses **declarative configuration** to manage infrastructure. Instead of manually creating resources, you define what you want in Nickel configuration files, and the system makes it happen.
### Mode-Based Architecture
The system supports four operational modes:
- **Solo**: Single developer local development
- **Multi-user**: Team collaboration with shared services
- **CI/CD**: Automated pipeline execution
- **Enterprise**: Production deployment with strict compliance
### Extension System
Extensibility through:
- **Providers**: Cloud platform integrations (AWS, UpCloud, Local)
- **Task Services**: Infrastructure components (Kubernetes, databases, etc.)
- **Clusters**: Complete deployment configurations
### OCI-Native Distribution
Extensions and packages distributed as OCI artifacts, enabling:
- Industry-standard packaging
- Efficient caching and bandwidth
- Version pinning and rollback
- Air-gapped deployments
---
## Documentation by Role
### For New Users
1. Start with **[Installation Guide](getting-started/installation-guide.md)**
2. Read **[Getting Started](getting-started/getting-started.md)**
3. Follow **[From Scratch Guide](guides/from-scratch.md)**
4. Reference **[Quickstart Cheatsheet](guides/quickstart-cheatsheet.md)**
### For Developers
1. Review **[System Overview](architecture/system-overview.md)**
2. Study **[Design Principles](architecture/design-principles.md)**
3. Read relevant **[ADRs](architecture/)**
4. Follow **[Development Guide](development/README.md)**
5. Reference **KCL Quick Reference**
### For Operators
1. Understand **[Mode System](infrastructure/mode-system)**
2. Learn **[Service Management](operations/service-management-guide.md)**
3. Review **[Infrastructure Management](infrastructure/infrastructure-management.md)**
4. Study **[OCI Registry](integration/oci-registry-guide.md)**
### For Architects
1. Read **[System Overview](architecture/system-overview.md)**
2. Study all **[ADRs](architecture/)**
3. Review **[Integration Patterns](architecture/integration-patterns.md)**
4. Understand **[Multi-Repo Architecture](architecture/multi-repo-architecture.md)**
---
## System Capabilities
### ✅ Infrastructure Automation
- Multi-cloud support (AWS, UpCloud, Local)
- Declarative configuration with KCL
- Automated dependency resolution
- Batch operations with rollback
### ✅ Workflow Orchestration
- Hybrid Rust/Nushell orchestration
- Checkpoint-based recovery
- Parallel execution with limits
- Real-time monitoring
### ✅ Test Environments
- Containerized testing
- Multi-node cluster simulation
- Topology templates
- Automated cleanup
### ✅ Mode-Based Operation
- Solo: Local development
- Multi-user: Team collaboration
- CI/CD: Automated pipelines
- Enterprise: Production deployment
### ✅ Extension Management
- OCI-native distribution
- Automatic dependency resolution
- Version management
- Local and remote sources
---
## Key Achievements
### 🚀 Batch Workflow System (v3.1.0)
- Provider-agnostic batch operations
- Mixed provider support (UpCloud + AWS + local)
- Dependency resolution with soft/hard dependencies
- Real-time monitoring and rollback
### 🏗️ Hybrid Orchestrator (v3.0.0)
- Solves Nushell deep call stack limitations
- Preserves all business logic
- REST API for external integration
- Checkpoint-based state management
### ⚙️ Configuration System (v2.0.0)
- Migrated from ENV to config-driven
- Hierarchical configuration loading
- Variable interpolation
- True IaC without hardcoded fallbacks
### 🎯 Modular CLI (v3.2.0)
- 84% reduction in main file size
- Domain-driven handlers
- 80+ shortcuts
- Bi-directional help system
### 🧪 Test Environment Service (v3.4.0)
- Automated containerized testing
- Multi-node cluster topologies
- CI/CD integration ready
- Template-based configurations
### 🔄 Workspace Switching (v2.0.5)
- Centralized workspace management
- Single-command workspace switching
- Active workspace tracking
- User preference system
---
## Technology Stack
| Component | Technology | Purpose |
|-----------|------------|---------|
| **Core CLI** | Nushell 0.107.1 | Shell and scripting |
| **Configuration** | KCL 0.11.2 | Type-safe IaC |
| **Orchestrator** | Rust | High-performance coordination |
| **Templates** | Jinja2 (nu_plugin_tera) | Code generation |
| **Secrets** | SOPS 3.10.2 + Age 1.2.1 | Encryption |
| **Distribution** | OCI (skopeo/crane/oras) | Artifact management |
---
## Support
### Getting Help
- **Documentation**: You're reading it!
- **Quick Reference**: Run `provisioning sc` or `provisioning guide quickstart`
- **Help System**: Run `provisioning help` or `provisioning < command> help`
- **Interactive Shell**: Run `provisioning nu` for Nushell REPL
### Reporting Issues
- Check **[Troubleshooting Guide](infrastructure/troubleshooting-guide.md)**
- Review **[FAQ](troubleshooting/troubleshooting-guide.md)**
- Enable debug mode: `provisioning --debug < command> `
- Check logs: `provisioning platform logs < service> `
---
## Contributing
This project welcomes contributions! See **[Development Guide](development/README.md)** for:
- Development setup
- Code style guidelines
- Testing requirements
- Pull request process
---
## License
[Add license information]
---
## Version History
| Version | Date | Major Changes |
|---------|------|---------------|
| **3.5.0** | 2025-10-06 | Mode system, OCI registry, comprehensive documentation |
| **3.4.0** | 2025-10-06 | Test environment service |
| **3.3.0** | 2025-09-30 | Interactive guides system |
| **3.2.0** | 2025-09-30 | Modular CLI refactoring |
| **3.1.0** | 2025-09-25 | Batch workflow system |
| **3.0.0** | 2025-09-25 | Hybrid orchestrator architecture |
| **2.0.5** | 2025-10-02 | Workspace switching system |
| **2.0.0** | 2025-09-23 | Configuration system migration |
---
**Maintained By**: Provisioning Team
**Last Review**: 2025-10-06
**Next Review**: 2026-01-06
2025-12-11 21:50:42 +00:00
< / code > < / pre >
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
2026-01-08 09:55:37 +00:00
< a rel = "next prefetch" href = "getting-started/installation-guide.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-right" > < / i >
< / a >
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
2026-01-08 09:55:37 +00:00
< a rel = "next prefetch" href = "getting-started/installation-guide.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-right" > < / i >
< / a >
< / nav >
< / div >
< script >
window.playground_copyable = true;
< / script >
< script src = "elasticlunr.min.js" > < / script >
< script src = "mark.min.js" > < / script >
< script src = "searcher.js" > < / script >
< script src = "clipboard.min.js" > < / script >
< script src = "highlight.js" > < / script >
< script src = "book.js" > < / script >
<!-- Custom JS scripts -->
< / div >
< / body >
< / html >
