provisioning/templates/docs

# Workspace {{ workspace_name | title }} Documentation

**Complete guide for deploying and managing {{ workspace_name }} infrastructure**

---

## Overview

This documentation covers deployment, configuration, and troubleshooting for the **{{ workspace_name }}** workspace.

**Key Details**:
- **Location**: {{ workspace_path }}
- **Provider**: {{ primary_provider | title }}{% if primary_zone %} ({{ primary_zone }}){% endif %}
- **Infrastructures**: {{ infrastructures | join(sep=', ') | title }}
- **Estimated Cost**: {{ pricing_estimate }}

---

## Documentation Files

### 1. [Deployment Guide](deployment-guide.md)
**Purpose**: Step-by-step deployment instructions

**Sections**:
- Prerequisites verification
- Credentials setup ({{ primary_provider | title }})
- SSH key configuration
- Workspace activation
- Server deployment
- Service installation
- Verification and monitoring
- Cleanup procedures

**When to use**: Follow this guide to deploy infrastructure from scratch.

---

### 2. [Configuration Guide](configuration-guide.md)
**Purpose**: Configuration reference and options

**Sections**:
- Configuration hierarchy
- Master configuration
- Provider configuration
- Infrastructure settings
- Server definitions
- Task services configuration
- Validation procedures
- Common configuration changes

**When to use**: Consult when modifying workspace configuration.

---

### 3. [Troubleshooting Guide](troubleshooting.md)
**Purpose**: Solutions for common issues

**Sections**:
- Authentication & credentials issues
- Server deployment problems
- Configuration validation errors
- Service installation failures
- Network connectivity issues
- Performance issues
- Debug procedures
- Diagnosis checklist

**When to use**: Consult when deployment fails or issues occur.

---

## Quick Start

### First Time Deployment

1. **Read Installation Guide**:
   ```bash
   cat provisioning/docs/src/getting-started/installation-validation-guide.md
   ```

2. **Follow Deployment Guide**:
   ```bash
   cat docs/deployment-guide.md
   ```

3. **Verify Deployment**:
   ```bash
   provisioning server list
   provisioning price --infra {{ default_infra }}
   ```

### Modify Configuration

1. **Review Options**: Read `configuration-guide.md`
2. **Make Changes**: Edit `infra/{{ default_infra }}/servers.ncl`
3. **Validate**: `nickel typecheck infra/{{ default_infra }}/main.ncl`
4. **Deploy**: `provisioning -c server create --infra {{ default_infra }}`

### Troubleshoot Issues

1. **Find Issue**: Search in `troubleshooting.md`
2. **Follow Solutions**: Execute recommended steps
3. **Check Logs**: `tail -f provisioning/platform/orchestrator/data/orchestrator.log`

---

## Workspace Overview

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

**Purpose**: {{ infrastructure_purposes[infra] }}

**Location**: `infra/{{ infra }}/`

**Servers**:
{% for server in servers %}
- `{{ server.name }}` - {{ server.plan }} ({{ server.storage }}GB storage)
{% endfor %}

**Services**:
{% for service in taskservs %}
- {{ service }}
{% endfor %}

**Provider**: {{ primary_provider | title }}{% if primary_zone %} ({{ primary_zone }} zone){% endif %}

{% endfor %}
---

## Prerequisites

Before using this workspace:

1. **Complete Installation Validation**
   - Read: `provisioning/docs/src/getting-started/installation-validation-guide.md`
   - Verify all prerequisites installed

2. **Have Provider Account**
   - Account at {{ provider_url }}
   - API credentials available
   - Sufficient account balance

3. **Have SSH Key**
   - Generate: `ssh-keygen -t ed25519 -f ~/.ssh/id_deployment`
   - Location: `~/.ssh/id_deployment.pub`

---

## Key Commands

### Workspace Management

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

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

# Check active workspace
provisioning workspace active

# Validate workspace
nu workspace.nu validate
```

### Server Management

```bash
# List servers
provisioning server list --infra {{ default_infra }}

# Check pricing
provisioning price --infra {{ default_infra }}

# Dry-run deployment
provisioning -c server create --infra {{ default_infra }}

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

# SSH to server
provisioning server ssh {{ servers[0].name }}

# Delete servers
provisioning server delete --infra {{ default_infra }}
```

### Configuration Management

```bash
# Validate Nickel files
nickel typecheck config/config.ncl
nickel typecheck infra/{{ default_infra }}/main.ncl

# Validate workspace
nu workspace.nu validate

# Export configuration
provisioning config export
```

---

## Common Workflows

### Complete Deployment

```bash
# 1. Activate workspace
provisioning workspace activate {{ workspace_name }}:{{ default_infra }}

# 2. Check pricing
provisioning price --infra {{ default_infra }}

# 3. Dry-run
provisioning -c server create --infra {{ default_infra }}

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

# 5. Verify
provisioning server list --infra {{ default_infra }}
```

### Update Configuration

```bash
# 1. Make changes
vim infra/{{ default_infra }}/servers.ncl

# 2. Validate
nickel typecheck infra/{{ default_infra }}/main.ncl

# 3. Dry-run
provisioning -c server create --infra {{ default_infra }}

# 4. Deploy
provisioning server create --infra {{ default_infra }}
```

### Cleanup

```bash
# 1. Delete servers
provisioning server delete --infra {{ default_infra }}

# 2. Clean cache
provisioning cache clean
rm -rf {{ workspace_path }}/.providers/*/state/*

# 3. Verify
provisioning server list --infra {{ default_infra }}
```

---

## Workspace Structure

```
{{ workspace_path }}/
├── docs/                           # This directory
│   ├── README.md                  # Overview and quick start
│   ├── deployment-guide.md        # Deployment instructions
│   ├── configuration-guide.md     # Configuration reference
│   └── troubleshooting.md         # Common issues
│
├── config/                         # Workspace configuration
│   ├── config.ncl                 # Master Nickel config
│   ├── kms.toml                   # KMS configuration
│   ├── providers/                 # Provider configs
│   └── generated/                 # Exported TOML files
│
├── infra/                          # Infrastructure definitions
{% for infra in infrastructures %}
│   ├── {{ infra }}/              # {{ infra | title }} infrastructure
│   │   ├── main.ncl              # Main entry point
│   │   ├── settings.ncl          # Settings
│   │   ├── servers.ncl           # Server definitions
│   │   └── taskservs/            # Task services
{% endfor %}
│
├── .providers/                     # Provider modules
├── .taskservs/                     # Task service modules
├── .kms/                           # KMS data
├── data/                           # Runtime data (cache, prices)
│
├── workspace.nu                    # Workspace utility
└── README.md                       # Workspace overview (root)
```

---

## Support & Resources

### Documentation

- **Installation**: `provisioning/docs/src/getting-started/installation-validation-guide.md`
- **Deployment**: `docs/deployment-guide.md`
- **Configuration**: `docs/configuration-guide.md`
- **Troubleshooting**: `docs/troubleshooting.md`

### External Resources

- **{{ primary_provider | title }}**: {{ provider_url }}
- **{{ primary_provider | title }} API**: {{ provider_api_url }}
- **Kubernetes**: https://kubernetes.io/docs/

### Getting Help

**For Deployment Issues**:
- See Deployment section in troubleshooting.md
- Check logs: `tail -f provisioning/platform/orchestrator/data/orchestrator.log`
- Enable debug: `provisioning --debug server create --infra {{ default_infra }}`

**For Configuration Issues**:
- See Configuration section in troubleshooting.md
- Review examples in configuration-guide.md
- Validate: `nickel typecheck config/config.ncl`

**For Service Issues**:
- See Service Installation section in troubleshooting.md
- Check service status: `provisioning taskserv list --infra {{ default_infra }}`

---

## Next Steps

1. **Start with Installation Validation**
   - Read: `provisioning/docs/src/getting-started/installation-validation-guide.md`

2. **Follow Deployment Guide**
   - Read: `docs/deployment-guide.md`
   - Execute step-by-step

3. **Modify Configuration (Optional)**
   - Read: `docs/configuration-guide.md`
   - Make needed changes

4. **Troubleshoot if Issues**
   - Read: `docs/troubleshooting.md`
   - Find and fix issues

---

**Workspace**: {{ workspace_name }}
**Location**: {{ workspace_path }}
**Provider**: {{ primary_provider | title }}
**Infrastructures**: {{ infrastructures | join(sep=', ') | title }}
**Generated**: 2025-01-07