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

```bash
# 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

```bash
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:

```bash
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:

```bash
# 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:

```bash
# 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

```bash
# 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"

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

### "Nushell not found"

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

### "Cannot write to directory"

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

### Check required tools

```bash
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

```bash
# General help
provisioning help

# Setup help
provisioning help setup

# Specific command help
provisioning setup system --help
```

## Next Steps

1. [Installation Guide](installation-guide.md)
2. [Workspace Setup](workspace-setup.md)
3. [Provider Configuration](provider-setup.md)
4. [From Scratch Guide](../guides/from-scratch.md)

---

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