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:

{
  "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

# 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

# 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

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

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

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

# 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

[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)

fail_fast = true
cleanup_on_failure = true

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

Continue on Error

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

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

Discord

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

Custom API

[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:

{
  "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

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

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

Verbose Logging

verbose = true

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

Common Issues

Issue: Webhook notifications failing

# Increase retry attempts
[notifications]
retry_attempts = 5

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

Issue: Services not starting

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

Issue: Cleanup failing

# Disable cleanup to inspect state
cleanup_on_failure = false

Advanced Usage

Custom Deployment Steps

Extend the installer by modifying runner.rs:

// 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

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

Multi-Stage Deployments

# 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):

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.