# First Deployment

This guide walks you through deploying your first infrastructure using the Provisioning Platform.

## Overview

In this chapter, you'll:

1. Configure a simple infrastructure
2. Create your first server
3. Install a task service (Kubernetes)
4. Verify the deployment

Estimated time: 10-15 minutes

## Step 1: Configure Infrastructure

Create a basic infrastructure configuration:

```bash
# Generate infrastructure template
provisioning generate infra --new my-infra

# This creates: workspace/infra/my-infra/
# - config.toml (infrastructure settings)
# - settings.ncl (Nickel configuration)
```

## Step 2: Edit Configuration

Edit the generated configuration:

```bash
# Edit with your preferred editor
$EDITOR workspace/infra/my-infra/settings.ncl
```

Example configuration:

```kcl
import provisioning.settings as cfg

# Infrastructure settings
infra_settings = cfg.InfraSettings {
    name = "my-infra"
    provider = "local"  # Start with local provider
    environment = "development"
}

# Server configuration
servers = [
    {
        hostname = "dev-server-01"
        cores = 2
        memory = 4096  # MB
        disk = 50  # GB
    }
]
```

## Step 3: Create Server (Check Mode)

First, run in check mode to see what would happen:

```bash
# Check mode - no actual changes
provisioning server create --infra my-infra --check

# Expected output:
# ✓ Validation passed
# ⚠ Check mode: No changes will be made
# 
# Would create:
# - Server: dev-server-01 (2 cores, 4 GB RAM, 50 GB disk)
```

## Step 4: Create Server (Real)

If check mode looks good, create the server:

```bash
# Create server
provisioning server create --infra my-infra

# Expected output:
# ✓ Creating server: dev-server-01
# ✓ Server created successfully
# ✓ IP Address: 192.168.1.100
# ✓ SSH access: ssh user@192.168.1.100
```

## Step 5: Verify Server

Check server status:

```bash
# List all servers
provisioning server list

# Get detailed server info
provisioning server info dev-server-01

# SSH to server (optional)
provisioning server ssh dev-server-01
```

## Step 6: Install Kubernetes (Check Mode)

Install a task service on the server:

```bash
# Check mode first
provisioning taskserv create kubernetes --infra my-infra --check

# Expected output:
# ✓ Validation passed
# ⚠ Check mode: No changes will be made
#
# Would install:
# - Kubernetes v1.28.0
# - Required dependencies: containerd, etcd
# - On servers: dev-server-01
```

## Step 7: Install Kubernetes (Real)

Proceed with installation:

```bash
# Install Kubernetes
provisioning taskserv create kubernetes --infra my-infra --wait

# This will:
# 1. Check dependencies
# 2. Install containerd
# 3. Install etcd
# 4. Install Kubernetes
# 5. Configure and start services

# Monitor progress
provisioning workflow monitor <task-id>
```

## Step 8: Verify Installation

Check that Kubernetes is running:

```bash
# List installed task services
provisioning taskserv list --infra my-infra

# Check Kubernetes status
provisioning server ssh dev-server-01
kubectl get nodes  # On the server
exit

# Or remotely
provisioning server exec dev-server-01 -- kubectl get nodes
```

## Common Deployment Patterns

### Pattern 1: Multiple Servers

Create multiple servers at once:

```kcl
servers = [
    {hostname = "web-01", cores = 2, memory = 4096},
    {hostname = "web-02", cores = 2, memory = 4096},
    {hostname = "db-01", cores = 4, memory = 8192}
]
```

```bash
provisioning server create --infra my-infra --servers web-01,web-02,db-01
```

### Pattern 2: Server with Multiple Task Services

Install multiple services on one server:

```bash
provisioning taskserv create kubernetes,cilium,postgres --infra my-infra --servers web-01
```

### Pattern 3: Complete Cluster

Deploy a complete cluster configuration:

```bash
provisioning cluster create buildkit --infra my-infra
```

## Deployment Workflow

The typical deployment workflow:

```bash
# 1. Initialize workspace
provisioning workspace init production

# 2. Generate infrastructure
provisioning generate infra --new prod-infra

# 3. Configure (edit settings.ncl)
$EDITOR workspace/infra/prod-infra/settings.ncl

# 4. Validate configuration
provisioning validate config --infra prod-infra

# 5. Create servers (check mode)
provisioning server create --infra prod-infra --check

# 6. Create servers (real)
provisioning server create --infra prod-infra

# 7. Install task services
provisioning taskserv create kubernetes --infra prod-infra --wait

# 8. Deploy cluster (if needed)
provisioning cluster create my-cluster --infra prod-infra

# 9. Verify
provisioning server list
provisioning taskserv list
```

## Troubleshooting

### Server Creation Fails

```bash
# Check logs
provisioning server logs dev-server-01

# Try with debug mode
provisioning --debug server create --infra my-infra
```

### Task Service Installation Fails

```bash
# Check task service logs
provisioning taskserv logs kubernetes

# Retry installation
provisioning taskserv create kubernetes --infra my-infra --force
```

### SSH Connection Issues

```bash
# Verify SSH key
ls -la ~/.ssh/

# Test SSH manually
ssh -v user@<server-ip>

# Use provisioning SSH helper
provisioning server ssh dev-server-01 --debug
```

## Next Steps

Now that you've completed your first deployment:
→ **[Verification](04-verification.md)** - Verify your deployment is working correctly

## Additional Resources

- [Complete Deployment Guide](../guides/from-scratch.md)
- [Infrastructure Management](../user/infrastructure-management.md)
- [Troubleshooting Guide](../user/troubleshooting-guide.md)
