prvng_platform/installer/docs/UNATTENDED_MODE.md

# Unattended Installation Mode

**Version**: 3.5.0
**Status**: Production Ready
**Suitable for**: CI/CD pipelines, automation, infrastructure as code

## Overview

The unattended installation mode provides fully automated deployment without any user interaction. This mode is designed for:

- **CI/CD Pipelines**: Jenkins, GitLab CI, GitHub Actions
- **Infrastructure as Code**: Terraform, Ansible, CloudFormation
- **Automated Deployments**: Scheduled deployments, auto-scaling
- **Testing Environments**: Automated test infrastructure setup

## Features

### Core Capabilities

- ✅ **Zero User Interaction**: Complete automation, no prompts
- ✅ **Configuration-Driven**: TOML-based configuration files
- ✅ **Webhook Notifications**: Real-time progress updates
- ✅ **Failure Recovery**: Automatic cleanup on failure
- ✅ **Progress Tracking**: Step-by-step execution monitoring
- ✅ **Dependency Resolution**: Automatic service dependency handling
- ✅ **Multi-Platform Support**: Docker, Podman, Kubernetes, OrbStack

### Notification System

The notification system sends webhook updates for:

- **Installation Started**: Initial notification with metadata
- **Progress Updates**: Real-time step execution progress
- **Step Completion**: Individual step success notifications
- **Installation Complete**: Final success notification
- **Failure Alerts**: Error notifications with context

Notification payload structure:

```json
{
  "event": "progress",
  "installation_id": "kubernetes-1.28.0-20250106-143022",
  "timestamp": 1704550222,
  "current_step": "deploy-docker",
  "progress": 60,
  "completed_steps": 4,
  "total_steps": 7,
  "error": null,
  "metadata": {}
}
```

## Quick Start

### 1. Basic Usage

```bash
# Use pre-configured example
provisioning-installer --unattended --config provisioning/config/installer-examples/solo.toml

# With custom configuration
provisioning-installer --unattended --config /path/to/custom-config.toml
```

### 2. Available Example Configurations

| Configuration | Mode | Platform | Use Case |
|--------------|------|----------|----------|
| `solo.toml` | Solo | Docker | Single developer, local development |
| `multi-user.toml` | MultiUser | Docker | Team collaboration with Git |
| `cicd.toml` | CICD | Docker | CI/CD automation |
| `enterprise.toml` | Enterprise | Kubernetes | Production deployment |

### 3. Configuration Structure

```toml
# Installation metadata
installation_id = "my-deployment-001"
verbose = true
fail_fast = true
cleanup_on_failure = true

# Paths
provisioning_path = "/usr/local/bin/provisioning"
work_dir = "~/.provisioning"

# Deployment settings
[deployment]
platform = "Docker"
mode = "Solo"
domain = "localhost"
auto_generate_secrets = true

# Services
[[deployment.services]]
name = "orchestrator"
description = "Task coordination"
port = 8080
enabled = true
required = true

# Notifications (optional)
[notifications]
webhook_url = "https://example.com/webhook"
notify_progress = true
notify_completion = true
notify_failure = true
retry_attempts = 3

# Environment variables
[env_vars]
LOG_LEVEL = "info"
```

## CI/CD Integration

### GitHub Actions

```yaml
name: Deploy Provisioning Platform
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install provisioning-installer
        run: cargo install --path provisioning/platform/installer

      - name: Deploy in unattended mode
        run: |
          provisioning-installer \
            --unattended \
            --config provisioning/config/installer-examples/cicd.toml
        env:
          WEBHOOK_URL: ${{ secrets.WEBHOOK_URL }}
```

### GitLab CI

```yaml
deploy:
  stage: deploy
  image: rust:latest
  script:
    - cargo install --path provisioning/platform/installer
    - |
      provisioning-installer \
        --unattended \
        --config provisioning/config/installer-examples/cicd.toml
  only:
    - main
```

### Jenkins

```groovy
pipeline {
    agent any
    stages {
        stage('Deploy') {
            steps {
                sh '''
                    cargo install --path provisioning/platform/installer
                    provisioning-installer \
                        --unattended \
                        --config provisioning/config/installer-examples/cicd.toml
                '''
            }
        }
    }
}
```

## Taskserv Self-Install

The Kubernetes taskserv includes a self-install script that integrates with MCP:

### Usage

```bash
# Query MCP and install automatically
./provisioning/extensions/taskservs/kubernetes/self-install.nu \
    --mcp-url http://localhost:8084 \
    --workspace production \
    --infra k8s-cluster \
    --platform Docker \
    --domain k8s.example.com \
    --webhook-url https://example.com/webhook

# Generate sample config
./provisioning/extensions/taskservs/kubernetes/self-install.nu sample \
    --output kubernetes-install.toml

# Dry-run (generate config without installing)
./provisioning/extensions/taskservs/kubernetes/self-install.nu \
    --dry-run \
    --config-output kubernetes-config.toml
```

### MCP Integration

The self-install script:

1. **Queries MCP** for taskserv configuration
2. **Resolves dependencies** (containerd, etcd, cilium, etc.)
3. **Generates installer config** with all dependencies
4. **Runs unattended installation** automatically
5. **Sends notifications** for progress tracking

## Configuration Reference

### Top-Level Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `installation_id` | string | No | Unique installation identifier (auto-generated) |
| `verbose` | bool | No | Enable verbose logging (default: false) |
| `fail_fast` | bool | No | Stop on first error (default: true) |
| `cleanup_on_failure` | bool | No | Cleanup resources on failure (default: true) |
| `provisioning_path` | string | No | Path to provisioning CLI |
| `work_dir` | string | No | Working directory for installation |

### Deployment Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `platform` | enum | Yes | Docker, Podman, Kubernetes, OrbStack |
| `mode` | enum | Yes | Solo, MultiUser, CICD, Enterprise |
| `domain` | string | Yes | Domain/hostname for services |
| `auto_generate_secrets` | bool | No | Auto-generate secrets (default: true) |
| `services` | array | Yes | List of services to deploy |

### Service Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Service name |
| `description` | string | Yes | Service description |
| `port` | int | Yes | Service port (0 for no port) |
| `enabled` | bool | Yes | Enable service |
| `required` | bool | Yes | Service is required |

### Notification Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `webhook_url` | string | Yes | Webhook URL for notifications |
| `notify_progress` | bool | No | Send progress notifications (default: true) |
| `notify_completion` | bool | No | Send completion notification (default: true) |
| `notify_failure` | bool | No | Send failure notification (default: true) |
| `retry_attempts` | int | No | Retry attempts for webhook (default: 3) |
| `headers` | map | No | Custom HTTP headers |

### Environment Variables

```toml
[env_vars]
LOG_LEVEL = "info"
ENABLE_DEBUG = "false"
PROVISIONING_MODE = "production"
# Add any custom environment variables
```

## Deployment Steps

The unattended installer executes these steps:

1. **Validate Prerequisites**: Check system requirements
2. **Create Work Directory**: Set up working directory
3. **Generate Secrets**: Auto-generate encryption keys (if enabled)
4. **Generate Configuration**: Create deployment configuration
5. **Deploy Platform**: Deploy to selected platform
6. **Wait for Services**: Wait for services to become healthy
7. **Verify Deployment**: Verify all services are running

Each step sends notifications and can be monitored in real-time.

## Error Handling

### Fail-Fast Mode (default)

```toml
fail_fast = true
cleanup_on_failure = true
```

- Stops on first error
- Automatically cleans up resources
- Sends failure notification with error details

### Continue on Error

```toml
fail_fast = false
cleanup_on_failure = false
```

- Continues through errors where possible
- Keeps state for debugging
- Collects all errors before failing

## Webhook Integration

### Example Webhook Endpoints

#### Slack

```toml
[notifications]
webhook_url = "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
notify_progress = true
notify_completion = true
notify_failure = true
```

#### Discord

```toml
[notifications]
webhook_url = "https://discord.com/api/webhooks/YOUR/WEBHOOK"
notify_progress = true
notify_completion = true
notify_failure = true
```

#### Custom API

```toml
[notifications]
webhook_url = "https://api.example.com/webhooks/provisioning"
notify_progress = true
notify_completion = true
notify_failure = true
retry_attempts = 5

[notifications.headers]
Content-Type = "application/json"
Authorization = "Bearer ${API_TOKEN}"
X-Custom-Header = "provisioning-installer"
```

### Webhook Payload

All webhooks receive JSON payloads:

```json
{
  "event": "started|progress|step_completed|completed|failed",
  "installation_id": "unique-id",
  "timestamp": 1704550222,
  "current_step": "Step description",
  "progress": 0-100,
  "completed_steps": 0,
  "total_steps": 7,
  "error": "Error message (if failed)",
  "metadata": {}
}
```

## Troubleshooting

### Configuration Validation

```bash
# Validate configuration syntax
cat my-config.toml | toml validate

# Test configuration loading
provisioning-installer --unattended --config my-config.toml --dry-run
```

### Verbose Logging

```toml
verbose = true

[env_vars]
LOG_LEVEL = "debug"
ENABLE_DEBUG = "true"
```

### Common Issues

**Issue**: Webhook notifications failing

```toml
# Increase retry attempts
[notifications]
retry_attempts = 5

# Add authentication
[notifications.headers]
Authorization = "Bearer ${TOKEN}"
```

**Issue**: Services not starting

```toml
# Disable fail-fast to see all errors
fail_fast = false
verbose = true
```

**Issue**: Cleanup failing

```toml
# Disable cleanup to inspect state
cleanup_on_failure = false
```

## Advanced Usage

### Custom Deployment Steps

Extend the installer by modifying `runner.rs`:

```rust
// Add custom deployment step
steps.push(DeploymentStep::new(
    "custom-step",
    "My custom deployment step",
    "/path/to/script.sh",
    vec!["arg1".to_string(), "arg2".to_string()],
));
```

### Environment Variable Substitution

```toml
[env_vars]
DATABASE_URL = "${DB_HOST}:${DB_PORT}"
API_KEY = "${SECRET_API_KEY}"
```

### Multi-Stage Deployments

```bash
# Stage 1: Core services
provisioning-installer --unattended --config stage1-core.toml

# Stage 2: Application services
provisioning-installer --unattended --config stage2-apps.toml

# Stage 3: Monitoring
provisioning-installer --unattended --config stage3-monitoring.toml
```

## Security Considerations

### Secrets Management

- ✅ Use `auto_generate_secrets = true` for automatic secret generation
- ✅ Never commit secrets to configuration files
- ✅ Use environment variable substitution for sensitive data
- ✅ Integrate with external secret managers (Vault, AWS Secrets Manager)

### Webhook Security

- ✅ Use HTTPS webhooks only
- ✅ Add authentication headers
- ✅ Validate webhook signatures
- ✅ Rate limit webhook endpoints

### Access Control

- ✅ Restrict configuration file permissions (600)
- ✅ Run installer with least privilege
- ✅ Audit installation logs
- ✅ Monitor webhook notifications

## API Integration

Load configuration from JSON (for API/MCP integration):

```rust
use provisioning_installer::UnattendedConfig;

let json = r#"{
  "deployment": {
    "platform": "Docker",
    "mode": "Solo",
    "domain": "localhost",
    "auto_generate_secrets": true,
    "services": []
  }
}"#;

let config = UnattendedConfig::from_json(json)?;
```

## Examples

See `provisioning/config/installer-examples/` for complete examples:

- **solo.toml**: Minimal single-developer setup
- **multi-user.toml**: Team collaboration with Git
- **cicd.toml**: CI/CD pipeline configuration
- **enterprise.toml**: Full production deployment

## Support

For issues or questions:

- GitHub Issues: https://github.com/your-org/provisioning/issues
- Documentation: https://docs.example.com/installer
- Community: https://community.example.com

## License

See LICENSE file in the repository root.