Provisioning Logo

Provisioning

# Provisioning Platform Documentation **Last Updated**: 2025-01-02 (Phase 3.A Cleanup Complete) **Status**: โœ… Primary documentation source (145 files consolidated) Welcome to the comprehensive documentation for the Provisioning Platform - a modern, cloud-native infrastructure automation system built with Nushell, Nickel, and Rust. > **Note**: Architecture Decision Records (ADRs) and design documentation are in `docs/` > directory. This location contains user-facing, operational, and product documentation. --- ## Quick Navigation ### ๐Ÿš€ Getting Started | Document | Description | Audience | | ---------- | ------------- | ---------- | | **[Installation Guide](getting-started/installation-guide.md)** | Install and configure the system | New Users | | **[Getting Started](getting-started/getting-started.md)** | First steps and basic concepts | New Users | | **[Quick Reference](getting-started/quickstart-cheatsheet.md)** | Command cheat sheet | All Users | | **[From Scratch Guide](guides/from-scratch.md)** | Complete deployment walkthrough | New Users | ### ๐Ÿ“š User Guides | Document | Description | | ---------- | ------------- | | **[CLI Reference](infrastructure/cli-reference.md)** | Complete command reference | | **[Workspace Management](infrastructure/workspace-setup.md)** | Workspace creation and management | | **[Workspace Switching](infrastructure/workspace-switching-guide.md)** | Switch between workspaces | | **[Infrastructure Management](infrastructure/infrastructure-management.md)** | Server, taskserv, cluster operations | | **[Service Management](operations/service-management-guide.md)** | Platform service lifecycle management | | **[OCI Registry](integration/oci-registry-guide.md)** | OCI artifact management | | **[Gitea Integration](integration/gitea-integration-guide.md)** | Git workflow and collaboration | | **[CoreDNS Guide](operations/coredns-guide.md)** | DNS management | | **[Test Environments](testing/test-environment-usage.md)** | Containerized testing | | **[Extension Development](development/extension-development.md)** | Create custom extensions | ### ๐Ÿ—๏ธ Architecture | Document | Description | | ---------- | ------------- | | **[System Overview](architecture/system-overview.md)** | High-level architecture | | **[Multi-Repo Architecture](architecture/multi-repo-architecture.md)** | Repository structure and OCI distribution | | **[Design Principles](architecture/design-principles.md)** | Architectural philosophy | | **[Integration Patterns](architecture/integration-patterns.md)** | System integration patterns | | **[Orchestrator Model](architecture/orchestrator-integration-model.md)** | Hybrid orchestration architecture | ### ๐Ÿ“‹ Architecture Decision Records (ADRs) | ADR | Title | Status | | ----- | ------- | -------- | | **[ADR-001](architecture/adr/adr-001-project-structure.md)** | Project Structure Decision | Accepted | | **[ADR-002](architecture/adr/adr-002-distribution-strategy.md)** | Distribution Strategy | Accepted | | **[ADR-003](architecture/adr/adr-003-workspace-isolation.md)** | Workspace Isolation | Accepted | | **[ADR-004](architecture/adr/adr-004-hybrid-architecture.md)** | Hybrid Architecture | Accepted | | **[ADR-005](architecture/adr/adr-005-extension-framework.md)** | Extension Framework | Accepted | | **[ADR-006](architecture/adr/adr-006-provisioning-cli-refactoring.md)** | CLI Refactoring | Accepted | ### ๐Ÿ”Œ API Documentation | Document | Description | | ---------- | ------------- | | **[REST API](api-reference/rest-api.md)** | HTTP API endpoints | | **[WebSocket API](api-reference/websocket.md)** | Real-time event streams | | **[Extensions API](development/extensions.md)** | Extension integration APIs | | **[SDKs](api-reference/sdks.md)** | Client libraries | | **[Integration Examples](api-reference/integration-examples.md)** | API usage examples | ### ๐Ÿ› ๏ธ Development | Document | Description | | ---------- | ------------- | | **[Development README](development/README.md)** | Developer overview | | **[Implementation Guide](development/implementation-guide.md)** | Implementation details | | **[Provider Development](development/quick-provider-guide.md)** | Create cloud providers | | **[Taskserv Development](development/taskserv-developer-guide.md)** | Create task services | | **[Extension Framework](development/extensions.md)** | Extension system | | **[Command Handlers](development/command-handler-guide.md)** | CLI command development | ### ๐Ÿ› Troubleshooting | Document | Description | | ---------- | ------------- | | **[Troubleshooting Guide](troubleshooting/troubleshooting-guide.md)** | Common issues and solutions | ### ๐Ÿ“– How-To Guides | Document | Description | | ---------- | ------------- | | **[From Scratch](guides/from-scratch.md)** | Complete deployment from zero | | **[Update Infrastructure](guides/update-infrastructure.md)** | Safe update procedures | | **[Customize Infrastructure](guides/customize-infrastructure.md)** | Layer and template customization | ### ๐Ÿ” Configuration | Document | Description | | ---------- | ------------- | | **[Workspace Config Architecture](configuration/workspace-config-architecture.md)** | Configuration architecture | ### ๐Ÿ“ฆ Quick References | Document | Description | | ---------- | ------------- | | **[Quickstart Cheatsheet](getting-started/quickstart-cheatsheet.md)** | Command shortcuts | | **[OCI Quick Reference](quick-reference/oci.md)** | OCI operations | --- ## Documentation Structure ```text provisioning/docs/src/ โ”œโ”€โ”€ README.md (this file) # Documentation hub โ”œโ”€โ”€ getting-started/ # Getting started guides โ”‚ โ”œโ”€โ”€ installation-guide.md โ”‚ โ”œโ”€โ”€ getting-started.md โ”‚ โ””โ”€โ”€ quickstart-cheatsheet.md โ”œโ”€โ”€ architecture/ # System architecture โ”‚ โ”œโ”€โ”€ adr/ # Architecture Decision Records โ”‚ โ”œโ”€โ”€ design-principles.md โ”‚ โ”œโ”€โ”€ integration-patterns.md โ”‚ โ”œโ”€โ”€ system-overview.md โ”‚ โ””โ”€โ”€ ... (and 10+ more architecture docs) โ”œโ”€โ”€ infrastructure/ # Infrastructure guides โ”‚ โ”œโ”€โ”€ cli-reference.md โ”‚ โ”œโ”€โ”€ workspace-setup.md โ”‚ โ”œโ”€โ”€ workspace-switching-guide.md โ”‚ โ””โ”€โ”€ infrastructure-management.md โ”œโ”€โ”€ api-reference/ # API documentation โ”‚ โ”œโ”€โ”€ rest-api.md โ”‚ โ”œโ”€โ”€ websocket.md โ”‚ โ”œโ”€โ”€ integration-examples.md โ”‚ โ””โ”€โ”€ sdks.md โ”œโ”€โ”€ development/ # Developer guides โ”‚ โ”œโ”€โ”€ README.md โ”‚ โ”œโ”€โ”€ implementation-guide.md โ”‚ โ”œโ”€โ”€ quick-provider-guide.md โ”‚ โ”œโ”€โ”€ taskserv-developer-guide.md โ”‚ โ””โ”€โ”€ ... (15+ more developer docs) โ”œโ”€โ”€ guides/ # How-to guides โ”‚ โ”œโ”€โ”€ from-scratch.md โ”‚ โ”œโ”€โ”€ update-infrastructure.md โ”‚ โ””โ”€โ”€ customize-infrastructure.md โ”œโ”€โ”€ operations/ # Operations guides โ”‚ โ”œโ”€โ”€ service-management-guide.md โ”‚ โ”œโ”€โ”€ coredns-guide.md โ”‚ โ””โ”€โ”€ ... (more operations docs) โ”œโ”€โ”€ security/ # Security docs โ”œโ”€โ”€ integration/ # Integration guides โ”œโ”€โ”€ testing/ # Testing docs โ”œโ”€โ”€ configuration/ # Configuration docs โ”œโ”€โ”€ troubleshooting/ # Troubleshooting guides โ””โ”€โ”€ quick-reference/ # Quick references ``` --- ## 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 **Nickel 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 Nickel - 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** | Nickel 1.0.0+ | 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 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 ` - Check logs: `provisioning platform logs ` --- ## 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