provisioning/docs/src/getting-started/setup-system-guide.md

Provisioning Setup System Guide

Version: 1.0.0 Last Updated: 2025-12-09 Status: Production Ready

Quick Start

Prerequisites

• Nushell 0.109.0+
• bash
• One deployment tool: Docker, Kubernetes, SSH, or systemd
• Optional: KCL, SOPS, Age

30-Second Setup

# Install provisioning
curl -sSL https://install.provisioning.dev | bash

# Run setup wizard
provisioning setup system --interactive

# Create workspace
provisioning setup workspace myproject

# Start deploying
provisioning server create

Configuration Paths

macOS: ~/Library/Application Support/provisioning/ Linux: ~/.config/provisioning/ Windows: %APPDATA%/provisioning/

Directory Structure

provisioning/
├── system.toml                  # System info (immutable)
├── user_preferences.toml        # User settings (editable)
├── platform/                    # Platform services
├── providers/                   # Provider configs
└── workspaces/                  # Workspace definitions
    └── myproject/
        ├── config/
        ├── infra/
        └── auth.token

Setup Wizard

Run the interactive setup wizard:

provisioning setup system --interactive

The wizard guides you through:

1. Welcome & Prerequisites Check
2. Operating System Detection
3. Configuration Path Selection
4. Platform Services Setup
5. Provider Selection
6. Security Configuration
7. Review & Confirmation

Configuration Management

Hierarchy (highest to lowest priority)

1. Runtime Arguments (--flag value)
2. Environment Variables (PROVISIONING_*)
3. Workspace Configuration
4. Workspace Authentication Token
5. User Preferences (user_preferences.toml)
6. Platform Configurations (platform/*.toml)
7. Provider Configurations (providers/*.toml)
8. System Configuration (system.toml)
9. Built-in Defaults

Configuration Files

• system.toml - System information (OS, architecture, paths)
• user_preferences.toml - User preferences (editor, format, etc.)
• platform/*.toml - Service endpoints and configuration
• providers/*.toml - Cloud provider settings

Multiple Workspaces

Create and manage multiple isolated environments:

# Create workspace
provisioning setup workspace dev
provisioning setup workspace prod

# List workspaces
provisioning workspace list

# Activate workspace
provisioning workspace activate prod

Configuration Updates

Update any setting:

# Update platform configuration
provisioning setup platform --config new-config.toml

# Update provider settings
provisioning setup provider upcloud --config upcloud-config.toml

# Validate changes
provisioning setup validate

Backup & Restore

# Backup current configuration
provisioning setup backup --path ./backup.tar.gz

# Restore from backup
provisioning setup restore --path ./backup.tar.gz

# Migrate from old setup
provisioning setup migrate --from-existing

Troubleshooting

"Command not found: provisioning"

export PATH="/usr/local/bin:$PATH"

"Nushell not found"

curl -sSL https://raw.githubusercontent.com/nushell/nushell/main/install.sh | bash

"Cannot write to directory"

chmod 755 ~/Library/Application\ Support/provisioning/

Check required tools

provisioning setup validate --check-tools

FAQ

Q: Do I need all optional tools? A: No. You need at least one deployment tool (Docker, Kubernetes, SSH, or systemd).

Q: Can I use provisioning without Docker? A: Yes. Provisioning supports Docker, Kubernetes, SSH, systemd, or combinations.

Q: How do I update configuration? A: provisioning setup update <category>

Q: Can I have multiple workspaces? A: Yes, unlimited workspaces.

Q: Is my configuration secure? A: Yes. Credentials stored securely, never in config files.

Q: Can I share workspaces with my team? A: Yes, via GitOps - configurations in Git, secrets in secure storage.

Getting Help

# General help
provisioning help

# Setup help
provisioning help setup

# Specific command help
provisioning setup system --help

Next Steps

1. Installation Guide
2. Workspace Setup
3. Provider Configuration
4. From Scratch Guide

---

Status: Production Ready ✅ Version: 1.0.0 Last Updated: 2025-12-09