provisioning/templates/docs/deployment-guide.md.j2

# Workspace {{ workspace_name | title }} - Deployment Guide

**Workspace**: {{ workspace_name }}
**Location**: {{ workspace_path }}
**Provider**: {{ primary_provider | title }}{% if primary_zone %} ({{ primary_zone }} zone){% endif %}
**Active Infrastructures**: {{ infrastructures | join(sep=', ') }}

---

## Overview

This guide provides step-by-step instructions for deploying the **{{ workspace_name }}** infrastructure.

{% for infra in infrastructures %}
### Infrastructure: {{ infra | title }}

**Purpose**: {{ infrastructure_purposes[infra] }}
**Location**: `infra/{{ infra }}/`

{% endfor %}

---

## Prerequisites

Before deploying, ensure you have completed:

1. **Installation Validation Guide**
   - Available at: `provisioning/docs/src/getting-started/installation-validation-guide.md`
   - Verify all prerequisites are installed

2. **Required Tools**
   - Nushell 0.109.0+
   - Nickel 1.x.x
   - Docker 20.10+
   - macOS, Linux, or WSL2

3. **Provider Credentials**
   {% for provider in providers %}
   - {{ provider | title }} account and credentials
   {% endfor %}

4. **SSH Key**
   - Location: `~/.ssh/id_deployment.pub`
   - Generate if missing: `ssh-keygen -t ed25519 -f ~/.ssh/id_deployment`

---

## Section 1: Credentials Setup

### Step 1.1: {{ primary_provider | title }} Credentials

**Option A: Environment Variables**

```bash
{% for var, hint in provider_env_vars %}
export {{ var }}="{{ hint }}"
{% endfor %}
```

**Option B: Configuration File**

Create `~/.config/{{ primary_provider | lower }}.yaml`:

```yaml
{% for key, value in provider_config_example %}
{{ key }}: {{ value }}
{% endfor %}
```

### Step 1.2: Verify Credentials

```bash
# Test provider connectivity
provisioning -c server create --infra {{ default_infra }}
```

Expected: Shows servers to be created (dry-run check, no resources created)

---

## Section 2: SSH Key Configuration

### Step 2.1: Verify SSH Key

```bash
ls -la ~/.ssh/id_deployment.pub
```

### Step 2.2: Generate SSH Key (if needed)

```bash
ssh-keygen -t ed25519 -f ~/.ssh/id_deployment -C "provisioning@{{ workspace_name }}"
```

### Step 2.3: Update Configuration (if needed)

**File**: `infra/{{ default_infra }}/servers.ncl`

```nickel
ssh_key_path = "~/.ssh/id_deployment.pub"
```

---

## Section 3: Workspace Activation

### Step 3.1: Register Workspace

```bash
provisioning workspace register {{ workspace_name }} {{ workspace_path }}
```

### Step 3.2: Activate Workspace

```bash
provisioning workspace activate {{ workspace_name }}:{{ default_infra }}
```

### Step 3.3: Verify Configuration

```bash
cd {{ workspace_path }}

# Validate Nickel syntax
{% for infra in infrastructures -%}
nickel typecheck infra/{{ infra }}/main.ncl
{% endfor %}

# Workspace validation
nu workspace.nu validate
```

---

## Section 4: Pre-Deployment Review

### Step 4.1: Review Infrastructure Configuration

```bash
cd {{ workspace_path }}

# View server definitions
cat infra/{{ default_infra }}/servers.ncl
```

Expected servers:
{% for server in servers -%}
- {{ server.name }} ({{ server.plan }}, {{ server.storage }}GB)
{% endfor %}

### Step 4.2: Check Pricing

```bash
provisioning price --infra {{ default_infra }}
```

Expected monthly cost: {{ pricing_estimate }}

### Step 4.3: Dry-Run Deployment

```bash
provisioning -c server create --infra {{ default_infra }}
```

---

## Section 5: Deploy Servers

**⚠️ WARNING: This creates REAL resources and incurs COSTS**

### Pre-Deployment Checklist

```
[ ] Provider credentials configured and tested
[ ] SSH key exists and path is correct
[ ] Workspace activated
[ ] Configuration validated
[ ] Dry-run passed
[ ] Pricing reviewed and acceptable
```

### Step 5.1: Create Servers

```bash
cd {{ workspace_path }}/infra/{{ default_infra }}

provisioning server create
```

Expected duration: 2-5 minutes

### Step 5.2: Verify Deployment

```bash
provisioning server list --infra {{ default_infra }}
```

### Step 5.3: Test SSH Connectivity

```bash
provisioning server ssh {{ servers[0].name }} --command "uptime"
```

---

## Section 6: Install Services (Optional)

Once servers are deployed, install services:

{% for service in taskservs -%}
### Install {{ service | title }}

```bash
provisioning taskserv create {{ service }} --infra {{ default_infra }}
```

{% endfor %}

Verify all services:

```bash
provisioning taskserv list --infra {{ default_infra }}
```

---

## Section 7: Verification & Monitoring

### Step 7.1: Server Health Check

```bash
provisioning server list --infra {{ default_infra }}
```

Expected: All servers showing "running" status

### Step 7.2: Network Connectivity

```bash
{% if servers %}
# Test connectivity between servers
ssh root@{{ servers[0].name }} "ping -c 3 {{ servers[0].name }}"
{% endif %}
```

### Step 7.3: Monitor Workflows

```bash
provisioning workflow list
provisioning workflow monitor <workflow_id>
```

---

## Section 8: Troubleshooting

See `docs/troubleshooting.md` for common issues and solutions.

**Quick Reference**:
- Authentication issues: Check provider credentials
- SSH failures: Wait 2-3 minutes for server boot
- Service installation errors: Check server resources

---

## Section 9: Cleanup & Teardown

### Step 9.1: Delete Servers

```bash
cd {{ workspace_path }}/infra/{{ default_infra }}

provisioning server delete
```

### Step 9.2: Clean Cache

```bash
provisioning cache clean
rm -rf {{ workspace_path }}/.providers/*/state/*
```

---

## Quick Reference Commands

```bash
# Setup
cd {{ workspace_path }}

# Activate
provisioning workspace activate {{ workspace_name }}:{{ default_infra }}

# Validate
provisioning -c server create --infra {{ default_infra }}

# Deploy
provisioning server create --infra {{ default_infra }}

# Verify
provisioning server list --infra {{ default_infra }}

# Cleanup
provisioning server delete --infra {{ default_infra }}
provisioning cache clean
```

---

## Next Steps

After deployment:
1. Configure applications
2. Set up monitoring
3. Plan backup strategy
4. Configure security

For more information, see:
- Configuration Guide: `docs/configuration-guide.md`
- Troubleshooting Guide: `docs/troubleshooting.md`
- Installation Guide: `provisioning/docs/src/getting-started/installation-validation-guide.md`