982 lines
44 KiB
HTML
982 lines
44 KiB
HTML
|
<!DOCTYPE HTML>
|
|||
|
|
<html lang="en" class="ayu sidebar-visible" dir="ltr">
|
|||
|
|
<head>
|
|||
|
|
<!-- Book generated using mdBook -->
|
|||
|
|
<meta charset="UTF-8">
|
|||
|
|
<title>Workspace Management - 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/workspace-management.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="workspace-management-guide"><a class="header" href="#workspace-management-guide">Workspace Management Guide</a></h1>
|
|||
|
|
<p>This document provides comprehensive guidance on setting up and using development workspaces, including the path resolution system, testing infrastructure, and workspace tools usage.</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="#workspace-architecture">Workspace Architecture</a></li>
|
|||
|
|
<li><a href="#setup-and-initialization">Setup and Initialization</a></li>
|
|||
|
|
<li><a href="#path-resolution-system">Path Resolution System</a></li>
|
|||
|
|
<li><a href="#configuration-management">Configuration Management</a></li>
|
|||
|
|
<li><a href="#extension-development">Extension Development</a></li>
|
|||
|
|
<li><a href="#runtime-management">Runtime Management</a></li>
|
|||
|
|
<li><a href="#health-monitoring">Health Monitoring</a></li>
|
|||
|
|
<li><a href="#backup-and-restore">Backup and Restore</a></li>
|
|||
|
|
<li><a href="#troubleshooting">Troubleshooting</a></li>
|
|||
|
|
</ol>
|
|||
|
|
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
|
|||
|
|
<p>The workspace system provides isolated development environments for the provisioning project, enabling:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>User Isolation</strong>: Each developer has their own workspace with isolated runtime data</li>
|
|||
|
|
<li><strong>Configuration Cascading</strong>: Hierarchical configuration from workspace to core system</li>
|
|||
|
|
<li><strong>Extension Development</strong>: Template-based extension development with testing</li>
|
|||
|
|
<li><strong>Path Resolution</strong>: Smart path resolution with workspace-aware fallbacks</li>
|
|||
|
|
<li><strong>Health Monitoring</strong>: Comprehensive health checks with automatic repairs</li>
|
|||
|
|
<li><strong>Backup/Restore</strong>: Complete workspace backup and restore capabilities</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Location</strong>: <code>/workspace/</code>
|
|||
|
|
<strong>Main Tool</strong>: <code>workspace/tools/workspace.nu</code></p>
|
|||
|
|
<h2 id="workspace-architecture"><a class="header" href="#workspace-architecture">Workspace Architecture</a></h2>
|
|||
|
|
<h3 id="directory-structure"><a class="header" href="#directory-structure">Directory Structure</a></h3>
|
|||
|
|
<pre><code>workspace/
|
|||
|
|
├── config/ # Development configuration
|
|||
|
|
│ ├── dev-defaults.toml # Development environment defaults
|
|||
|
|
│ ├── test-defaults.toml # Testing environment configuration
|
|||
|
|
│ ├── local-overrides.toml.example # User customization template
|
|||
|
|
│ └── {user}.toml # User-specific configurations
|
|||
|
|
├── extensions/ # Extension development
|
|||
|
|
│ ├── providers/ # Custom provider extensions
|
|||
|
|
│ │ ├── template/ # Provider development template
|
|||
|
|
│ │ └── {user}/ # User-specific providers
|
|||
|
|
│ ├── taskservs/ # Custom task service extensions
|
|||
|
|
│ │ ├── template/ # Task service template
|
|||
|
|
│ │ └── {user}/ # User-specific task services
|
|||
|
|
│ └── clusters/ # Custom cluster extensions
|
|||
|
|
│ ├── template/ # Cluster template
|
|||
|
|
│ └── {user}/ # User-specific clusters
|
|||
|
|
├── infra/ # Development infrastructure
|
|||
|
|
│ ├── examples/ # Example infrastructures
|
|||
|
|
│ │ ├── minimal/ # Minimal learning setup
|
|||
|
|
│ │ ├── development/ # Full development environment
|
|||
|
|
│ │ └── testing/ # Testing infrastructure
|
|||
|
|
│ ├── local/ # Local development setups
|
|||
|
|
│ └── {user}/ # User-specific infrastructures
|
|||
|
|
├── lib/ # Workspace libraries
|
|||
|
|
│ └── path-resolver.nu # Path resolution system
|
|||
|
|
├── runtime/ # Runtime data (per-user isolation)
|
|||
|
|
│ ├── workspaces/{user}/ # User workspace data
|
|||
|
|
│ ├── cache/{user}/ # User-specific cache
|
|||
|
|
│ ├── state/{user}/ # User state management
|
|||
|
|
│ ├── logs/{user}/ # User application logs
|
|||
|
|
│ └── data/{user}/ # User database files
|
|||
|
|
└── tools/ # Workspace management tools
|
|||
|
|
├── workspace.nu # Main workspace interface
|
|||
|
|
├── init-workspace.nu # Workspace initialization
|
|||
|
|
├── workspace-health.nu # Health monitoring
|
|||
|
|
├── backup-workspace.nu # Backup management
|
|||
|
|
├── restore-workspace.nu # Restore functionality
|
|||
|
|
├── reset-workspace.nu # Workspace reset
|
|||
|
|
└── runtime-manager.nu # Runtime data management
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="component-integration"><a class="header" href="#component-integration">Component Integration</a></h3>
|
|||
|
|
<p><strong>Workspace → Core Integration</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Workspace paths take priority over core paths</li>
|
|||
|
|
<li>Extensions discovered automatically from workspace</li>
|
|||
|
|
<li>Configuration cascades from workspace to core defaults</li>
|
|||
|
|
<li>Runtime data completely isolated per user</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Development Workflow</strong>:</p>
|
|||
|
|
<ol>
|
|||
|
|
<li><strong>Initialize</strong> personal workspace</li>
|
|||
|
|
<li><strong>Configure</strong> development environment</li>
|
|||
|
|
<li><strong>Develop</strong> extensions and infrastructure</li>
|
|||
|
|
<li><strong>Test</strong> locally with isolated environment</li>
|
|||
|
|
<li><strong>Deploy</strong> to shared infrastructure</li>
|
|||
|
|
</ol>
|
|||
|
|
<h2 id="setup-and-initialization"><a class="header" href="#setup-and-initialization">Setup and Initialization</a></h2>
|
|||
|
|
<h3 id="quick-start"><a class="header" href="#quick-start">Quick Start</a></h3>
|
|||
|
|
<pre><code class="language-bash"># Navigate to workspace
|
|||
|
|
cd workspace/tools
|
|||
|
|
|
|||
|
|
# Initialize workspace with defaults
|
|||
|
|
nu workspace.nu init
|
|||
|
|
|
|||
|
|
# Initialize with specific options
|
|||
|
|
nu workspace.nu init --user-name developer --infra-name my-dev-infra
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="complete-initialization"><a class="header" href="#complete-initialization">Complete Initialization</a></h3>
|
|||
|
|
<pre><code class="language-bash"># Full initialization with all options
|
|||
|
|
nu workspace.nu init \
|
|||
|
|
--user-name developer \
|
|||
|
|
--infra-name development-env \
|
|||
|
|
--workspace-type development \
|
|||
|
|
--template full \
|
|||
|
|
--overwrite \
|
|||
|
|
--create-examples
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Initialization Parameters</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>--user-name</code>: User identifier (defaults to <code>$env.USER</code>)</li>
|
|||
|
|
<li><code>--infra-name</code>: Infrastructure name for this workspace</li>
|
|||
|
|
<li><code>--workspace-type</code>: Type (<code>development</code>, <code>testing</code>, <code>production</code>)</li>
|
|||
|
|
<li><code>--template</code>: Template to use (<code>minimal</code>, <code>full</code>, <code>custom</code>)</li>
|
|||
|
|
<li><code>--overwrite</code>: Overwrite existing workspace</li>
|
|||
|
|
<li><code>--create-examples</code>: Create example configurations and infrastructure</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="post-initialization-setup"><a class="header" href="#post-initialization-setup">Post-Initialization Setup</a></h3>
|
|||
|
|
<p><strong>Verify Installation</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Check workspace health
|
|||
|
|
nu workspace.nu health --detailed
|
|||
|
|
|
|||
|
|
# Show workspace status
|
|||
|
|
nu workspace.nu status --detailed
|
|||
|
|
|
|||
|
|
# List workspace contents
|
|||
|
|
nu workspace.nu list
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Configure Development Environment</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Create user-specific configuration
|
|||
|
|
cp workspace/config/local-overrides.toml.example workspace/config/$USER.toml
|
|||
|
|
|
|||
|
|
# Edit configuration
|
|||
|
|
$EDITOR workspace/config/$USER.toml
|
|||
|
|
</code></pre>
|
|||
|
|
<h2 id="path-resolution-system"><a class="header" href="#path-resolution-system">Path Resolution System</a></h2>
|
|||
|
|
<p>The workspace implements a sophisticated path resolution system that prioritizes workspace paths while providing fallbacks to core system paths.</p>
|
|||
|
|
<h3 id="resolution-hierarchy"><a class="header" href="#resolution-hierarchy">Resolution Hierarchy</a></h3>
|
|||
|
|
<p><strong>Resolution Order</strong>:</p>
|
|||
|
|
<ol>
|
|||
|
|
<li><strong>Workspace User Paths</strong>: <code>workspace/{type}/{user}/{name}</code></li>
|
|||
|
|
<li><strong>Workspace Shared Paths</strong>: <code>workspace/{type}/{name}</code></li>
|
|||
|
|
<li><strong>Workspace Templates</strong>: <code>workspace/{type}/template/{name}</code></li>
|
|||
|
|
<li><strong>Core System Paths</strong>: <code>core/{type}/{name}</code> (fallback)</li>
|
|||
|
|
</ol>
|
|||
|
|
<h3 id="using-path-resolution"><a class="header" href="#using-path-resolution">Using Path Resolution</a></h3>
|
|||
|
|
<pre><code class="language-nushell"># Import path resolver
|
|||
|
|
use workspace/lib/path-resolver.nu
|
|||
|
|
|
|||
|
|
# Resolve configuration with workspace awareness
|
|||
|
|
let config_path = (path-resolver resolve_path "config" "user" --workspace-user "developer")
|
|||
|
|
|
|||
|
|
# Resolve with automatic fallback to core
|
|||
|
|
let extension_path = (path-resolver resolve_path "extensions" "custom-provider" --fallback-to-core)
|
|||
|
|
|
|||
|
|
# Create missing directories during resolution
|
|||
|
|
let new_path = (path-resolver resolve_path "infra" "my-infra" --create-missing)
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="configuration-resolution"><a class="header" href="#configuration-resolution">Configuration Resolution</a></h3>
|
|||
|
|
<p><strong>Hierarchical Configuration Loading</strong>:</p>
|
|||
|
|
<pre><code class="language-nushell"># Resolve configuration with full hierarchy
|
|||
|
|
let config = (path-resolver resolve_config "user" --workspace-user "developer")
|
|||
|
|
|
|||
|
|
# Load environment-specific configuration
|
|||
|
|
let dev_config = (path-resolver resolve_config "development" --workspace-user "developer")
|
|||
|
|
|
|||
|
|
# Get merged configuration with all overrides
|
|||
|
|
let merged = (path-resolver resolve_config "merged" --workspace-user "developer" --include-overrides)
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="extension-discovery"><a class="header" href="#extension-discovery">Extension Discovery</a></h3>
|
|||
|
|
<p><strong>Automatic Extension Discovery</strong>:</p>
|
|||
|
|
<pre><code class="language-nushell"># Find custom provider extension
|
|||
|
|
let provider = (path-resolver resolve_extension "providers" "my-aws-provider")
|
|||
|
|
|
|||
|
|
# Discover all available task services
|
|||
|
|
let taskservs = (path-resolver list_extensions "taskservs" --include-core)
|
|||
|
|
|
|||
|
|
# Find cluster definition
|
|||
|
|
let cluster = (path-resolver resolve_extension "clusters" "development-cluster")
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="health-checking"><a class="header" href="#health-checking">Health Checking</a></h3>
|
|||
|
|
<p><strong>Workspace Health Validation</strong>:</p>
|
|||
|
|
<pre><code class="language-nushell"># Check workspace health with automatic fixes
|
|||
|
|
let health = (path-resolver check_workspace_health --workspace-user "developer" --fix-issues)
|
|||
|
|
|
|||
|
|
# Validate path resolution chain
|
|||
|
|
let validation = (path-resolver validate_paths --workspace-user "developer" --repair-broken)
|
|||
|
|
|
|||
|
|
# Check runtime directories
|
|||
|
|
let runtime_status = (path-resolver check_runtime_health --workspace-user "developer")
|
|||
|
|
</code></pre>
|
|||
|
|
<h2 id="configuration-management"><a class="header" href="#configuration-management">Configuration Management</a></h2>
|
|||
|
|
<h3 id="configuration-hierarchy"><a class="header" href="#configuration-hierarchy">Configuration Hierarchy</a></h3>
|
|||
|
|
<p><strong>Configuration Cascade</strong>:</p>
|
|||
|
|
<ol>
|
|||
|
|
<li><strong>User Configuration</strong>: <code>workspace/config/{user}.toml</code></li>
|
|||
|
|
<li><strong>Environment Defaults</strong>: <code>workspace/config/{env}-defaults.toml</code></li>
|
|||
|
|
<li><strong>Workspace Defaults</strong>: <code>workspace/config/dev-defaults.toml</code></li>
|
|||
|
|
<li><strong>Core System Defaults</strong>: <code>config.defaults.toml</code></li>
|
|||
|
|
</ol>
|
|||
|
|
<h3 id="environment-specific-configuration"><a class="header" href="#environment-specific-configuration">Environment-Specific Configuration</a></h3>
|
|||
|
|
<p><strong>Development Environment</strong> (<code>workspace/config/dev-defaults.toml</code>):</p>
|
|||
|
|
<pre><code class="language-toml">[core]
|
|||
|
|
name = "provisioning-dev"
|
|||
|
|
version = "dev-${git.branch}"
|
|||
|
|
|
|||
|
|
[development]
|
|||
|
|
auto_reload = true
|
|||
|
|
verbose_logging = true
|
|||
|
|
experimental_features = true
|
|||
|
|
hot_reload_templates = true
|
|||
|
|
|
|||
|
|
[http]
|
|||
|
|
use_curl = false
|
|||
|
|
timeout = 30
|
|||
|
|
retry_count = 3
|
|||
|
|
|
|||
|
|
[cache]
|
|||
|
|
enabled = true
|
|||
|
|
ttl = 300
|
|||
|
|
refresh_interval = 60
|
|||
|
|
|
|||
|
|
[logging]
|
|||
|
|
level = "debug"
|
|||
|
|
file_rotation = true
|
|||
|
|
max_size = "10MB"
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Testing Environment</strong> (<code>workspace/config/test-defaults.toml</code>):</p>
|
|||
|
|
<pre><code class="language-toml">[core]
|
|||
|
|
name = "provisioning-test"
|
|||
|
|
version = "test-${build.timestamp}"
|
|||
|
|
|
|||
|
|
[testing]
|
|||
|
|
mock_providers = true
|
|||
|
|
ephemeral_resources = true
|
|||
|
|
parallel_tests = true
|
|||
|
|
cleanup_after_test = true
|
|||
|
|
|
|||
|
|
[http]
|
|||
|
|
use_curl = true
|
|||
|
|
timeout = 10
|
|||
|
|
retry_count = 1
|
|||
|
|
|
|||
|
|
[cache]
|
|||
|
|
enabled = false
|
|||
|
|
mock_responses = true
|
|||
|
|
|
|||
|
|
[logging]
|
|||
|
|
level = "info"
|
|||
|
|
test_output = true
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="user-configuration-example"><a class="header" href="#user-configuration-example">User Configuration Example</a></h3>
|
|||
|
|
<p><strong>User-Specific Configuration</strong> (<code>workspace/config/{user}.toml</code>):</p>
|
|||
|
|
<pre><code class="language-toml">[core]
|
|||
|
|
name = "provisioning-${workspace.user}"
|
|||
|
|
version = "1.0.0-dev"
|
|||
|
|
|
|||
|
|
[infra]
|
|||
|
|
current = "${workspace.user}-development"
|
|||
|
|
default_provider = "upcloud"
|
|||
|
|
|
|||
|
|
[workspace]
|
|||
|
|
user = "developer"
|
|||
|
|
type = "development"
|
|||
|
|
infra_name = "developer-dev"
|
|||
|
|
|
|||
|
|
[development]
|
|||
|
|
preferred_editor = "code"
|
|||
|
|
auto_backup = true
|
|||
|
|
backup_interval = "1h"
|
|||
|
|
|
|||
|
|
[paths]
|
|||
|
|
# Custom paths for this user
|
|||
|
|
templates = "~/custom-templates"
|
|||
|
|
extensions = "~/my-extensions"
|
|||
|
|
|
|||
|
|
[git]
|
|||
|
|
auto_commit = false
|
|||
|
|
commit_message_template = "[${workspace.user}] ${change.type}: ${change.description}"
|
|||
|
|
|
|||
|
|
[notifications]
|
|||
|
|
slack_webhook = "https://hooks.slack.com/..."
|
|||
|
|
email = "developer@company.com"
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="configuration-commands"><a class="header" href="#configuration-commands">Configuration Commands</a></h3>
|
|||
|
|
<p><strong>Workspace Configuration Management</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Show current configuration
|
|||
|
|
nu workspace.nu config show
|
|||
|
|
|
|||
|
|
# Validate configuration
|
|||
|
|
nu workspace.nu config validate --user-name developer
|
|||
|
|
|
|||
|
|
# Edit user configuration
|
|||
|
|
nu workspace.nu config edit --user-name developer
|
|||
|
|
|
|||
|
|
# Show configuration hierarchy
|
|||
|
|
nu workspace.nu config hierarchy --user-name developer
|
|||
|
|
|
|||
|
|
# Merge configurations for debugging
|
|||
|
|
nu workspace.nu config merge --user-name developer --output merged-config.toml
|
|||
|
|
</code></pre>
|
|||
|
|
<h2 id="extension-development"><a class="header" href="#extension-development">Extension Development</a></h2>
|
|||
|
|
<h3 id="extension-types"><a class="header" href="#extension-types">Extension Types</a></h3>
|
|||
|
|
<p>The workspace provides templates and tools for developing three types of extensions:</p>
|
|||
|
|
<ol>
|
|||
|
|
<li><strong>Providers</strong>: Cloud provider implementations</li>
|
|||
|
|
<li><strong>Task Services</strong>: Infrastructure service components</li>
|
|||
|
|
<li><strong>Clusters</strong>: Complete deployment solutions</li>
|
|||
|
|
</ol>
|
|||
|
|
<h3 id="provider-extension-development"><a class="header" href="#provider-extension-development">Provider Extension Development</a></h3>
|
|||
|
|
<p><strong>Create New Provider</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Copy template
|
|||
|
|
cp -r workspace/extensions/providers/template workspace/extensions/providers/my-provider
|
|||
|
|
|
|||
|
|
# Initialize provider
|
|||
|
|
cd workspace/extensions/providers/my-provider
|
|||
|
|
nu init.nu --provider-name my-provider --author developer
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Provider Structure</strong>:</p>
|
|||
|
|
<pre><code>workspace/extensions/providers/my-provider/
|
|||
|
|
├── kcl/
|
|||
|
|
│ ├── provider.k # Provider configuration schema
|
|||
|
|
│ ├── server.k # Server configuration
|
|||
|
|
│ └── version.k # Version management
|
|||
|
|
├── nulib/
|
|||
|
|
│ ├── provider.nu # Main provider implementation
|
|||
|
|
│ ├── servers.nu # Server management
|
|||
|
|
│ └── auth.nu # Authentication handling
|
|||
|
|
├── templates/
|
|||
|
|
│ ├── server.j2 # Server configuration template
|
|||
|
|
│ └── network.j2 # Network configuration template
|
|||
|
|
├── tests/
|
|||
|
|
│ ├── unit/ # Unit tests
|
|||
|
|
│ └── integration/ # Integration tests
|
|||
|
|
└── README.md
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Test Provider</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Run provider tests
|
|||
|
|
nu workspace/extensions/providers/my-provider/nulib/provider.nu test
|
|||
|
|
|
|||
|
|
# Test with dry-run
|
|||
|
|
nu workspace/extensions/providers/my-provider/nulib/provider.nu create-server --dry-run
|
|||
|
|
|
|||
|
|
# Integration test
|
|||
|
|
nu workspace/extensions/providers/my-provider/tests/integration/basic-test.nu
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="task-service-extension-development"><a class="header" href="#task-service-extension-development">Task Service Extension Development</a></h3>
|
|||
|
|
<p><strong>Create New Task Service</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Copy template
|
|||
|
|
cp -r workspace/extensions/taskservs/template workspace/extensions/taskservs/my-service
|
|||
|
|
|
|||
|
|
# Initialize service
|
|||
|
|
cd workspace/extensions/taskservs/my-service
|
|||
|
|
nu init.nu --service-name my-service --service-type database
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Task Service Structure</strong>:</p>
|
|||
|
|
<pre><code>workspace/extensions/taskservs/my-service/
|
|||
|
|
├── kcl/
|
|||
|
|
│ ├── taskserv.k # Service configuration schema
|
|||
|
|
│ ├── version.k # Version configuration with GitHub integration
|
|||
|
|
│ └── kcl.mod # KCL module dependencies
|
|||
|
|
├── nushell/
|
|||
|
|
│ ├── taskserv.nu # Main service implementation
|
|||
|
|
│ ├── install.nu # Installation logic
|
|||
|
|
│ ├── uninstall.nu # Removal logic
|
|||
|
|
│ └── check-updates.nu # Version checking
|
|||
|
|
├── templates/
|
|||
|
|
│ ├── config.j2 # Service configuration template
|
|||
|
|
│ ├── systemd.j2 # Systemd service template
|
|||
|
|
│ └── compose.j2 # Docker Compose template
|
|||
|
|
└── manifests/
|
|||
|
|
├── deployment.yaml # Kubernetes deployment
|
|||
|
|
└── service.yaml # Kubernetes service
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="cluster-extension-development"><a class="header" href="#cluster-extension-development">Cluster Extension Development</a></h3>
|
|||
|
|
<p><strong>Create New Cluster</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Copy template
|
|||
|
|
cp -r workspace/extensions/clusters/template workspace/extensions/clusters/my-cluster
|
|||
|
|
|
|||
|
|
# Initialize cluster
|
|||
|
|
cd workspace/extensions/clusters/my-cluster
|
|||
|
|
nu init.nu --cluster-name my-cluster --cluster-type web-stack
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Testing Extensions</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Test extension syntax
|
|||
|
|
nu workspace.nu tools validate-extension providers/my-provider
|
|||
|
|
|
|||
|
|
# Run extension tests
|
|||
|
|
nu workspace.nu tools test-extension taskservs/my-service
|
|||
|
|
|
|||
|
|
# Integration test with infrastructure
|
|||
|
|
nu workspace.nu tools deploy-test clusters/my-cluster --infra test-env
|
|||
|
|
</code></pre>
|
|||
|
|
<h2 id="runtime-management"><a class="header" href="#runtime-management">Runtime Management</a></h2>
|
|||
|
|
<h3 id="runtime-data-organization"><a class="header" href="#runtime-data-organization">Runtime Data Organization</a></h3>
|
|||
|
|
<p><strong>Per-User Isolation</strong>:</p>
|
|||
|
|
<pre><code>runtime/
|
|||
|
|
├── workspaces/
|
|||
|
|
│ ├── developer/ # Developer's workspace data
|
|||
|
|
│ │ ├── current-infra # Current infrastructure context
|
|||
|
|
│ │ ├── settings.toml # Runtime settings
|
|||
|
|
│ │ └── extensions/ # Extension runtime data
|
|||
|
|
│ └── tester/ # Tester's workspace data
|
|||
|
|
├── cache/
|
|||
|
|
│ ├── developer/ # Developer's cache
|
|||
|
|
│ │ ├── providers/ # Provider API cache
|
|||
|
|
│ │ ├── images/ # Container image cache
|
|||
|
|
│ │ └── downloads/ # Downloaded artifacts
|
|||
|
|
│ └── tester/ # Tester's cache
|
|||
|
|
├── state/
|
|||
|
|
│ ├── developer/ # Developer's state
|
|||
|
|
│ │ ├── deployments/ # Deployment state
|
|||
|
|
│ │ └── workflows/ # Workflow state
|
|||
|
|
│ └── tester/ # Tester's state
|
|||
|
|
├── logs/
|
|||
|
|
│ ├── developer/ # Developer's logs
|
|||
|
|
│ │ ├── provisioning.log
|
|||
|
|
│ │ ├── orchestrator.log
|
|||
|
|
│ │ └── extensions/
|
|||
|
|
│ └── tester/ # Tester's logs
|
|||
|
|
└── data/
|
|||
|
|
├── developer/ # Developer's data
|
|||
|
|
│ ├── database.db # Local database
|
|||
|
|
│ └── backups/ # Local backups
|
|||
|
|
└── tester/ # Tester's data
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="runtime-management-commands"><a class="header" href="#runtime-management-commands">Runtime Management Commands</a></h3>
|
|||
|
|
<p><strong>Initialize Runtime Environment</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Initialize for current user
|
|||
|
|
nu workspace/tools/runtime-manager.nu init
|
|||
|
|
|
|||
|
|
# Initialize for specific user
|
|||
|
|
nu workspace/tools/runtime-manager.nu init --user-name developer
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Runtime Cleanup</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Clean cache older than 30 days
|
|||
|
|
nu workspace/tools/runtime-manager.nu cleanup --type cache --age 30d
|
|||
|
|
|
|||
|
|
# Clean logs with rotation
|
|||
|
|
nu workspace/tools/runtime-manager.nu cleanup --type logs --rotate
|
|||
|
|
|
|||
|
|
# Clean temporary files
|
|||
|
|
nu workspace/tools/runtime-manager.nu cleanup --type temp --force
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Log Management</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># View recent logs
|
|||
|
|
nu workspace/tools/runtime-manager.nu logs --action tail --lines 100
|
|||
|
|
|
|||
|
|
# Follow logs in real-time
|
|||
|
|
nu workspace/tools/runtime-manager.nu logs --action tail --follow
|
|||
|
|
|
|||
|
|
# Rotate large log files
|
|||
|
|
nu workspace/tools/runtime-manager.nu logs --action rotate
|
|||
|
|
|
|||
|
|
# Archive old logs
|
|||
|
|
nu workspace/tools/runtime-manager.nu logs --action archive --older-than 7d
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Cache Management</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Show cache statistics
|
|||
|
|
nu workspace/tools/runtime-manager.nu cache --action stats
|
|||
|
|
|
|||
|
|
# Optimize cache
|
|||
|
|
nu workspace/tools/runtime-manager.nu cache --action optimize
|
|||
|
|
|
|||
|
|
# Clear specific cache
|
|||
|
|
nu workspace/tools/runtime-manager.nu cache --action clear --type providers
|
|||
|
|
|
|||
|
|
# Refresh cache
|
|||
|
|
nu workspace/tools/runtime-manager.nu cache --action refresh --selective
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Monitoring</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Monitor runtime usage
|
|||
|
|
nu workspace/tools/runtime-manager.nu monitor --duration 5m --interval 30s
|
|||
|
|
|
|||
|
|
# Check disk usage
|
|||
|
|
nu workspace/tools/runtime-manager.nu monitor --type disk
|
|||
|
|
|
|||
|
|
# Monitor active processes
|
|||
|
|
nu workspace/tools/runtime-manager.nu monitor --type processes --workspace-user developer
|
|||
|
|
</code></pre>
|
|||
|
|
<h2 id="health-monitoring"><a class="header" href="#health-monitoring">Health Monitoring</a></h2>
|
|||
|
|
<h3 id="health-check-system"><a class="header" href="#health-check-system">Health Check System</a></h3>
|
|||
|
|
<p>The workspace provides comprehensive health monitoring with automatic repair capabilities.</p>
|
|||
|
|
<p><strong>Health Check Components</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Directory Structure</strong>: Validates workspace directory integrity</li>
|
|||
|
|
<li><strong>Configuration Files</strong>: Checks configuration syntax and completeness</li>
|
|||
|
|
<li><strong>Runtime Environment</strong>: Validates runtime data and permissions</li>
|
|||
|
|
<li><strong>Extension Status</strong>: Checks extension functionality</li>
|
|||
|
|
<li><strong>Resource Usage</strong>: Monitors disk space and memory usage</li>
|
|||
|
|
<li><strong>Integration Status</strong>: Tests integration with core system</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="health-commands"><a class="header" href="#health-commands">Health Commands</a></h3>
|
|||
|
|
<p><strong>Basic Health Check</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Quick health check
|
|||
|
|
nu workspace.nu health
|
|||
|
|
|
|||
|
|
# Detailed health check with all components
|
|||
|
|
nu workspace.nu health --detailed
|
|||
|
|
|
|||
|
|
# Health check with automatic fixes
|
|||
|
|
nu workspace.nu health --fix-issues
|
|||
|
|
|
|||
|
|
# Export health report
|
|||
|
|
nu workspace.nu health --report-format json > health-report.json
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Component-Specific Health Checks</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Check directory structure
|
|||
|
|
nu workspace/tools/workspace-health.nu check-directories --workspace-user developer
|
|||
|
|
|
|||
|
|
# Validate configuration files
|
|||
|
|
nu workspace/tools/workspace-health.nu check-config --workspace-user developer
|
|||
|
|
|
|||
|
|
# Check runtime environment
|
|||
|
|
nu workspace/tools/workspace-health.nu check-runtime --workspace-user developer
|
|||
|
|
|
|||
|
|
# Test extension functionality
|
|||
|
|
nu workspace/tools/workspace-health.nu check-extensions --workspace-user developer
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="health-monitoring-output"><a class="header" href="#health-monitoring-output">Health Monitoring Output</a></h3>
|
|||
|
|
<p><strong>Example Health Report</strong>:</p>
|
|||
|
|
<pre><code class="language-json">{
|
|||
|
|
"workspace_health": {
|
|||
|
|
"user": "developer",
|
|||
|
|
"timestamp": "2025-09-25T14:30:22Z",
|
|||
|
|
"overall_status": "healthy",
|
|||
|
|
"checks": {
|
|||
|
|
"directories": {
|
|||
|
|
"status": "healthy",
|
|||
|
|
"issues": [],
|
|||
|
|
"auto_fixed": []
|
|||
|
|
},
|
|||
|
|
"configuration": {
|
|||
|
|
"status": "warning",
|
|||
|
|
"issues": [
|
|||
|
|
"User configuration missing default provider"
|
|||
|
|
],
|
|||
|
|
"auto_fixed": [
|
|||
|
|
"Created missing user configuration file"
|
|||
|
|
]
|
|||
|
|
},
|
|||
|
|
"runtime": {
|
|||
|
|
"status": "healthy",
|
|||
|
|
"disk_usage": "1.2GB",
|
|||
|
|
"cache_size": "450MB",
|
|||
|
|
"log_size": "120MB"
|
|||
|
|
},
|
|||
|
|
"extensions": {
|
|||
|
|
"status": "healthy",
|
|||
|
|
"providers": 2,
|
|||
|
|
"taskservs": 5,
|
|||
|
|
"clusters": 1
|
|||
|
|
}
|
|||
|
|
},
|
|||
|
|
"recommendations": [
|
|||
|
|
"Consider cleaning cache (>400MB)",
|
|||
|
|
"Rotate logs (>100MB)"
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="automatic-fixes"><a class="header" href="#automatic-fixes">Automatic Fixes</a></h3>
|
|||
|
|
<p><strong>Auto-Fix Capabilities</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Missing Directories</strong>: Creates missing workspace directories</li>
|
|||
|
|
<li><strong>Broken Symlinks</strong>: Repairs or removes broken symbolic links</li>
|
|||
|
|
<li><strong>Configuration Issues</strong>: Creates missing configuration files with defaults</li>
|
|||
|
|
<li><strong>Permission Problems</strong>: Fixes file and directory permissions</li>
|
|||
|
|
<li><strong>Corrupted Cache</strong>: Clears and rebuilds corrupted cache entries</li>
|
|||
|
|
<li><strong>Log Rotation</strong>: Rotates large log files automatically</li>
|
|||
|
|
</ul>
|
|||
|
|
<h2 id="backup-and-restore"><a class="header" href="#backup-and-restore">Backup and Restore</a></h2>
|
|||
|
|
<h3 id="backup-system"><a class="header" href="#backup-system">Backup System</a></h3>
|
|||
|
|
<p><strong>Backup Components</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Configuration</strong>: All workspace configuration files</li>
|
|||
|
|
<li><strong>Extensions</strong>: Custom extensions and templates</li>
|
|||
|
|
<li><strong>Runtime Data</strong>: User-specific runtime data (optional)</li>
|
|||
|
|
<li><strong>Logs</strong>: Application logs (optional)</li>
|
|||
|
|
<li><strong>Cache</strong>: Cache data (optional)</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="backup-commands"><a class="header" href="#backup-commands">Backup Commands</a></h3>
|
|||
|
|
<p><strong>Create Backup</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Basic backup
|
|||
|
|
nu workspace.nu backup
|
|||
|
|
|
|||
|
|
# Backup with auto-generated name
|
|||
|
|
nu workspace.nu backup --auto-name
|
|||
|
|
|
|||
|
|
# Comprehensive backup including logs and cache
|
|||
|
|
nu workspace.nu backup --auto-name --include-logs --include-cache
|
|||
|
|
|
|||
|
|
# Backup specific components
|
|||
|
|
nu workspace.nu backup --components config,extensions --name my-backup
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Backup Options</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>--auto-name</code>: Generate timestamp-based backup name</li>
|
|||
|
|
<li><code>--include-logs</code>: Include application logs</li>
|
|||
|
|
<li><code>--include-cache</code>: Include cache data</li>
|
|||
|
|
<li><code>--components</code>: Specify components to backup</li>
|
|||
|
|
<li><code>--compress</code>: Create compressed backup archive</li>
|
|||
|
|
<li><code>--encrypt</code>: Encrypt backup with age/sops</li>
|
|||
|
|
<li><code>--remote</code>: Upload to remote storage (S3, etc.)</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="restore-system"><a class="header" href="#restore-system">Restore System</a></h3>
|
|||
|
|
<p><strong>List Available Backups</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># List all backups
|
|||
|
|
nu workspace.nu restore --list-backups
|
|||
|
|
|
|||
|
|
# List backups with details
|
|||
|
|
nu workspace.nu restore --list-backups --detailed
|
|||
|
|
|
|||
|
|
# Show backup contents
|
|||
|
|
nu workspace.nu restore --show-contents --backup-name workspace-developer-20250925_143022
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Restore Operations</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Restore latest backup
|
|||
|
|
nu workspace.nu restore --latest
|
|||
|
|
|
|||
|
|
# Restore specific backup
|
|||
|
|
nu workspace.nu restore --backup-name workspace-developer-20250925_143022
|
|||
|
|
|
|||
|
|
# Selective restore
|
|||
|
|
nu workspace.nu restore --selective --backup-name my-backup
|
|||
|
|
|
|||
|
|
# Restore to different user
|
|||
|
|
nu workspace.nu restore --backup-name my-backup --restore-to different-user
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Advanced Restore Options</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>--selective</code>: Choose components to restore interactively</li>
|
|||
|
|
<li><code>--restore-to</code>: Restore to different user workspace</li>
|
|||
|
|
<li><code>--merge</code>: Merge with existing workspace (don’t overwrite)</li>
|
|||
|
|
<li><code>--dry-run</code>: Show what would be restored without doing it</li>
|
|||
|
|
<li><code>--verify</code>: Verify backup integrity before restore</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="reset-and-cleanup"><a class="header" href="#reset-and-cleanup">Reset and Cleanup</a></h3>
|
|||
|
|
<p><strong>Workspace Reset</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Reset with backup
|
|||
|
|
nu workspace.nu reset --backup-first
|
|||
|
|
|
|||
|
|
# Reset keeping configuration
|
|||
|
|
nu workspace.nu reset --backup-first --keep-config
|
|||
|
|
|
|||
|
|
# Complete reset (dangerous)
|
|||
|
|
nu workspace.nu reset --force --no-backup
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Cleanup Operations</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Clean old data with dry-run
|
|||
|
|
nu workspace.nu cleanup --type old --age 14d --dry-run
|
|||
|
|
|
|||
|
|
# Clean cache forcefully
|
|||
|
|
nu workspace.nu cleanup --type cache --force
|
|||
|
|
|
|||
|
|
# Clean specific user data
|
|||
|
|
nu workspace.nu cleanup --user-name old-user --type all
|
|||
|
|
</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="workspace-not-found"><a class="header" href="#workspace-not-found">Workspace Not Found</a></h4>
|
|||
|
|
<p><strong>Error</strong>: <code>Workspace for user 'developer' not found</code></p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Initialize workspace
|
|||
|
|
nu workspace.nu init --user-name developer
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="path-resolution-errors"><a class="header" href="#path-resolution-errors">Path Resolution Errors</a></h4>
|
|||
|
|
<p><strong>Error</strong>: <code>Path resolution failed for config/user</code></p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Fix with health check
|
|||
|
|
nu workspace.nu health --fix-issues
|
|||
|
|
|
|||
|
|
# Manual fix
|
|||
|
|
nu workspace/lib/path-resolver.nu resolve_path "config" "user" --create-missing
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="configuration-errors"><a class="header" href="#configuration-errors">Configuration Errors</a></h4>
|
|||
|
|
<p><strong>Error</strong>: <code>Invalid configuration syntax in user.toml</code></p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Validate and fix configuration
|
|||
|
|
nu workspace.nu config validate --user-name developer
|
|||
|
|
|
|||
|
|
# Reset to defaults
|
|||
|
|
cp workspace/config/local-overrides.toml.example workspace/config/developer.toml
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="runtime-issues"><a class="header" href="#runtime-issues">Runtime Issues</a></h4>
|
|||
|
|
<p><strong>Error</strong>: <code>Runtime directory permissions error</code></p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Reinitialize runtime
|
|||
|
|
nu workspace/tools/runtime-manager.nu init --user-name developer --force
|
|||
|
|
|
|||
|
|
# Fix permissions manually
|
|||
|
|
chmod -R 755 workspace/runtime/workspaces/developer
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="extension-issues"><a class="header" href="#extension-issues">Extension Issues</a></h4>
|
|||
|
|
<p><strong>Error</strong>: <code>Extension 'my-provider' not found or invalid</code></p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Validate extension
|
|||
|
|
nu workspace.nu tools validate-extension providers/my-provider
|
|||
|
|
|
|||
|
|
# Reinitialize extension from template
|
|||
|
|
cp -r workspace/extensions/providers/template workspace/extensions/providers/my-provider
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="debug-mode"><a class="header" href="#debug-mode">Debug Mode</a></h3>
|
|||
|
|
<p><strong>Enable Debug Logging</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Set debug environment
|
|||
|
|
export PROVISIONING_DEBUG=true
|
|||
|
|
export PROVISIONING_LOG_LEVEL=debug
|
|||
|
|
export PROVISIONING_WORKSPACE_USER=developer
|
|||
|
|
|
|||
|
|
# Run with debug
|
|||
|
|
nu workspace.nu health --detailed
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="performance-issues"><a class="header" href="#performance-issues">Performance Issues</a></h3>
|
|||
|
|
<p><strong>Slow Operations</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Check disk space
|
|||
|
|
df -h workspace/
|
|||
|
|
|
|||
|
|
# Check runtime data size
|
|||
|
|
du -h workspace/runtime/workspaces/developer/
|
|||
|
|
|
|||
|
|
# Optimize workspace
|
|||
|
|
nu workspace.nu cleanup --type cache
|
|||
|
|
nu workspace/tools/runtime-manager.nu cache --action optimize
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="recovery-procedures"><a class="header" href="#recovery-procedures">Recovery Procedures</a></h3>
|
|||
|
|
<p><strong>Corrupted Workspace</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># 1. Backup current state
|
|||
|
|
nu workspace.nu backup --name corrupted-backup --force
|
|||
|
|
|
|||
|
|
# 2. Reset workspace
|
|||
|
|
nu workspace.nu reset --backup-first
|
|||
|
|
|
|||
|
|
# 3. Restore from known good backup
|
|||
|
|
nu workspace.nu restore --latest-known-good
|
|||
|
|
|
|||
|
|
# 4. Validate health
|
|||
|
|
nu workspace.nu health --detailed --fix-issues
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Data Loss Prevention</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Enable automatic backups: <code>backup_interval = "1h"</code> in user config</li>
|
|||
|
|
<li>Use version control for custom extensions</li>
|
|||
|
|
<li>Regular health checks: <code>nu workspace.nu health</code></li>
|
|||
|
|
<li>Monitor disk space and set up alerts</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>This workspace management system provides a robust foundation for development while maintaining isolation and providing comprehensive tools for maintenance and troubleshooting.</p>
|
|||
|
|
|
|||
|
|
</main>
|
|||
|
|
|
|||
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|||
|
|
<!-- Mobile navigation buttons -->
|
|||
|
|
<a rel="prev" href="../development/configuration.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|||
|
|
<i class="fa fa-angle-left"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<a rel="next prefetch" href="../development/KCL_MODULE_GUIDE.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|||
|
|
<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">
|
|||
|
|
<a rel="prev" href="../development/configuration.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|||
|
|
<i class="fa fa-angle-left"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<a rel="next prefetch" href="../development/KCL_MODULE_GUIDE.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|||
|
|
<i class="fa fa-angle-right"></i>
|
|||
|
|
</a>
|
|||
|
|
</nav>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<!-- Livereload script (if served using the cli tool) -->
|
|||
|
|
<script>
|
|||
|
|
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
|
|||
|
|
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
|
|||
|
|
const socket = new WebSocket(wsAddress);
|
|||
|
|
socket.onmessage = function (event) {
|
|||
|
|
if (event.data === "reload") {
|
|||
|
|
socket.close();
|
|||
|
|
location.reload();
|
|||
|
|
}
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
window.onbeforeunload = function() {
|
|||
|
|
socket.close();
|
|||
|
|
}
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<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>
|