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.

🚀 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

Start with Installation Guide
Read Getting Started
Follow From Scratch Guide
Reference Quickstart Cheatsheet

For Developers

Review System Overview
Study Design Principles
Read relevant ADRs
Follow Development Guide
Reference Nickel Quick Reference

For Operators

Understand Mode System
Learn Service Management
Review Infrastructure Management
Study OCI Registry

For Architects

Read System Overview
Study all ADRs
Review Integration Patterns
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

README.md

Provisioning Platform Documentation

Quick Navigation