# Provisioning Setup System Guide\n\n**Version**: 1.0.0\n**Last Updated**: 2025-12-09\n**Status**: Production Ready\n\n## Quick Start\n\n### Prerequisites\n\n- Nushell 0.109.0+\n- bash\n- One deployment tool: Docker, Kubernetes, SSH, or systemd\n- Optional: KCL, SOPS, Age\n\n### 30-Second Setup\n\n```\n# Install provisioning\ncurl -sSL https://install.provisioning.dev | bash\n\n# Run setup wizard\nprovisioning setup system --interactive\n\n# Create workspace\nprovisioning setup workspace myproject\n\n# Start deploying\nprovisioning server create\n```\n\n## Configuration Paths\n\n**macOS**: `~/Library/Application Support/provisioning/`\n**Linux**: `~/.config/provisioning/`\n**Windows**: `%APPDATA%/provisioning/`\n\n## Directory Structure\n\n```\nprovisioning/\n├── system.toml                  # System info (immutable)\n├── user_preferences.toml        # User settings (editable)\n├── platform/                    # Platform services\n├── providers/                   # Provider configs\n└── workspaces/                  # Workspace definitions\n    └── myproject/\n        ├── config/\n        ├── infra/\n        └── auth.token\n```\n\n## Setup Wizard\n\nRun the interactive setup wizard:\n\n```\nprovisioning setup system --interactive\n```\n\nThe wizard guides you through:\n\n1. Welcome & Prerequisites Check\n2. Operating System Detection\n3. Configuration Path Selection\n4. Platform Services Setup\n5. Provider Selection\n6. Security Configuration\n7. Review & Confirmation\n\n## Configuration Management\n\n### Hierarchy (highest to lowest priority)\n\n1. Runtime Arguments (`--flag value`)\n2. Environment Variables (`PROVISIONING_*`)\n3. Workspace Configuration\n4. Workspace Authentication Token\n5. User Preferences (`user_preferences.toml`)\n6. Platform Configurations (`platform/*.toml`)\n7. Provider Configurations (`providers/*.toml`)\n8. System Configuration (`system.toml`)\n9. Built-in Defaults\n\n### Configuration Files\n\n- `system.toml` - System information (OS, architecture, paths)\n- `user_preferences.toml` - User preferences (editor, format, etc.)\n- `platform/*.toml` - Service endpoints and configuration\n- `providers/*.toml` - Cloud provider settings\n\n## Multiple Workspaces\n\nCreate and manage multiple isolated environments:\n\n```\n# Create workspace\nprovisioning setup workspace dev\nprovisioning setup workspace prod\n\n# List workspaces\nprovisioning workspace list\n\n# Activate workspace\nprovisioning workspace activate prod\n```\n\n## Configuration Updates\n\nUpdate any setting:\n\n```\n# Update platform configuration\nprovisioning setup platform --config new-config.toml\n\n# Update provider settings\nprovisioning setup provider upcloud --config upcloud-config.toml\n\n# Validate changes\nprovisioning setup validate\n```\n\n## Backup & Restore\n\n```\n# Backup current configuration\nprovisioning setup backup --path ./backup.tar.gz\n\n# Restore from backup\nprovisioning setup restore --path ./backup.tar.gz\n\n# Migrate from old setup\nprovisioning setup migrate --from-existing\n```\n\n## Troubleshooting\n\n### "Command not found: provisioning"\n\n```\nexport PATH="/usr/local/bin:$PATH"\n```\n\n### "Nushell not found"\n\n```\ncurl -sSL https://raw.githubusercontent.com/nushell/nushell/main/install.sh | bash\n```\n\n### "Cannot write to directory"\n\n```\nchmod 755 ~/Library/Application\ Support/provisioning/\n```\n\n### Check required tools\n\n```\nprovisioning setup validate --check-tools\n```\n\n## FAQ\n\n**Q: Do I need all optional tools?**\nA: No. You need at least one deployment tool (Docker, Kubernetes, SSH, or systemd).\n\n**Q: Can I use provisioning without Docker?**\nA: Yes. Provisioning supports Docker, Kubernetes, SSH, systemd, or combinations.\n\n**Q: How do I update configuration?**\nA: `provisioning setup update <category>`\n\n**Q: Can I have multiple workspaces?**\nA: Yes, unlimited workspaces.\n\n**Q: Is my configuration secure?**\nA: Yes. Credentials stored securely, never in config files.\n\n**Q: Can I share workspaces with my team?**\nA: Yes, via GitOps - configurations in Git, secrets in secure storage.\n\n## Getting Help\n\n```\n# General help\nprovisioning help\n\n# Setup help\nprovisioning help setup\n\n# Specific command help\nprovisioning setup system --help\n```\n\n## Next Steps\n\n1. [Installation Guide](installation-guide.md)\n2. [Workspace Setup](workspace-setup.md)\n3. [Provider Configuration](provider-setup.md)\n4. [From Scratch Guide](../guides/from-scratch.md)\n\n---\n\n**Status**: Production Ready ✅\n**Version**: 1.0.0\n**Last Updated**: 2025-12-09
