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" >
< title > Distribution Process - Provisioning Platform Documentation< / title >
<!-- 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/development/distribution-process.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 >
< h1 id = "distribution-process-documentation" > < a class = "header" href = "#distribution-process-documentation" > Distribution Process Documentation< / a > < / h1 >
< p > This document provides comprehensive documentation for the provisioning project’ < / p >
< h2 id = "table-of-contents" > < a class = "header" href = "#table-of-contents" > Table of Contents< / a > < / h2 >
< ol >
< li > < a href = "#overview" > Overview< / a > < / li >
< li > < a href = "#distribution-architecture" > Distribution Architecture< / a > < / li >
< li > < a href = "#release-process" > Release Process< / a > < / li >
< li > < a href = "#package-generation" > Package Generation< / a > < / li >
< li > < a href = "#multi-platform-distribution" > Multi-Platform Distribution< / a > < / li >
< li > < a href = "#validation-and-testing" > Validation and Testing< / a > < / li >
< li > < a href = "#release-management" > Release Management< / a > < / li >
< li > < a href = "#rollback-procedures" > Rollback Procedures< / a > < / li >
< li > < a href = "#cicd-integration" > CI/CD Integration< / a > < / li >
< li > < a href = "#troubleshooting" > Troubleshooting< / a > < / li >
< / ol >
< h2 id = "overview" > < a class = "header" href = "#overview" > Overview< / a > < / h2 >
< p > The distribution system provides a comprehensive solution for creating, packaging, and distributing provisioning across multiple platforms with automated release management.< / p >
< p > < strong > Key Features< / strong > :< / p >
< ul >
< li > < strong > Multi-Platform Support< / strong > : Linux, macOS, Windows with multiple architectures< / li >
< li > < strong > Multiple Distribution Variants< / strong > : Complete and minimal distributions< / li >
< li > < strong > Automated Release Pipeline< / strong > : From development to production deployment< / li >
< li > < strong > Package Management< / strong > : Binary packages, container images, and installers< / li >
< li > < strong > Validation Framework< / strong > : Comprehensive testing and validation< / li >
< li > < strong > Rollback Capabilities< / strong > : Safe rollback and recovery procedures< / li >
< / ul >
< p > < strong > Location< / strong > : < code > /src/tools/< / code >
< strong > Main Tool< / strong > : < code > /src/tools/Makefile< / code > and associated Nushell scripts< / p >
< h2 id = "distribution-architecture" > < a class = "header" href = "#distribution-architecture" > Distribution Architecture< / a > < / h2 >
< h3 id = "distribution-components" > < a class = "header" href = "#distribution-components" > Distribution Components< / a > < / h3 >
2026-01-08 09:55:37 +00:00
< pre > < code class = "language-plaintext" > Distribution Ecosystem
2025-12-11 21:50:42 +00:00
├── Core Components
│ ├── Platform Binaries # Rust-compiled binaries
│ ├── Core Libraries # Nushell libraries and CLI
│ ├── Configuration System # TOML configuration files
│ └── Documentation # User and API documentation
├── Platform Packages
│ ├── Archives # TAR.GZ and ZIP files
│ ├── Installers # Platform-specific installers
│ └── Container Images # Docker/OCI images
├── Distribution Variants
│ ├── Complete # Full-featured distribution
│ └── Minimal # Lightweight distribution
└── Release Artifacts
├── Checksums # SHA256/MD5 verification
├── Signatures # Digital signatures
└── Metadata # Release information
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "build-pipeline" > < a class = "header" href = "#build-pipeline" > Build Pipeline< / a > < / h3 >
< pre > < code class = "language-plaintext" > Build Pipeline Flow
2025-12-11 21:50:42 +00:00
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Source Code │ -> │ Build Stage │ -> │ Package Stage │
│ │ │ │ │ │
│ - Rust code │ │ - compile- │ │ - create- │
│ - Nushell libs │ │ platform │ │ archives │
2026-01-12 04:42:18 +00:00
│ - Nickel schemas│ │ - bundle-core │ │ - build- │
│ - Config files │ │ - validate-nickel│ │ containers │
2025-12-11 21:50:42 +00:00
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
v
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Release Stage │ < - │ Validate Stage │ < - │ Distribute Stage│
│ │ │ │ │ │
│ - create- │ │ - test-dist │ │ - generate- │
│ release │ │ - validate- │ │ distribution │
│ - upload- │ │ package │ │ - create- │
│ artifacts │ │ - integration │ │ installers │
└─────────────────┘ └─────────────────┘ └─────────────────┘
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "distribution-variants" > < a class = "header" href = "#distribution-variants" > Distribution Variants< / a > < / h3 >
< p > < strong > Complete Distribution< / strong > :< / p >
< ul >
< li > All Rust binaries (orchestrator, control-center, MCP server)< / li >
< li > Full Nushell library suite< / li >
< li > All providers, taskservs, and clusters< / li >
< li > Complete documentation and examples< / li >
< li > Development tools and templates< / li >
< / ul >
< p > < strong > Minimal Distribution< / strong > :< / p >
< ul >
< li > Essential binaries only< / li >
< li > Core Nushell libraries< / li >
< li > Basic provider support< / li >
< li > Essential task services< / li >
< li > Minimal documentation< / li >
< / ul >
< h2 id = "release-process" > < a class = "header" href = "#release-process" > Release Process< / a > < / h2 >
< h3 id = "release-types" > < a class = "header" href = "#release-types" > Release Types< / a > < / h3 >
< p > < strong > Release Classifications< / strong > :< / p >
< ul >
< li > < strong > Major Release< / strong > (x.0.0): Breaking changes, new major features< / li >
< li > < strong > Minor Release< / strong > (x.y.0): New features, backward compatible< / li >
< li > < strong > Patch Release< / strong > (x.y.z): Bug fixes, security updates< / li >
< li > < strong > Pre-Release< / strong > (x.y.z-alpha/beta/rc): Development/testing releases< / li >
< / ul >
< h3 id = "step-by-step-release-process" > < a class = "header" href = "#step-by-step-release-process" > Step-by-Step Release Process< / a > < / h3 >
< h4 id = "1-preparation-phase" > < a class = "header" href = "#1-preparation-phase" > 1. Preparation Phase< / a > < / h4 >
< p > < strong > Pre-Release Checklist< / strong > :< / p >
< pre > < code class = "language-bash" > # Update dependencies and security
2025-12-11 21:50:42 +00:00
cargo update
cargo audit
# Run comprehensive tests
make ci-test
# Update documentation
make docs
# Validate all configurations
make validate-all
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Version Planning< / strong > :< / p >
< pre > < code class = "language-bash" > # Check current version
2025-12-11 21:50:42 +00:00
git describe --tags --always
# Plan next version
make status | grep Version
# Validate version bump
nu src/tools/release/create-release.nu --dry-run --version 2.1.0
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h4 id = "2-build-phase" > < a class = "header" href = "#2-build-phase" > 2. Build Phase< / a > < / h4 >
< p > < strong > Complete Build< / strong > :< / p >
< pre > < code class = "language-bash" > # Clean build environment
2025-12-11 21:50:42 +00:00
make clean
# Build all platforms and variants
make all
# Validate build output
make test-dist
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Build with Specific Parameters< / strong > :< / p >
< pre > < code class = "language-bash" > # Build for specific platforms
2025-12-11 21:50:42 +00:00
make all PLATFORMS=linux-amd64,macos-amd64 VARIANTS=complete
# Build with custom version
make all VERSION=2.1.0-rc1
# Parallel build for speed
make all PARALLEL=true
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h4 id = "3-package-generation" > < a class = "header" href = "#3-package-generation" > 3. Package Generation< / a > < / h4 >
< p > < strong > Create Distribution Packages< / strong > :< / p >
< pre > < code class = "language-bash" > # Generate complete distributions
2025-12-11 21:50:42 +00:00
make dist-generate
# Create binary packages
make package-binaries
# Build container images
make package-containers
# Create installers
make create-installers
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Package Validation< / strong > :< / p >
< pre > < code class = "language-bash" > # Validate packages
2025-12-11 21:50:42 +00:00
make test-dist
# Check package contents
nu src/tools/package/validate-package.nu packages/
# Test installation
make install
make uninstall
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h4 id = "4-release-creation" > < a class = "header" href = "#4-release-creation" > 4. Release Creation< / a > < / h4 >
< p > < strong > Automated Release< / strong > :< / p >
< pre > < code class = "language-bash" > # Create complete release
2025-12-11 21:50:42 +00:00
make release VERSION=2.1.0
# Create draft release for review
make release-draft VERSION=2.1.0
# Manual release creation
nu src/tools/release/create-release.nu \
--version 2.1.0 \
--generate-changelog \
--push-tag \
--auto-upload
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Release Options< / strong > :< / p >
< ul >
< li > < code > --pre-release< / code > : Mark as pre-release< / li >
< li > < code > --draft< / code > : Create draft release< / li >
< li > < code > --generate-changelog< / code > : Auto-generate changelog from commits< / li >
< li > < code > --push-tag< / code > : Push git tag to remote< / li >
< li > < code > --auto-upload< / code > : Upload assets automatically< / li >
< / ul >
< h4 id = "5-distribution-and-notification" > < a class = "header" href = "#5-distribution-and-notification" > 5. Distribution and Notification< / a > < / h4 >
< p > < strong > Upload Artifacts< / strong > :< / p >
< pre > < code class = "language-bash" > # Upload to GitHub Releases
2025-12-11 21:50:42 +00:00
make upload-artifacts
# Update package registries
make update-registry
# Send notifications
make notify-release
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Registry Updates< / strong > :< / p >
< pre > < code class = "language-bash" > # Update Homebrew formula
2025-12-11 21:50:42 +00:00
nu src/tools/release/update-registry.nu \
--registries homebrew \
--version 2.1.0 \
--auto-commit
# Custom registry updates
nu src/tools/release/update-registry.nu \
--registries custom \
--registry-url https://packages.company.com \
--credentials-file ~/.registry-creds
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "release-automation" > < a class = "header" href = "#release-automation" > Release Automation< / a > < / h3 >
< p > < strong > Complete Automated Release< / strong > :< / p >
< pre > < code class = "language-bash" > # Full release pipeline
2025-12-11 21:50:42 +00:00
make cd-deploy VERSION=2.1.0
# Equivalent manual steps:
make clean
make all VERSION=2.1.0
make create-archives
make create-installers
make release VERSION=2.1.0
make upload-artifacts
make update-registry
make notify-release
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h2 id = "package-generation" > < a class = "header" href = "#package-generation" > Package Generation< / a > < / h2 >
< h3 id = "binary-packages" > < a class = "header" href = "#binary-packages" > Binary Packages< / a > < / h3 >
< p > < strong > Package Types< / strong > :< / p >
< ul >
< li > < strong > Standalone Archives< / strong > : TAR.GZ and ZIP with all dependencies< / li >
< li > < strong > Platform Packages< / strong > : DEB, RPM, MSI, PKG with system integration< / li >
< li > < strong > Portable Packages< / strong > : Single-directory distributions< / li >
< li > < strong > Source Packages< / strong > : Source code with build instructions< / li >
< / ul >
< p > < strong > Create Binary Packages< / strong > :< / p >
< pre > < code class = "language-bash" > # Standard binary packages
2025-12-11 21:50:42 +00:00
make package-binaries
# Custom package creation
nu src/tools/package/package-binaries.nu \
--source-dir dist/platform \
--output-dir packages/binaries \
--platforms linux-amd64,macos-amd64 \
--format archive \
--compress \
--strip \
--checksum
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Package Features< / strong > :< / p >
< ul >
< li > < strong > Binary Stripping< / strong > : Removes debug symbols for smaller size< / li >
< li > < strong > Compression< / strong > : GZIP, LZMA, and Brotli compression< / li >
< li > < strong > Checksums< / strong > : SHA256 and MD5 verification< / li >
< li > < strong > Signatures< / strong > : GPG and code signing support< / li >
< / ul >
< h3 id = "container-images" > < a class = "header" href = "#container-images" > Container Images< / a > < / h3 >
< p > < strong > Container Build Process< / strong > :< / p >
< pre > < code class = "language-bash" > # Build container images
2025-12-11 21:50:42 +00:00
make package-containers
# Advanced container build
nu src/tools/package/build-containers.nu \
--dist-dir dist \
--tag-prefix provisioning \
--version 2.1.0 \
--platforms "linux/amd64,linux/arm64" \
--optimize-size \
--security-scan \
--multi-stage
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Container Features< / strong > :< / p >
< ul >
< li > < strong > Multi-Stage Builds< / strong > : Minimal runtime images< / li >
< li > < strong > Security Scanning< / strong > : Vulnerability detection< / li >
< li > < strong > Multi-Platform< / strong > : AMD64, ARM64 support< / li >
< li > < strong > Layer Optimization< / strong > : Efficient layer caching< / li >
< li > < strong > Runtime Configuration< / strong > : Environment-based configuration< / li >
< / ul >
< p > < strong > Container Registry Support< / strong > :< / p >
< ul >
< li > Docker Hub< / li >
< li > GitHub Container Registry< / li >
< li > Amazon ECR< / li >
< li > Google Container Registry< / li >
< li > Azure Container Registry< / li >
< li > Private registries< / li >
< / ul >
< h3 id = "installers" > < a class = "header" href = "#installers" > Installers< / a > < / h3 >
< p > < strong > Installer Types< / strong > :< / p >
< ul >
< li > < strong > Shell Script Installer< / strong > : Universal Unix/Linux installer< / li >
< li > < strong > Package Installers< / strong > : DEB, RPM, MSI, PKG< / li >
< li > < strong > Container Installer< / strong > : Docker/Podman setup< / li >
< li > < strong > Source Installer< / strong > : Build-from-source installer< / li >
< / ul >
< p > < strong > Create Installers< / strong > :< / p >
< pre > < code class = "language-bash" > # Generate all installer types
2025-12-11 21:50:42 +00:00
make create-installers
# Custom installer creation
nu src/tools/distribution/create-installer.nu \
dist/provisioning-2.1.0-linux-amd64-complete \
--output-dir packages/installers \
--installer-types shell,package \
--platforms linux,macos \
--include-services \
--create-uninstaller \
--validate-installer
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Installer Features< / strong > :< / p >
< ul >
< li > < strong > System Integration< / strong > : Systemd/Launchd service files< / li >
< li > < strong > Path Configuration< / strong > : Automatic PATH updates< / li >
< li > < strong > User/System Install< / strong > : Support for both user and system-wide installation< / li >
< li > < strong > Uninstaller< / strong > : Clean removal capability< / li >
< li > < strong > Dependency Management< / strong > : Automatic dependency resolution< / li >
< li > < strong > Configuration Setup< / strong > : Initial configuration creation< / li >
< / ul >
< h2 id = "multi-platform-distribution" > < a class = "header" href = "#multi-platform-distribution" > Multi-Platform Distribution< / a > < / h2 >
< h3 id = "supported-platforms" > < a class = "header" href = "#supported-platforms" > Supported Platforms< / a > < / h3 >
< p > < strong > Primary Platforms< / strong > :< / p >
< ul >
< li > < strong > Linux AMD64< / strong > (x86_64-unknown-linux-gnu)< / li >
< li > < strong > Linux ARM64< / strong > (aarch64-unknown-linux-gnu)< / li >
< li > < strong > macOS AMD64< / strong > (x86_64-apple-darwin)< / li >
< li > < strong > macOS ARM64< / strong > (aarch64-apple-darwin)< / li >
< li > < strong > Windows AMD64< / strong > (x86_64-pc-windows-gnu)< / li >
< li > < strong > FreeBSD AMD64< / strong > (x86_64-unknown-freebsd)< / li >
< / ul >
< p > < strong > Platform-Specific Features< / strong > :< / p >
< ul >
< li > < strong > Linux< / strong > : SystemD integration, package manager support< / li >
< li > < strong > macOS< / strong > : LaunchAgent services, Homebrew packages< / li >
< li > < strong > Windows< / strong > : Windows Service support, MSI installers< / li >
< li > < strong > FreeBSD< / strong > : RC scripts, pkg packages< / li >
< / ul >
< h3 id = "cross-platform-build" > < a class = "header" href = "#cross-platform-build" > Cross-Platform Build< / a > < / h3 >
< p > < strong > Cross-Compilation Setup< / strong > :< / p >
< pre > < code class = "language-bash" > # Install cross-compilation targets
2025-12-11 21:50:42 +00:00
rustup target add aarch64-unknown-linux-gnu
rustup target add x86_64-apple-darwin
rustup target add aarch64-apple-darwin
rustup target add x86_64-pc-windows-gnu
# Install cross-compilation tools
cargo install cross
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Platform-Specific Builds< / strong > :< / p >
< pre > < code class = "language-bash" > # Build for specific platform
2025-12-11 21:50:42 +00:00
make build-platform RUST_TARGET=aarch64-apple-darwin
# Build for multiple platforms
make build-cross PLATFORMS=linux-amd64,macos-arm64,windows-amd64
# Platform-specific distributions
make linux
make macos
make windows
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "distribution-matrix" > < a class = "header" href = "#distribution-matrix" > Distribution Matrix< / a > < / h3 >
< p > < strong > Generated Distributions< / strong > :< / p >
< pre > < code class = "language-plaintext" > Distribution Matrix:
2025-12-11 21:50:42 +00:00
provisioning-{version}-{platform}-{variant}.{format}
Examples:
- provisioning-2.1.0-linux-amd64-complete.tar.gz
- provisioning-2.1.0-macos-arm64-minimal.tar.gz
- provisioning-2.1.0-windows-amd64-complete.zip
- provisioning-2.1.0-freebsd-amd64-minimal.tar.xz
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Platform Considerations< / strong > :< / p >
< ul >
< li > < strong > File Permissions< / strong > : Executable permissions on Unix systems< / li >
< li > < strong > Path Separators< / strong > : Platform-specific path handling< / li >
< li > < strong > Service Integration< / strong > : Platform-specific service management< / li >
< li > < strong > Package Formats< / strong > : TAR.GZ for Unix, ZIP for Windows< / li >
< li > < strong > Line Endings< / strong > : CRLF for Windows, LF for Unix< / li >
< / ul >
< h2 id = "validation-and-testing" > < a class = "header" href = "#validation-and-testing" > Validation and Testing< / a > < / h2 >
< h3 id = "distribution-validation" > < a class = "header" href = "#distribution-validation" > Distribution Validation< / a > < / h3 >
< p > < strong > Validation Pipeline< / strong > :< / p >
< pre > < code class = "language-bash" > # Complete validation
2025-12-11 21:50:42 +00:00
make test-dist
# Custom validation
nu src/tools/build/test-distribution.nu \
--dist-dir dist \
--test-types basic,integration,complete \
--platform linux \
--cleanup \
--verbose
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Validation Types< / strong > :< / p >
< ul >
< li > < strong > Basic< / strong > : Installation test, CLI help, version check< / li >
< li > < strong > Integration< / strong > : Server creation, configuration validation< / li >
< li > < strong > Complete< / strong > : Full workflow testing including cluster operations< / li >
< / ul >
< h3 id = "testing-framework" > < a class = "header" href = "#testing-framework" > Testing Framework< / a > < / h3 >
< p > < strong > Test Categories< / strong > :< / p >
< ul >
< li > < strong > Unit Tests< / strong > : Component-specific testing< / li >
< li > < strong > Integration Tests< / strong > : Cross-component testing< / li >
< li > < strong > End-to-End Tests< / strong > : Complete workflow testing< / li >
< li > < strong > Performance Tests< / strong > : Load and performance validation< / li >
< li > < strong > Security Tests< / strong > : Security scanning and validation< / li >
< / ul >
< p > < strong > Test Execution< / strong > :< / p >
< pre > < code class = "language-bash" > # Run all tests
2025-12-11 21:50:42 +00:00
make ci-test
# Specific test types
nu src/tools/build/test-distribution.nu --test-types basic
nu src/tools/build/test-distribution.nu --test-types integration
nu src/tools/build/test-distribution.nu --test-types complete
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "package-validation" > < a class = "header" href = "#package-validation" > Package Validation< / a > < / h3 >
< p > < strong > Package Integrity< / strong > :< / p >
< pre > < code class = "language-bash" > # Validate package structure
2025-12-11 21:50:42 +00:00
nu src/tools/package/validate-package.nu dist/
# Check checksums
sha256sum -c packages/checksums.sha256
# Verify signatures
gpg --verify packages/provisioning-2.1.0.tar.gz.sig
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Installation Testing< / strong > :< / p >
< pre > < code class = "language-bash" > # Test installation process
2025-12-11 21:50:42 +00:00
./packages/installers/install-provisioning-2.1.0.sh --dry-run
# Test uninstallation
./packages/installers/uninstall-provisioning.sh --dry-run
# Container testing
docker run --rm provisioning:2.1.0 provisioning --version
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h2 id = "release-management" > < a class = "header" href = "#release-management" > Release Management< / a > < / h2 >
< h3 id = "release-workflow" > < a class = "header" href = "#release-workflow" > Release Workflow< / a > < / h3 >
< p > < strong > GitHub Release Integration< / strong > :< / p >
< pre > < code class = "language-bash" > # Create GitHub release
2025-12-11 21:50:42 +00:00
nu src/tools/release/create-release.nu \
--version 2.1.0 \
--asset-dir packages \
--generate-changelog \
--push-tag \
--auto-upload
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Release Features< / strong > :< / p >
< ul >
< li > < strong > Automated Changelog< / strong > : Generated from git commit history< / li >
< li > < strong > Asset Management< / strong > : Automatic upload of all distribution artifacts< / li >
< li > < strong > Tag Management< / strong > : Semantic version tagging< / li >
< li > < strong > Release Notes< / strong > : Formatted release notes with change summaries< / li >
< / ul >
< h3 id = "versioning-strategy" > < a class = "header" href = "#versioning-strategy" > Versioning Strategy< / a > < / h3 >
< p > < strong > Semantic Versioning< / strong > :< / p >
< ul >
< li > < strong > MAJOR.MINOR.PATCH< / strong > format (for example, 2.1.0)< / li >
< li > < strong > Pre-release< / strong > suffixes (for example, 2.1.0-alpha.1, 2.1.0-rc.2)< / li >
< li > < strong > Build metadata< / strong > (for example, 2.1.0+20250925.abcdef)< / li >
< / ul >
< p > < strong > Version Detection< / strong > :< / p >
< pre > < code class = "language-bash" > # Auto-detect next version
2025-12-11 21:50:42 +00:00
nu src/tools/release/create-release.nu --release-type minor
# Manual version specification
nu src/tools/release/create-release.nu --version 2.1.0
# Pre-release versioning
nu src/tools/release/create-release.nu --version 2.1.0-rc.1 --pre-release
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "artifact-management" > < a class = "header" href = "#artifact-management" > Artifact Management< / a > < / h3 >
< p > < strong > Artifact Types< / strong > :< / p >
< ul >
< li > < strong > Source Archives< / strong > : Complete source code distributions< / li >
< li > < strong > Binary Archives< / strong > : Compiled binary distributions< / li >
< li > < strong > Container Images< / strong > : OCI-compliant container images< / li >
< li > < strong > Installers< / strong > : Platform-specific installation packages< / li >
< li > < strong > Documentation< / strong > : Generated documentation packages< / li >
< / ul >
< p > < strong > Upload and Distribution< / strong > :< / p >
< pre > < code class = "language-bash" > # Upload to GitHub Releases
2025-12-11 21:50:42 +00:00
make upload-artifacts
# Upload to container registries
docker push provisioning:2.1.0
# Update package repositories
make update-registry
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h2 id = "rollback-procedures" > < a class = "header" href = "#rollback-procedures" > Rollback Procedures< / a > < / h2 >
< h3 id = "rollback-scenarios" > < a class = "header" href = "#rollback-scenarios" > Rollback Scenarios< / a > < / h3 >
< p > < strong > Common Rollback Triggers< / strong > :< / p >
< ul >
< li > Critical bugs discovered post-release< / li >
< li > Security vulnerabilities identified< / li >
< li > Performance regression< / li >
< li > Compatibility issues< / li >
< li > Infrastructure failures< / li >
< / ul >
< h3 id = "rollback-process" > < a class = "header" href = "#rollback-process" > Rollback Process< / a > < / h3 >
< p > < strong > Automated Rollback< / strong > :< / p >
< pre > < code class = "language-bash" > # Rollback latest release
2025-12-11 21:50:42 +00:00
nu src/tools/release/rollback-release.nu --version 2.1.0
# Rollback with specific target
nu src/tools/release/rollback-release.nu \
--from-version 2.1.0 \
--to-version 2.0.5 \
--update-registries \
--notify-users
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Manual Rollback Steps< / strong > :< / p >
< pre > < code class = "language-bash" > # 1. Identify target version
2025-12-11 21:50:42 +00:00
git tag -l | grep -v 2.1.0 | tail -5
# 2. Create rollback release
nu src/tools/release/create-release.nu \
--version 2.0.6 \
--rollback-from 2.1.0 \
--urgent
# 3. Update package managers
nu src/tools/release/update-registry.nu \
--version 2.0.6 \
--rollback-notice "Critical fix for 2.1.0 issues"
# 4. Notify users
nu src/tools/release/notify-users.nu \
--channels slack,discord,email \
--message-type rollback \
--urgent
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "rollback-safety" > < a class = "header" href = "#rollback-safety" > Rollback Safety< / a > < / h3 >
< p > < strong > Pre-Rollback Validation< / strong > :< / p >
< ul >
< li > Validate target version integrity< / li >
< li > Check compatibility matrix< / li >
< li > Verify rollback procedure testing< / li >
< li > Confirm communication plan< / li >
< / ul >
< p > < strong > Rollback Testing< / strong > :< / p >
< pre > < code class = "language-bash" > # Test rollback in staging
2025-12-11 21:50:42 +00:00
nu src/tools/release/rollback-release.nu \
--version 2.1.0 \
--target-version 2.0.5 \
--dry-run \
--staging-environment
# Validate rollback success
make test-dist DIST_VERSION=2.0.5
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "emergency-procedures" > < a class = "header" href = "#emergency-procedures" > Emergency Procedures< / a > < / h3 >
< p > < strong > Critical Security Rollback< / strong > :< / p >
< pre > < code class = "language-bash" > # Emergency rollback (bypasses normal procedures)
2025-12-11 21:50:42 +00:00
nu src/tools/release/rollback-release.nu \
--version 2.1.0 \
--emergency \
--security-issue \
--immediate-notify
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Infrastructure Failure Recovery< / strong > :< / p >
< pre > < code class = "language-bash" > # Failover to backup infrastructure
2025-12-11 21:50:42 +00:00
nu src/tools/release/rollback-release.nu \
--infrastructure-failover \
--backup-registry \
--mirror-sync
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h2 id = "cicd-integration" > < a class = "header" href = "#cicd-integration" > CI/CD Integration< / a > < / h2 >
< h3 id = "github-actions-integration" > < a class = "header" href = "#github-actions-integration" > GitHub Actions Integration< / a > < / h3 >
< p > < strong > Build Workflow< / strong > (< code > .github/workflows/build.yml< / code > ):< / p >
< pre > < code class = "language-yaml" > name: Build and Distribute
2025-12-11 21:50:42 +00:00
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
platform: [linux, macos, windows]
steps:
- uses: actions/checkout@v4
- name: Setup Nushell
uses: hustcer/setup-nu@v3.5
- name: Setup Rust
uses: actions-rs/toolchain@v1
with:
toolchain: stable
- name: CI Build
run: |
cd src/tools
make ci-build
- name: Upload Build Artifacts
uses: actions/upload-artifact@v4
with:
name: build-${{ matrix.platform }}
path: src/dist/
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Release Workflow< / strong > (< code > .github/workflows/release.yml< / code > ):< / p >
< pre > < code class = "language-yaml" > name: Release
2025-12-11 21:50:42 +00:00
on:
push:
tags: ['v*']
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build Release
run: |
cd src/tools
make ci-release VERSION=${{ github.ref_name }}
- name: Create Release
run: |
cd src/tools
make release VERSION=${{ github.ref_name }}
- name: Update Registries
run: |
cd src/tools
make update-registry VERSION=${{ github.ref_name }}
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "gitlab-ci-integration" > < a class = "header" href = "#gitlab-ci-integration" > GitLab CI Integration< / a > < / h3 >
< p > < strong > GitLab CI Configuration< / strong > (< code > .gitlab-ci.yml< / code > ):< / p >
< pre > < code class = "language-yaml" > stages:
2025-12-11 21:50:42 +00:00
- build
- package
- test
- release
build:
stage: build
script:
- cd src/tools
- make ci-build
artifacts:
paths:
- src/dist/
expire_in: 1 hour
package:
stage: package
script:
- cd src/tools
- make package-all
artifacts:
paths:
- src/packages/
expire_in: 1 day
release:
stage: release
script:
- cd src/tools
- make cd-deploy VERSION=${CI_COMMIT_TAG}
only:
- tags
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "jenkins-integration" > < a class = "header" href = "#jenkins-integration" > Jenkins Integration< / a > < / h3 >
< p > < strong > Jenkinsfile< / strong > :< / p >
< pre > < code class = "language-groovy" > pipeline {
2025-12-11 21:50:42 +00:00
agent any
stages {
stage('Build') {
steps {
dir('src/tools') {
sh 'make ci-build'
}
}
}
stage('Package') {
steps {
dir('src/tools') {
sh 'make package-all'
}
}
}
stage('Release') {
when {
tag '*'
}
steps {
dir('src/tools') {
sh "make cd-deploy VERSION=${env.TAG_NAME}"
}
}
}
}
}
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h2 id = "troubleshooting" > < a class = "header" href = "#troubleshooting" > Troubleshooting< / a > < / h2 >
< h3 id = "common-issues" > < a class = "header" href = "#common-issues" > Common Issues< / a > < / h3 >
< h4 id = "build-failures" > < a class = "header" href = "#build-failures" > Build Failures< / a > < / h4 >
< p > < strong > Rust Compilation Errors< / strong > :< / p >
< pre > < code class = "language-bash" > # Solution: Clean and rebuild
2025-12-11 21:50:42 +00:00
make clean
cargo clean
make build-platform
# Check Rust toolchain
rustup show
rustup update
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Cross-Compilation Issues< / strong > :< / p >
< pre > < code class = "language-bash" > # Solution: Install missing targets
2025-12-11 21:50:42 +00:00
rustup target list --installed
rustup target add x86_64-apple-darwin
# Use cross for problematic targets
cargo install cross
make build-platform CROSS=true
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h4 id = "package-generation-issues" > < a class = "header" href = "#package-generation-issues" > Package Generation Issues< / a > < / h4 >
< p > < strong > Missing Dependencies< / strong > :< / p >
< pre > < code class = "language-bash" > # Solution: Install build tools
2025-12-11 21:50:42 +00:00
sudo apt-get install build-essential
brew install gnu-tar
# Check tool availability
make info
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Permission Errors< / strong > :< / p >
< pre > < code class = "language-bash" > # Solution: Fix permissions
2025-12-11 21:50:42 +00:00
chmod +x src/tools/build/*.nu
chmod +x src/tools/distribution/*.nu
chmod +x src/tools/package/*.nu
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h4 id = "distribution-validation-failures" > < a class = "header" href = "#distribution-validation-failures" > Distribution Validation Failures< / a > < / h4 >
< p > < strong > Package Integrity Issues< / strong > :< / p >
< pre > < code class = "language-bash" > # Solution: Regenerate packages
2025-12-11 21:50:42 +00:00
make clean-dist
make package-all
# Verify manually
sha256sum packages/*.tar.gz
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Installation Test Failures< / strong > :< / p >
< pre > < code class = "language-bash" > # Solution: Test in clean environment
2025-12-11 21:50:42 +00:00
docker run --rm -v $(pwd):/work ubuntu:latest /work/packages/installers/install.sh
# Debug installation
./packages/installers/install.sh --dry-run --verbose
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "release-issues" > < a class = "header" href = "#release-issues" > Release Issues< / a > < / h3 >
< h4 id = "upload-failures" > < a class = "header" href = "#upload-failures" > Upload Failures< / a > < / h4 >
< p > < strong > Network Issues< / strong > :< / p >
< pre > < code class = "language-bash" > # Solution: Retry with backoff
2025-12-11 21:50:42 +00:00
nu src/tools/release/upload-artifacts.nu \
--retry-count 5 \
--backoff-delay 30
# Manual upload
gh release upload v2.1.0 packages/*.tar.gz
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Authentication Failures< / strong > :< / p >
< pre > < code class = "language-bash" > # Solution: Refresh tokens
2025-12-11 21:50:42 +00:00
gh auth refresh
docker login ghcr.io
# Check credentials
gh auth status
docker system info
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h4 id = "registry-update-issues" > < a class = "header" href = "#registry-update-issues" > Registry Update Issues< / a > < / h4 >
< p > < strong > Homebrew Formula Issues< / strong > :< / p >
< pre > < code class = "language-bash" > # Solution: Manual PR creation
2025-12-11 21:50:42 +00:00
git clone https://github.com/Homebrew/homebrew-core
cd homebrew-core
# Edit formula
git add Formula/provisioning.rb
git commit -m "provisioning 2.1.0"
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "debug-and-monitoring" > < a class = "header" href = "#debug-and-monitoring" > Debug and Monitoring< / a > < / h3 >
< p > < strong > Debug Mode< / strong > :< / p >
< pre > < code class = "language-bash" > # Enable debug logging
2025-12-11 21:50:42 +00:00
export PROVISIONING_DEBUG=true
export RUST_LOG=debug
# Run with verbose output
make all VERBOSE=true
# Debug specific components
nu src/tools/distribution/generate-distribution.nu \
--verbose \
--dry-run
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Monitoring Build Progress< / strong > :< / p >
< pre > < code class = "language-bash" > # Monitor build logs
2025-12-11 21:50:42 +00:00
tail -f src/tools/build.log
# Check build status
make status
# Resource monitoring
top
df -h
< / code > < / pre >
2026-01-12 04:42:18 +00:00
< p > This distribution process provides a robust, automated pipeline for creating, validating, and distributing provisioning across multiple platforms while maintaining high quality and reliability standards.< / p >
2025-12-11 21:50:42 +00:00
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
2026-01-08 09:55:37 +00:00
< a rel = "prev" href = "../development/extensions.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-left" > < / i >
< / a >
2026-01-08 09:55:37 +00:00
< a rel = "next prefetch" href = "../development/implementation-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 = "prev" href = "../development/extensions.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-left" > < / i >
< / a >
2026-01-08 09:55:37 +00:00
< a rel = "next prefetch" href = "../development/implementation-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 >
