# Getting Started Guide\n\nWelcome to Infrastructure Automation. This guide will walk you through your first steps with infrastructure automation, from basic setup to deploying\nyour first infrastructure.\n\n## What You'll Learn\n\n- Essential concepts and terminology\n- How to configure your first environment\n- Creating and managing infrastructure\n- Basic server and service management\n- Common workflows and best practices\n\n## Prerequisites\n\nBefore starting this guide, ensure you have:\n\n- ✅ Completed the [Installation Guide](installation-guide.md)\n- ✅ Verified your installation with `provisioning --version`\n- ✅ Basic familiarity with command-line interfaces\n\n## Essential Concepts\n\n### Infrastructure as Code (IaC)\n\nProvisioning uses **declarative configuration** to manage infrastructure. Instead of manually creating resources, you define what you want in\nconfiguration files, and the system makes it happen.\n\n```\nYou describe → System creates → Infrastructure exists\n```\n\n### Key Components\n\n| Component | Purpose | Example |\n| ----------- | --------- | --------- |\n| **Providers** | Cloud platforms | AWS, UpCloud, Local |\n| **Servers** | Virtual machines | Web servers, databases |\n| **Task Services** | Infrastructure software | Kubernetes, Docker, databases |\n| **Clusters** | Grouped services | Web cluster, database cluster |\n\n### Configuration Languages\n\n- **Nickel**: Primary configuration language for infrastructure definitions (type-safe, validated)\n- **TOML**: User preferences and system settings\n- **YAML**: Kubernetes manifests and service definitions\n\n## First-Time Setup\n\n### Step 1: Initialize Your Configuration\n\nCreate your personal configuration:\n\n```\n# Initialize user configuration\nprovisioning init config\n\n# This creates ~/.provisioning/config.user.toml\n```\n\n### Step 2: Verify Your Environment\n\n```\n# Check your environment setup\nprovisioning env\n\n# View comprehensive configuration\nprovisioning allenv\n```\n\nYou should see output like:\n\n```\n✅ Configuration loaded successfully\n✅ All required tools available\n📁 Base path: /usr/local/provisioning\n🏠 User config: ~/.provisioning/config.user.toml\n```\n\n### Step 3: Explore Available Resources\n\n```\n# List available providers\nprovisioning list providers\n\n# List available task services\nprovisioning list taskservs\n\n# List available clusters\nprovisioning list clusters\n```\n\n## Your First Infrastructure\n\nLet's create a simple local infrastructure to learn the basics.\n\n### Step 1: Create a Workspace\n\n```\n# Create a new workspace directory\nmkdir ~/my-first-infrastructure\ncd ~/my-first-infrastructure\n\n# Initialize workspace\nprovisioning generate infra --new local-demo\n```\n\nThis creates:\n\n```\nlocal-demo/\n├── config/\n│   └── config.ncl     # Master Nickel configuration\n├── infra/\n│   └── default/\n│       ├── main.ncl   # Infrastructure definition\n│       └── servers.ncl # Server configurations\n└── docs/              # Auto-generated guides\n```\n\n### Step 2: Examine the Configuration\n\n```\n# View the generated configuration\nprovisioning show settings --infra local-demo\n```\n\n### Step 3: Validate the Configuration\n\n```\n# Validate syntax and structure\nprovisioning validate config --infra local-demo\n\n# Should show: ✅ Configuration validation passed!\n```\n\n### Step 4: Deploy Infrastructure (Check Mode)\n\n```\n# Dry run - see what would be created\nprovisioning server create --infra local-demo --check\n\n# This shows planned changes without making them\n```\n\n### Step 5: Create Your Infrastructure\n\n```\n# Create the actual infrastructure\nprovisioning server create --infra local-demo\n\n# Wait for completion\nprovisioning server list --infra local-demo\n```\n\n## Working with Services\n\n### Installing Your First Service\n\nLet's install a containerized service:\n\n```\n# Install Docker/containerd\nprovisioning taskserv create containerd --infra local-demo\n\n# Verify installation\nprovisioning taskserv list --infra local-demo\n```\n\n### Installing Kubernetes\n\nFor container orchestration:\n\n```\n# Install Kubernetes\nprovisioning taskserv create kubernetes --infra local-demo\n\n# This may take several minutes...\n```\n\n### Checking Service Status\n\n```\n# Show all services on your infrastructure\nprovisioning show servers --infra local-demo\n\n# Show specific service details\nprovisioning show servers web-01 taskserv kubernetes --infra local-demo\n```\n\n## Understanding Commands\n\n### Command Structure\n\nAll commands follow this pattern:\n\n```\nprovisioning [global-options] <command> [command-options] [arguments]\n```\n\n### Global Options\n\n| Option | Short | Description |\n| -------- | ------- | ------------- |\n| `--infra` | `-i` | Specify infrastructure |\n| `--check` | `-c` | Dry run mode |\n| `--debug` | `-x` | Enable debug output |\n| `--yes` | `-y` | Auto-confirm actions |\n\n### Essential Commands\n\n| Command | Purpose | Example |\n| --------- | --------- | --------- |\n| `help` | Show help | `provisioning help` |\n| `env` | Show environment | `provisioning env` |\n| `list` | List resources | `provisioning list servers` |\n| `show` | Show details | `provisioning show settings` |\n| `validate` | Validate config | `provisioning validate config` |\n\n## Working with Multiple Environments\n\n### Environment Concepts\n\nThe system supports multiple environments:\n\n- **dev** - Development and testing\n- **test** - Integration testing\n- **prod** - Production deployment\n\n### Switching Environments\n\n```\n# Set environment for this session\nexport PROVISIONING_ENV=dev\nprovisioning env\n\n# Or specify per command\nprovisioning --environment dev server create\n```\n\n### Environment-Specific Configuration\n\nCreate environment configs:\n\n```\n# Development environment\nprovisioning init config dev\n\n# Production environment\nprovisioning init config prod\n```\n\n## Common Workflows\n\n### Workflow 1: Development Environment\n\n```\n# 1. Create development workspace\nmkdir ~/dev-environment\ncd ~/dev-environment\n\n# 2. Generate infrastructure\nprovisioning generate infra --new dev-setup\n\n# 3. Customize for development\n# Edit settings.ncl to add development tools\n\n# 4. Deploy\nprovisioning server create --infra dev-setup --check\nprovisioning server create --infra dev-setup\n\n# 5. Install development services\nprovisioning taskserv create kubernetes --infra dev-setup\nprovisioning taskserv create containerd --infra dev-setup\n```\n\n### Workflow 2: Service Updates\n\n```\n# Check for service updates\nprovisioning taskserv check-updates\n\n# Update specific service\nprovisioning taskserv update kubernetes --infra dev-setup\n\n# Verify update\nprovisioning taskserv versions kubernetes\n```\n\n### Workflow 3: Infrastructure Scaling\n\n```\n# Add servers to existing infrastructure\n# Edit settings.ncl to add more servers\n\n# Apply changes\nprovisioning server create --infra dev-setup\n\n# Install services on new servers\nprovisioning taskserv create containerd --infra dev-setup\n```\n\n## Interactive Mode\n\n### Starting Interactive Shell\n\n```\n# Start Nushell with provisioning loaded\nprovisioning nu\n```\n\nIn the interactive shell, you have access to all provisioning functions:\n\n```\n# Inside Nushell session\nuse lib_provisioning *\n\n# Check environment\nshow_env\n\n# List available functions\nhelp commands | where name =~ "provision"\n```\n\n### Useful Interactive Commands\n\n```\n# Show detailed server information\nfind_servers "web-*" | table\n\n# Get cost estimates\nservers_walk_by_costs $settings "" false false "stdout"\n\n# Check task service status\ntaskservs_list | where status == "running"\n```\n\n## Configuration Management\n\n### Understanding Configuration Files\n\n1. **System Defaults**: `config.defaults.toml` - System-wide defaults\n2. **User Config**: `~/.provisioning/config.user.toml` - Your preferences\n3. **Environment Config**: `config.{env}.toml` - Environment-specific settings\n4. **Infrastructure Config**: `settings.ncl` - Infrastructure definitions\n\n### Configuration Hierarchy\n\n```\nInfrastructure settings.ncl\n    ↓ (overrides)\nEnvironment config.{env}.toml\n    ↓ (overrides)\nUser config.user.toml\n    ↓ (overrides)\nSystem config.defaults.toml\n```\n\n### Customizing Your Configuration\n\n```\n# Edit user configuration\nprovisioning sops ~/.provisioning/config.user.toml\n\n# Or using your preferred editor\nnano ~/.provisioning/config.user.toml\n```\n\nExample customizations:\n\n```\n[debug]\nenabled = true        # Enable debug mode by default\nlog_level = "debug"   # Verbose logging\n\n[providers]\ndefault = "aws"       # Use AWS as default provider\n\n[output]\nformat = "json"       # Prefer JSON output\n```\n\n## Monitoring and Observability\n\n### Checking System Status\n\n```\n# Overall system health\nprovisioning env\n\n# Infrastructure status\nprovisioning show servers --infra dev-setup\n\n# Service status\nprovisioning taskserv list --infra dev-setup\n```\n\n### Logging and Debugging\n\n```\n# Enable debug mode for troubleshooting\nprovisioning --debug server create --infra dev-setup --check\n\n# View logs for specific operations\nprovisioning show logs --infra dev-setup\n```\n\n### Cost Monitoring\n\n```\n# Show cost estimates\nprovisioning show cost --infra dev-setup\n\n# Detailed cost breakdown\nprovisioning server price --infra dev-setup\n```\n\n## Best Practices\n\n### 1. Configuration Management\n\n- ✅ Use version control for infrastructure definitions\n- ✅ Test changes in development before production\n- ✅ Use `--check` mode to preview changes\n- ✅ Keep user configuration separate from infrastructure\n\n### 2. Security\n\n- ✅ Use SOPS for encrypting sensitive data\n- ✅ Regular key rotation for cloud providers\n- ✅ Principle of least privilege for access\n- ✅ Audit infrastructure changes\n\n### 3. Operational Excellence\n\n- ✅ Monitor infrastructure costs regularly\n- ✅ Keep services updated\n- ✅ Document custom configurations\n- ✅ Plan for disaster recovery\n\n### 4. Development Workflow\n\n```\n# 1. Always validate before applying\nprovisioning validate config --infra my-infra\n\n# 2. Use check mode first\nprovisioning server create --infra my-infra --check\n\n# 3. Apply changes incrementally\nprovisioning server create --infra my-infra\n\n# 4. Verify results\nprovisioning show servers --infra my-infra\n```\n\n## Getting Help\n\n### Built-in Help System\n\n```\n# General help\nprovisioning help\n\n# Command-specific help\nprovisioning server help\nprovisioning taskserv help\nprovisioning cluster help\n\n# Show available options\nprovisioning generate help\n```\n\n### Command Reference\n\nFor complete command documentation, see: [CLI Reference](cli-reference.md)\n\n### Troubleshooting\n\nIf you encounter issues, see: [Troubleshooting Guide](troubleshooting-guide.md)\n\n## Real-World Example\n\nLet's walk through a complete example of setting up a web application infrastructure:\n\n### Step 1: Plan Your Infrastructure\n\n```\n# Create project workspace\nmkdir ~/webapp-infrastructure\ncd ~/webapp-infrastructure\n\n# Generate base infrastructure\nprovisioning generate infra --new webapp\n```\n\n### Step 2: Customize Configuration\n\nEdit `webapp/settings.ncl` to define:\n\n- 2 web servers for load balancing\n- 1 database server\n- Load balancer configuration\n\n### Step 3: Deploy Base Infrastructure\n\n```\n# Validate configuration\nprovisioning validate config --infra webapp\n\n# Preview deployment\nprovisioning server create --infra webapp --check\n\n# Deploy servers\nprovisioning server create --infra webapp\n```\n\n### Step 4: Install Services\n\n```\n# Install container runtime on all servers\nprovisioning taskserv create containerd --infra webapp\n\n# Install load balancer on web servers\nprovisioning taskserv create haproxy --infra webapp\n\n# Install database on database server\nprovisioning taskserv create postgresql --infra webapp\n```\n\n### Step 5: Deploy Application\n\n```\n# Create application cluster\nprovisioning cluster create webapp --infra webapp\n\n# Verify deployment\nprovisioning show servers --infra webapp\nprovisioning cluster list --infra webapp\n```\n\n## Next Steps\n\nNow that you understand the basics:\n\n1. **Set up your workspace**: [Workspace Setup Guide](workspace-setup.md)\n2. **Learn about infrastructure management**: [Infrastructure Management Guide](infrastructure-management.md)\n3. **Understand configuration**: [Configuration Guide](configuration.md)\n4. **Explore examples**: [Examples and Tutorials](examples/)\n\nYou're ready to start building and managing cloud infrastructure with confidence!
