diff --git a/docs/src/README.md.bak2 b/docs/src/README.md.bak2 deleted file mode 100644 index 593c649..0000000 --- a/docs/src/README.md.bak2 +++ /dev/null @@ -1,385 +0,0 @@ -

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