provisioning/docs/src/infrastructure/workspace-setup.md

# Workspace Setup Guide

This guide shows you how to set up a new infrastructure workspace with Nickel-based configuration and auto-generated documentation.

## Quick Start

### 1. Create a New Workspace (Automatic)

```bash
# Interactive workspace creation with prompts
provisioning workspace init

# Or non-interactive with explicit path
provisioning workspace init my_workspace /path/to/my_workspace
```

When you run `provisioning workspace init`, the system automatically:
- ✅ Creates Nickel-based configuration (`config/config.ncl`)
- ✅ Sets up infrastructure directories with Nickel files (`infra/default/`)
- ✅ **Generates 4 workspace guides** (deployment, configuration, troubleshooting, README)
- ✅ Configures local provider as default
- ✅ Creates .gitignore for workspace

### 2. Workspace Structure (Auto-Generated)

After running `workspace init`, your workspace has this structure:

```bash
my_workspace/
├── config/
│   ├── config.ncl              # Master Nickel configuration
│   ├── providers/
│   └── platform/
│
├── infra/
│   └── default/
│       ├── main.ncl            # Infrastructure definition
│       └── servers.ncl         # Server configurations
│
├── docs/                       # ✨ AUTO-GENERATED GUIDES
│   ├── README.md              # Workspace overview & quick start
│   ├── deployment-guide.md    # Step-by-step deployment
│   ├── configuration-guide.md # Configuration reference
│   └── troubleshooting.md     # Common issues & solutions
│
├── .providers/                # Provider state & cache
├── .kms/                      # KMS data
├── .provisioning/             # Workspace metadata
└── workspace.nu              # Utility scripts
```

### 3. Understanding Nickel Configuration

The `config/config.ncl` file is the master configuration for your workspace:

```nickel
{
  workspace = {
    name = "my_workspace",
    path = "/path/to/my_workspace",
    description = "Workspace: my_workspace",
    metadata = {
      owner = "your_username",
      created = "2025-01-07T19:30:00Z",
      environment = "development",
    },
  },

  providers = {
    local = {
      name = "local",
      enabled = true,
      workspace = "my_workspace",
      auth = { interface = "local" },
      paths = {
        base = ".providers/local",
        cache = ".providers/local/cache",
        state = ".providers/local/state",
      },
    },
  },
}
```

### 4. Auto-Generated Documentation

Every workspace gets 4 auto-generated guides tailored to your specific configuration:

**README.md** - Overview with workspace structure and quick start
**deployment-guide.md** - Step-by-step deployment instructions for your infrastructure
**configuration-guide.md** - Configuration reference specific to your workspace
**troubleshooting.md** - Common issues and solutions for your setup

These guides are automatically generated based on your workspace's:
- Configured providers
- Infrastructure definitions
- Server configurations
- Taskservs and services

### 5. Customize Your Workspace

After creation, edit the Nickel configuration files:

```bash
# Edit master configuration
vim config/config.ncl

# Edit infrastructure definition
vim infra/default/main.ncl

# Edit server definitions
vim infra/default/servers.ncl

# Validate Nickel syntax
nickel typecheck config/config.ncl
```

## Next Steps After Workspace Creation

### 1. Read Your Auto-Generated Documentation

Each workspace gets 4 auto-generated guides in the `docs/` directory:

```bash
cd my_workspace

# Overview and quick start
cat docs/README.md

# Step-by-step deployment
cat docs/deployment-guide.md

# Configuration reference
cat docs/configuration-guide.md

# Common issues and solutions
cat docs/troubleshooting.md
```

### 2. Customize Your Configuration

Edit the Nickel configuration files to suit your needs:

```bash
# Master configuration (providers, settings)
vim config/config.ncl

# Infrastructure definition
vim infra/default/main.ncl

# Server configurations
vim infra/default/servers.ncl
```

### 3. Validate Your Configuration

```bash
# Check Nickel syntax
nickel typecheck config/config.ncl
nickel typecheck infra/default/main.ncl

# Validate with provisioning system
provisioning validate config
```

### 4. Add Multiple Infrastructures

To add more infrastructure environments:

```bash
# Create new infrastructure directory
mkdir infra/production
mkdir infra/staging

# Create Nickel files for each infrastructure
cp infra/default/main.ncl infra/production/main.ncl
cp infra/default/servers.ncl infra/production/servers.ncl

# Edit them for your specific needs
vim infra/production/servers.ncl
```

### 5. Configure Providers

To use cloud providers (UpCloud, AWS, etc.), update `config/config.ncl`:

```nickel
providers = {
  upcloud = {
    name = "upcloud",
    enabled = true,              # Set to true to enable
    workspace = "my_workspace",
    auth = { interface = "API" },
    paths = {
      base = ".providers/upcloud",
      cache = ".providers/upcloud/cache",
      state = ".providers/upcloud/state",
    },
    api = {
      url = "https://api.upcloud.com/1.3",
      timeout = 30,
    },
  },
}
```

## Workspace Management Commands

### List Workspaces

```bash
provisioning workspace list
```

### Activate a Workspace

```bash
provisioning workspace activate my_workspace
```

### Show Active Workspace

```bash
provisioning workspace active
```

### Deploy Infrastructure

```bash
# Dry-run first (check mode)
provisioning -c server create

# Actually create servers
provisioning server create

# List created servers
provisioning server list
```

## Troubleshooting

### Invalid Nickel Syntax

```bash
# Check syntax
nickel typecheck config/config.ncl

# Example error and solution
Error: Type checking failed
Solution: Fix the syntax error shown and retry
```

### Configuration Issues

Refer to the auto-generated `docs/troubleshooting.md` in your workspace for:
- Authentication & credentials issues
- Server deployment problems
- Configuration validation errors
- Network connectivity issues
- Performance issues

### Getting Help

1. **Consult workspace guides**: Check the `docs/` directory
2. **Check the docs**: `provisioning --help`, `provisioning workspace --help`
3. **Enable debug mode**: `provisioning --debug server create`
4. **Review logs**: Check logs for detailed error information

## Next Steps

1. **Review auto-generated guides** in `docs/`
2. **Customize configuration** in Nickel files
3. **Test with dry-run** before deployment
4. **Deploy infrastructure**
5. **Monitor and maintain** your workspace

For detailed deployment instructions, see `docs/deployment-guide.md` in your workspace.