# Quick Start

Deploy your first infrastructure in 5 minutes using the Provisioning platform.

## Prerequisites

- [Prerequisites](prerequisites.md) installed
- [Platform installed](installation.md) and CLI accessible
- Cloud provider credentials configured (or local provider)

## 5-Minute Deployment

### Step 1: Create Workspace (30 seconds)

```bash
# Initialize workspace
provisioning workspace init quickstart-demo
cd quickstart-demo
```

Workspace structure created:

```text
quickstart-demo/
├── infra/       # Infrastructure definitions
├── config/      # Workspace configuration
├── extensions/  # Custom providers/taskservs
└── runtime/     # State and logs
```

### Step 2: Define Infrastructure (1 minute)

Create a simple server configuration using Nickel:

```bash
# Create infrastructure schema
cat > infra/demo-server.ncl <<'EOF'
{
  metadata = {
    name = "demo-server"
    provider = "local"  # Use local provider for quick demo
    environment = "development"
  }

  infrastructure = {
    servers = [
      {
        name = "web-01"
        plan = "small"
        role = "web"
      }
    ]
  }

  services = {
    taskservs = ["containerd"]  # Simple container runtime
  }
}
EOF
```

**Using UpCloud or AWS?** Change provider:

```nickel
metadata.provider = "upcloud"  # or "aws"
```

### Step 3: Validate Configuration (30 seconds)

```bash
# Validate Nickel schema
nickel typecheck infra/demo-server.ncl

# Validate provisioning configuration
provisioning validate config

# Preview what will be created
provisioning server create --check --infra demo-server
```

Expected output:

```text
Infrastructure Plan: demo-server
Provider: local
Servers to create: 1
  - web-01 (small, role: web)
Task services: containerd

Estimated resources:
  CPU: 2 cores
  RAM: 2 GB
  Disk: 10 GB
```

### Step 4: Create Infrastructure (2 minutes)

```bash
# Create server
provisioning server create --infra demo-server --yes

# Monitor progress
provisioning server status web-01
```

Progress indicators:

```text
Creating server: web-01...
  [████████████████████████] 100% - Server provisioned
  [████████████████████████] 100% - SSH configured
  [████████████████████████] 100% - Network ready

Server web-01 created successfully
IP Address: 10.0.1.10
Status: running
```

### Step 5: Install Task Service (1 minute)

```bash
# Install containerd
provisioning taskserv create containerd --infra demo-server

# Verify installation
provisioning taskserv status containerd
```

Output:

```text
Installing containerd on web-01...
  [████████████████████████] 100% - Dependencies resolved
  [████████████████████████] 100% - Containerd installed
  [████████████████████████] 100% - Service started
  [████████████████████████] 100% - Health check passed

Containerd v1.7.0 installed successfully
```

### Step 6: Verify Deployment (30 seconds)

```bash
# SSH into server
provisioning server ssh web-01

# Inside server - verify containerd
sudo systemctl status containerd
sudo ctr version

# Exit server
exit
```

## What You've Accomplished

In 5 minutes, you've:

- Created a workspace for infrastructure management
- Defined infrastructure using type-safe Nickel schemas
- Validated configuration before deployment
- Provisioned a server on your chosen provider
- Installed and configured containerd
- Verified the deployment

## Common Workflows

### List Resources

```bash
# List all servers
provisioning server list

# List task services
provisioning taskserv list

# Show workspace info
provisioning workspace info
```

### Modify Infrastructure

```bash
# Edit infrastructure schema
nano infra/demo-server.ncl

# Validate changes
provisioning validate config --infra demo-server

# Apply changes
provisioning server update --infra demo-server
```

### Cleanup

```bash
# Remove task service
provisioning taskserv delete containerd --infra demo-server

# Delete server
provisioning server delete web-01 --yes

# Remove workspace
cd ..
rm -rf quickstart-demo
```

## Next Steps

### Deploy Kubernetes

Ready for something more complex?

```nickel
# infra/kubernetes-cluster.ncl
{
  metadata = {
    name = "k8s-cluster"
    provider = "upcloud"
  }

  infrastructure = {
    servers = [
      {name = "control-01", plan = "medium", role = "control"}
      {name = "worker-01", plan = "large", role = "worker"}
      {name = "worker-02", plan = "large", role = "worker"}
    ]
  }

  services = {
    taskservs = ["kubernetes", "cilium", "rook-ceph"]
  }
}
```

```bash
provisioning server create --infra kubernetes-cluster --yes
provisioning taskserv create kubernetes --infra kubernetes-cluster
```

### Multi-Cloud Deployment

Deploy to multiple providers simultaneously:

```nickel
# infra/multi-cloud.ncl
{
  batch_workflow = {
    operations = [
      {
        id = "aws-cluster"
        provider = "aws"
        servers = [{name = "aws-web-01", plan = "t3.medium"}]
      }
      {
        id = "upcloud-cluster"
        provider = "upcloud"
        servers = [{name = "upcloud-web-01", plan = "medium"}]
      }
    ]
  }
}
```

```bash
provisioning batch submit infra/multi-cloud.ncl
```

### Use Interactive Guides

Access built-in guides for comprehensive walkthroughs:

```bash
# Quick command reference
provisioning sc

# Complete from-scratch guide
provisioning guide from-scratch

# Customization patterns
provisioning guide customize
```

## Troubleshooting Quick Issues

### Server creation fails

```bash
# Check provider connectivity
provisioning providers

# Validate credentials
provisioning validate config

# Enable debug mode
provisioning --debug server create --infra demo-server
```

### Task service installation fails

```bash
# Check server connectivity
provisioning server ssh web-01

# Verify dependencies
provisioning taskserv check-deps containerd

# Retry installation
provisioning taskserv create containerd --infra demo-server --force
```

### Configuration validation errors

```bash
# Check Nickel syntax
nickel typecheck infra/demo-server.ncl

# Show detailed validation errors
provisioning validate config --verbose

# View configuration
provisioning config show
```

## Reference

### Essential Commands

```bash
# Workspace management
provisioning workspace init <name>
provisioning workspace list
provisioning workspace switch <name>

# Server operations
provisioning server create --infra <name>
provisioning server list
provisioning server status <hostname>
provisioning server ssh <hostname>
provisioning server delete <hostname>

# Task service operations
provisioning taskserv create <service> --infra <name>
provisioning taskserv list
provisioning taskserv status <service>
provisioning taskserv delete <service>

# Configuration
provisioning config show
provisioning validate config
provisioning env
```

### Quick Reference

```bash
# Shortcut for fastest reference
provisioning sc
```

## Further Reading

- [First Deployment](first-deployment.md) - Comprehensive walkthrough
- [Verification](verification.md) - Platform health checks
- [Workspace Management](../guides/workspace-management.md) - Advanced workspace usage
- [Nickel Guide](../infrastructure/nickel-guide.md) - Infrastructure-as-code patterns
