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)

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

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:

{
  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:

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

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:

# 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

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

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

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

provisioning workspace list

Activate a Workspace

provisioning workspace activate my_workspace

Show Active Workspace

provisioning workspace active

Deploy Infrastructure

# 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

# 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.