# Workspace Setup Guide\n\nThis guide shows you how to set up a new infrastructure workspace with Nickel-based configuration and auto-generated documentation.\n\n## Quick Start\n\n### 1. Create a New Workspace (Automatic)\n\n```\n# Interactive workspace creation with prompts\nprovisioning workspace init\n\n# Or non-interactive with explicit path\nprovisioning workspace init my_workspace /path/to/my_workspace\n```\n\nWhen you run `provisioning workspace init`, the system automatically:\n- ✅ Creates Nickel-based configuration (`config/config.ncl`)\n- ✅ Sets up infrastructure directories with Nickel files (`infra/default/`)\n- ✅ **Generates 4 workspace guides** (deployment, configuration, troubleshooting, README)\n- ✅ Configures local provider as default\n- ✅ Creates .gitignore for workspace\n\n### 2. Workspace Structure (Auto-Generated)\n\nAfter running `workspace init`, your workspace has this structure:\n\n```\nmy_workspace/\n├── config/\n│   ├── config.ncl              # Master Nickel configuration\n│   ├── providers/\n│   └── platform/\n│\n├── infra/\n│   └── default/\n│       ├── main.ncl            # Infrastructure definition\n│       └── servers.ncl         # Server configurations\n│\n├── docs/                       # ✨ AUTO-GENERATED GUIDES\n│   ├── README.md              # Workspace overview & quick start\n│   ├── deployment-guide.md    # Step-by-step deployment\n│   ├── configuration-guide.md # Configuration reference\n│   └── troubleshooting.md     # Common issues & solutions\n│\n├── .providers/                # Provider state & cache\n├── .kms/                      # KMS data\n├── .provisioning/             # Workspace metadata\n└── workspace.nu              # Utility scripts\n```\n\n### 3. Understanding Nickel Configuration\n\nThe `config/config.ncl` file is the master configuration for your workspace:\n\n```\n{\n  workspace = {\n    name = "my_workspace",\n    path = "/path/to/my_workspace",\n    description = "Workspace: my_workspace",\n    metadata = {\n      owner = "your_username",\n      created = "2025-01-07T19:30:00Z",\n      environment = "development",\n    },\n  },\n\n  providers = {\n    local = {\n      name = "local",\n      enabled = true,\n      workspace = "my_workspace",\n      auth = { interface = "local" },\n      paths = {\n        base = ".providers/local",\n        cache = ".providers/local/cache",\n        state = ".providers/local/state",\n      },\n    },\n  },\n}\n```\n\n### 4. Auto-Generated Documentation\n\nEvery workspace gets 4 auto-generated guides tailored to your specific configuration:\n\n**README.md** - Overview with workspace structure and quick start\n**deployment-guide.md** - Step-by-step deployment instructions for your infrastructure\n**configuration-guide.md** - Configuration reference specific to your workspace\n**troubleshooting.md** - Common issues and solutions for your setup\n\nThese guides are automatically generated based on your workspace's:\n- Configured providers\n- Infrastructure definitions\n- Server configurations\n- Taskservs and services\n\n### 5. Customize Your Workspace\n\nAfter creation, edit the Nickel configuration files:\n\n```\n# Edit master configuration\nvim config/config.ncl\n\n# Edit infrastructure definition\nvim infra/default/main.ncl\n\n# Edit server definitions\nvim infra/default/servers.ncl\n\n# Validate Nickel syntax\nnickel typecheck config/config.ncl\n```\n\n## Next Steps After Workspace Creation\n\n### 1. Read Your Auto-Generated Documentation\n\nEach workspace gets 4 auto-generated guides in the `docs/` directory:\n\n```\ncd my_workspace\n\n# Overview and quick start\ncat docs/README.md\n\n# Step-by-step deployment\ncat docs/deployment-guide.md\n\n# Configuration reference\ncat docs/configuration-guide.md\n\n# Common issues and solutions\ncat docs/troubleshooting.md\n```\n\n### 2. Customize Your Configuration\n\nEdit the Nickel configuration files to suit your needs:\n\n```\n# Master configuration (providers, settings)\nvim config/config.ncl\n\n# Infrastructure definition\nvim infra/default/main.ncl\n\n# Server configurations\nvim infra/default/servers.ncl\n```\n\n### 3. Validate Your Configuration\n\n```\n# Check Nickel syntax\nnickel typecheck config/config.ncl\nnickel typecheck infra/default/main.ncl\n\n# Validate with provisioning system\nprovisioning validate config\n```\n\n### 4. Add Multiple Infrastructures\n\nTo add more infrastructure environments:\n\n```\n# Create new infrastructure directory\nmkdir infra/production\nmkdir infra/staging\n\n# Create Nickel files for each infrastructure\ncp infra/default/main.ncl infra/production/main.ncl\ncp infra/default/servers.ncl infra/production/servers.ncl\n\n# Edit them for your specific needs\nvim infra/production/servers.ncl\n```\n\n### 5. Configure Providers\n\nTo use cloud providers (UpCloud, AWS, etc.), update `config/config.ncl`:\n\n```\nproviders = {\n  upcloud = {\n    name = "upcloud",\n    enabled = true,              # Set to true to enable\n    workspace = "my_workspace",\n    auth = { interface = "API" },\n    paths = {\n      base = ".providers/upcloud",\n      cache = ".providers/upcloud/cache",\n      state = ".providers/upcloud/state",\n    },\n    api = {\n      url = "https://api.upcloud.com/1.3",\n      timeout = 30,\n    },\n  },\n}\n```\n\n## Workspace Management Commands\n\n### List Workspaces\n\n```\nprovisioning workspace list\n```\n\n### Activate a Workspace\n\n```\nprovisioning workspace activate my_workspace\n```\n\n### Show Active Workspace\n\n```\nprovisioning workspace active\n```\n\n### Deploy Infrastructure\n\n```\n# Dry-run first (check mode)\nprovisioning -c server create\n\n# Actually create servers\nprovisioning server create\n\n# List created servers\nprovisioning server list\n```\n\n## Troubleshooting\n\n### Invalid Nickel Syntax\n\n```\n# Check syntax\nnickel typecheck config/config.ncl\n\n# Example error and solution\nError: Type checking failed\nSolution: Fix the syntax error shown and retry\n```\n\n### Configuration Issues\n\nRefer to the auto-generated `docs/troubleshooting.md` in your workspace for:\n- Authentication & credentials issues\n- Server deployment problems\n- Configuration validation errors\n- Network connectivity issues\n- Performance issues\n\n### Getting Help\n\n1. **Consult workspace guides**: Check the `docs/` directory\n2. **Check the docs**: `provisioning --help`, `provisioning workspace --help`\n3. **Enable debug mode**: `provisioning --debug server create`\n4. **Review logs**: Check logs for detailed error information\n\n## Next Steps\n\n1. **Review auto-generated guides** in `docs/`\n2. **Customize configuration** in Nickel files\n3. **Test with dry-run** before deployment\n4. **Deploy infrastructure**\n5. **Monitor and maintain** your workspace\n\nFor detailed deployment instructions, see `docs/deployment-guide.md` in your workspace.
