provisioning/docs/src/guides/workspace-generation-quick-reference.md

Workspace Generation - Quick Reference

Updated for Nickel-based workspaces with auto-generated documentation

Quick Start: Create a Workspace

# Interactive mode (recommended)
provisioning workspace init

# Non-interactive mode with explicit path
provisioning workspace init my_workspace /path/to/my_workspace

# With activation
provisioning workspace init my_workspace /path/to/my_workspace --activate

What Gets Created Automatically

When you run provisioning workspace init, the system creates:

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

Key Files Created

Master Configuration: config/config.ncl

{
  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",
      },
    },
  },
}

Infrastructure: infra/default/main.ncl

{
  workspace_name = "my_workspace",
  infrastructure = "default",
  servers = [
    {
      hostname = "my-workspace-server-0",
      provider = "local",
      plan = "1xCPU-2 GB",
      zone = "local",
      storages = [{total = 25}],
    },
  ],
}

Auto-Generated Guides

Every workspace includes 4 auto-generated guides in the docs/ directory:

Guide	Content
README.md	Workspace overview, quick start, and structure
deployment-guide.md	Step-by-step deployment for your infrastructure
configuration-guide.md	Configuration options specific to your setup
troubleshooting.md	Solutions for common issues

These guides are customized for your workspace's:

• Configured providers
• Infrastructure definitions
• Server configurations
• Platform services

Initialization Process (8 Steps)

STEP 1: Create directory structure
        └─ workspace/, config/, infra/default/, etc.

STEP 2: Generate Nickel configuration
        ├─ config/config.ncl (master config)
        └─ infra/default/*.ncl (infrastructure files)

STEP 3: Configure providers
        └─ Setup local provider (default)

STEP 4: Initialize metadata
        └─ .provisioning/metadata.yaml

STEP 5: Activate workspace (if requested)
        └─ Set as default workspace

STEP 6: Create .gitignore
        └─ Workspace-specific ignore rules

STEP 7: ✨ GENERATE DOCUMENTATION
        ├─ Extract workspace metadata
        ├─ Render 4 workspace guides
        └─ Place in docs/ directory

STEP 8: Display summary
        └─ Show workspace path and documentation location

Common Commands

Workspace Management

# Create interactive workspace
provisioning workspace init

# Create with explicit path and activate
provisioning workspace init my_workspace /path/to/workspace --activate

# List all workspaces
provisioning workspace list

# Activate workspace
provisioning workspace activate my_workspace

# Show active workspace
provisioning workspace active

Configuration

# Validate Nickel configuration
nickel typecheck config/config.ncl
nickel typecheck infra/default/main.ncl

# Validate with provisioning system
provisioning validate config

Deployment

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

# Actual deployment
provisioning server create

# List servers
provisioning server list

Workspace Directory Structure

Auto-Generated Structure

my_workspace/
├── config/
│   ├── config.ncl                 # Master configuration
│   ├── providers/                 # Provider configs
│   └── platform/                  # Platform configs
│
├── infra/
│   └── default/
│       ├── main.ncl              # Infrastructure definition
│       └── servers.ncl           # Server definitions
│
├── docs/                         # AUTO-GENERATED GUIDES
│   ├── README.md                # Workspace overview
│   ├── 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

Customization Guide

Edit Configuration

# Master workspace configuration
vim config/config.ncl

# Infrastructure definition
vim infra/default/main.ncl

# Server definitions
vim infra/default/servers.ncl

Add Multiple Infrastructures

# Create new infrastructure environment
mkdir -p infra/production infra/staging

# Copy template files
cp infra/default/main.ncl infra/production/main.ncl
cp infra/default/servers.ncl infra/production/servers.ncl

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

Configure Providers

Update config/config.ncl to enable cloud providers:

providers = {
  upcloud = {
    name = "upcloud",
    enabled = true,              # Set to true
    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,
    },
  },
}

Next Steps

1. Read auto-generated guides in docs/
2. Customize configuration in Nickel files
3. Validate with: nickel typecheck config/config.ncl
4. Test deployment with dry-run mode: provisioning -c server create
5. Deploy infrastructure when ready

Documentation References

• Workspace Setup Guide - Complete setup instructions
• Workspace Switching Guide - Managing multiple workspaces
• Infrastructure Guide - Infrastructure details