provisioning/docs/src/getting-started/getting-started.md

Getting Started Guide

Welcome to Infrastructure Automation. This guide will walk you through your first steps with infrastructure automation, from basic setup to deploying your first infrastructure.

What You'll Learn

• Essential concepts and terminology
• How to configure your first environment
• Creating and managing infrastructure
• Basic server and service management
• Common workflows and best practices

Prerequisites

Before starting this guide, ensure you have:

• ✅ Completed the Installation Guide
• ✅ Verified your installation with provisioning --version
• ✅ Basic familiarity with command-line interfaces

Essential Concepts

Infrastructure as Code (IaC)

Provisioning uses declarative configuration to manage infrastructure. Instead of manually creating resources, you define what you want in configuration files, and the system makes it happen.

You describe → System creates → Infrastructure exists
```plaintext

### Key Components

| Component | Purpose | Example |
|-----------|---------|---------|
| **Providers** | Cloud platforms | AWS, UpCloud, Local |
| **Servers** | Virtual machines | Web servers, databases |
| **Task Services** | Infrastructure software | Kubernetes, Docker, databases |
| **Clusters** | Grouped services | Web cluster, database cluster |

### Configuration Languages

- **Nickel**: Primary configuration language for infrastructure definitions (type-safe, validated)
- **TOML**: User preferences and system settings
- **YAML**: Kubernetes manifests and service definitions

## First-Time Setup

### Step 1: Initialize Your Configuration

Create your personal configuration:

```bash
# Initialize user configuration
provisioning init config

# This creates ~/.provisioning/config.user.toml
```plaintext

### Step 2: Verify Your Environment

```bash
# Check your environment setup
provisioning env

# View comprehensive configuration
provisioning allenv
```plaintext

You should see output like:

```plaintext
✅ Configuration loaded successfully
✅ All required tools available
📁 Base path: /usr/local/provisioning
🏠 User config: ~/.provisioning/config.user.toml
```plaintext

### Step 3: Explore Available Resources

```bash
# List available providers
provisioning list providers

# List available task services
provisioning list taskservs

# List available clusters
provisioning list clusters
```plaintext

## Your First Infrastructure

Let's create a simple local infrastructure to learn the basics.

### Step 1: Create a Workspace

```bash
# Create a new workspace directory
mkdir ~/my-first-infrastructure
cd ~/my-first-infrastructure

# Initialize workspace
provisioning generate infra --new local-demo
```plaintext

This creates:

```plaintext
local-demo/
├── config/
│   └── config.ncl     # Master Nickel configuration
├── infra/
│   └── default/
│       ├── main.ncl   # Infrastructure definition
│       └── servers.ncl # Server configurations
└── docs/              # Auto-generated guides
```plaintext

### Step 2: Examine the Configuration

```bash
# View the generated configuration
provisioning show settings --infra local-demo
```plaintext

### Step 3: Validate the Configuration

```bash
# Validate syntax and structure
provisioning validate config --infra local-demo

# Should show: ✅ Configuration validation passed!
```plaintext

### Step 4: Deploy Infrastructure (Check Mode)

```bash
# Dry run - see what would be created
provisioning server create --infra local-demo --check

# This shows planned changes without making them
```plaintext

### Step 5: Create Your Infrastructure

```bash
# Create the actual infrastructure
provisioning server create --infra local-demo

# Wait for completion
provisioning server list --infra local-demo
```plaintext

## Working with Services

### Installing Your First Service

Let's install a containerized service:

```bash
# Install Docker/containerd
provisioning taskserv create containerd --infra local-demo

# Verify installation
provisioning taskserv list --infra local-demo
```plaintext

### Installing Kubernetes

For container orchestration:

```bash
# Install Kubernetes
provisioning taskserv create kubernetes --infra local-demo

# This may take several minutes...
```plaintext

### Checking Service Status

```bash
# Show all services on your infrastructure
provisioning show servers --infra local-demo

# Show specific service details
provisioning show servers web-01 taskserv kubernetes --infra local-demo
```plaintext

## Understanding Commands

### Command Structure

All commands follow this pattern:

```bash
provisioning [global-options] <command> [command-options] [arguments]
```plaintext

### Global Options

| Option | Short | Description |
|--------|-------|-------------|
| `--infra` | `-i` | Specify infrastructure |
| `--check` | `-c` | Dry run mode |
| `--debug` | `-x` | Enable debug output |
| `--yes` | `-y` | Auto-confirm actions |

### Essential Commands

| Command | Purpose | Example |
|---------|---------|---------|
| `help` | Show help | `provisioning help` |
| `env` | Show environment | `provisioning env` |
| `list` | List resources | `provisioning list servers` |
| `show` | Show details | `provisioning show settings` |
| `validate` | Validate config | `provisioning validate config` |

## Working with Multiple Environments

### Environment Concepts

The system supports multiple environments:

- **dev** - Development and testing
- **test** - Integration testing
- **prod** - Production deployment

### Switching Environments

```bash
# Set environment for this session
export PROVISIONING_ENV=dev
provisioning env

# Or specify per command
provisioning --environment dev server create
```plaintext

### Environment-Specific Configuration

Create environment configs:

```bash
# Development environment
provisioning init config dev

# Production environment
provisioning init config prod
```plaintext

## Common Workflows

### Workflow 1: Development Environment

```bash
# 1. Create development workspace
mkdir ~/dev-environment
cd ~/dev-environment

# 2. Generate infrastructure
provisioning generate infra --new dev-setup

# 3. Customize for development
# Edit settings.ncl to add development tools

# 4. Deploy
provisioning server create --infra dev-setup --check
provisioning server create --infra dev-setup

# 5. Install development services
provisioning taskserv create kubernetes --infra dev-setup
provisioning taskserv create containerd --infra dev-setup
```plaintext

### Workflow 2: Service Updates

```bash
# Check for service updates
provisioning taskserv check-updates

# Update specific service
provisioning taskserv update kubernetes --infra dev-setup

# Verify update
provisioning taskserv versions kubernetes
```plaintext

### Workflow 3: Infrastructure Scaling

```bash
# Add servers to existing infrastructure
# Edit settings.ncl to add more servers

# Apply changes
provisioning server create --infra dev-setup

# Install services on new servers
provisioning taskserv create containerd --infra dev-setup
```plaintext

## Interactive Mode

### Starting Interactive Shell

```bash
# Start Nushell with provisioning loaded
provisioning nu
```plaintext

In the interactive shell, you have access to all provisioning functions:

```nushell
# Inside Nushell session
use lib_provisioning *

# Check environment
show_env

# List available functions
help commands | where name =~ "provision"
```plaintext

### Useful Interactive Commands

```nushell
# Show detailed server information
find_servers "web-*" | table

# Get cost estimates
servers_walk_by_costs $settings "" false false "stdout"

# Check task service status
taskservs_list | where status == "running"
```plaintext

## Configuration Management

### Understanding Configuration Files

1. **System Defaults**: `config.defaults.toml` - System-wide defaults
2. **User Config**: `~/.provisioning/config.user.toml` - Your preferences
3. **Environment Config**: `config.{env}.toml` - Environment-specific settings
4. **Infrastructure Config**: `settings.ncl` - Infrastructure definitions

### Configuration Hierarchy

```plaintext
Infrastructure settings.ncl
    ↓ (overrides)
Environment config.{env}.toml
    ↓ (overrides)
User config.user.toml
    ↓ (overrides)
System config.defaults.toml
```plaintext

### Customizing Your Configuration

```bash
# Edit user configuration
provisioning sops ~/.provisioning/config.user.toml

# Or using your preferred editor
nano ~/.provisioning/config.user.toml
```plaintext

Example customizations:

```toml
[debug]
enabled = true        # Enable debug mode by default
log_level = "debug"   # Verbose logging

[providers]
default = "aws"       # Use AWS as default provider

[output]
format = "json"       # Prefer JSON output
```plaintext

## Monitoring and Observability

### Checking System Status

```bash
# Overall system health
provisioning env

# Infrastructure status
provisioning show servers --infra dev-setup

# Service status
provisioning taskserv list --infra dev-setup
```plaintext

### Logging and Debugging

```bash
# Enable debug mode for troubleshooting
provisioning --debug server create --infra dev-setup --check

# View logs for specific operations
provisioning show logs --infra dev-setup
```plaintext

### Cost Monitoring

```bash
# Show cost estimates
provisioning show cost --infra dev-setup

# Detailed cost breakdown
provisioning server price --infra dev-setup
```plaintext

## Best Practices

### 1. Configuration Management

- ✅ Use version control for infrastructure definitions
- ✅ Test changes in development before production
- ✅ Use `--check` mode to preview changes
- ✅ Keep user configuration separate from infrastructure

### 2. Security

- ✅ Use SOPS for encrypting sensitive data
- ✅ Regular key rotation for cloud providers
- ✅ Principle of least privilege for access
- ✅ Audit infrastructure changes

### 3. Operational Excellence

- ✅ Monitor infrastructure costs regularly
- ✅ Keep services updated
- ✅ Document custom configurations
- ✅ Plan for disaster recovery

### 4. Development Workflow

```bash
# 1. Always validate before applying
provisioning validate config --infra my-infra

# 2. Use check mode first
provisioning server create --infra my-infra --check

# 3. Apply changes incrementally
provisioning server create --infra my-infra

# 4. Verify results
provisioning show servers --infra my-infra
```plaintext

## Getting Help

### Built-in Help System

```bash
# General help
provisioning help

# Command-specific help
provisioning server help
provisioning taskserv help
provisioning cluster help

# Show available options
provisioning generate help
```plaintext

### Command Reference

For complete command documentation, see: [CLI Reference](cli-reference.md)

### Troubleshooting

If you encounter issues, see: [Troubleshooting Guide](troubleshooting-guide.md)

## Real-World Example

Let's walk through a complete example of setting up a web application infrastructure:

### Step 1: Plan Your Infrastructure

```bash
# Create project workspace
mkdir ~/webapp-infrastructure
cd ~/webapp-infrastructure

# Generate base infrastructure
provisioning generate infra --new webapp
```plaintext

### Step 2: Customize Configuration

Edit `webapp/settings.ncl` to define:

- 2 web servers for load balancing
- 1 database server
- Load balancer configuration

### Step 3: Deploy Base Infrastructure

```bash
# Validate configuration
provisioning validate config --infra webapp

# Preview deployment
provisioning server create --infra webapp --check

# Deploy servers
provisioning server create --infra webapp
```plaintext

### Step 4: Install Services

```bash
# Install container runtime on all servers
provisioning taskserv create containerd --infra webapp

# Install load balancer on web servers
provisioning taskserv create haproxy --infra webapp

# Install database on database server
provisioning taskserv create postgresql --infra webapp
```plaintext

### Step 5: Deploy Application

```bash
# Create application cluster
provisioning cluster create webapp --infra webapp

# Verify deployment
provisioning show servers --infra webapp
provisioning cluster list --infra webapp
```plaintext

## Next Steps

Now that you understand the basics:

1. **Set up your workspace**: [Workspace Setup Guide](workspace-setup.md)
2. **Learn about infrastructure management**: [Infrastructure Management Guide](infrastructure-management.md)
3. **Understand configuration**: [Configuration Guide](configuration.md)
4. **Explore examples**: [Examples and Tutorials](examples/)

You're ready to start building and managing cloud infrastructure with confidence!