jesus/provisioning
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
provisioning/docs/src/README.md
Jesús Pérez a4b3c02371
chore: fix docs after fences fix
2026-01-14 04:53:21 +00:00

13 KiB
Raw Blame History

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 Install and configure the system New Users
Getting Started First steps and basic concepts New Users
Quick Reference Command cheat sheet All Users
From Scratch Guide Complete deployment walkthrough New Users

📚 User Guides

Document Description
CLI Reference Complete command reference
Workspace Management Workspace creation and management
Workspace Switching Switch between workspaces
Infrastructure Management Server, taskserv, cluster operations
Service Management Platform service lifecycle management
OCI Registry OCI artifact management
Gitea Integration Git workflow and collaboration
CoreDNS Guide DNS management
Test Environments Containerized testing
Extension Development Create custom extensions

🏗️ Architecture

Document Description
System Overview High-level architecture
Multi-Repo Architecture Repository structure and OCI distribution
Design Principles Architectural philosophy
Integration Patterns System integration patterns
Orchestrator Model Hybrid orchestration architecture

📋 Architecture Decision Records (ADRs)

ADR Title Status
ADR-001 Project Structure Decision Accepted
ADR-002 Distribution Strategy Accepted
ADR-003 Workspace Isolation Accepted
ADR-004 Hybrid Architecture Accepted
ADR-005 Extension Framework Accepted
ADR-006 CLI Refactoring Accepted

🔌 API Documentation

Document Description
REST API HTTP API endpoints
WebSocket API Real-time event streams
Extensions API Extension integration APIs
SDKs Client libraries
Integration Examples API usage examples

🛠️ Development

Document Description
Development README Developer overview
Implementation Guide Implementation details
Provider Development Create cloud providers
Taskserv Development Create task services
Extension Framework Extension system
Command Handlers CLI command development

🐛 Troubleshooting

Document Description
Troubleshooting Guide Common issues and solutions

📖 How-To Guides

Document Description
From Scratch Complete deployment from zero
Update Infrastructure Safe update procedures
Customize Infrastructure Layer and template customization

🔐 Configuration

Document Description
Workspace Config Architecture Configuration architecture

📦 Quick References

Document Description
Quickstart Cheatsheet Command shortcuts
OCI Quick Reference OCI operations

Documentation Structure

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
  2. Read Getting Started
  3. Follow From Scratch Guide
  4. Reference Quickstart Cheatsheet

For Developers

  1. Review System Overview
  2. Study Design Principles
  3. Read relevant ADRs
  4. Follow Development Guide
  5. Reference Nickel Quick Reference

For Operators

  1. Understand Mode System
  2. Learn Service Management
  3. Review Infrastructure Management
  4. Study OCI Registry

For Architects

  1. Read System Overview
  2. Study all ADRs
  3. Review Integration Patterns
  4. Understand Multi-Repo Architecture

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 <command> help
  • Interactive Shell: Run provisioning nu for Nushell REPL

Reporting Issues

  • Check Troubleshooting Guide
  • Review FAQ
  • Enable debug mode: provisioning --debug <command>
  • Check logs: provisioning platform logs <service>

Contributing

This project welcomes contributions! See Development Guide 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