# Quick Start: Local Development Setup

This example demonstrates how to set up a basic local development environment using provisioning. Perfect for learning the fundamentals without requiring cloud resources.

## What You'll Learn

- Setting up local infrastructure for development
- Creating and managing servers locally
- Installing basic task services
- Working with the provisioning CLI
- Configuration management basics

## Prerequisites

- Provisioning installed
- Local development tools (Docker recommended)
- At least 2 GB RAM and 5 GB free disk space

## Architecture

This example creates:

- 2 local development servers (web-dev-01, db-dev-01)
- Containerized environment using local provider
- Basic networking setup
- Development-friendly configurations

```plaintext
┌─────────────────────────────────────┐
│         Local Development           │
├─────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐   │
│  │  web-dev-01 │  │  db-dev-01  │   │
│  │             │  │             │   │
│  │  - Nginx    │  │ - PostgreSQL│   │
│  │  - Node.js  │  │ - Redis     │   │
│  │             │  │             │   │
│  └─────────────┘  └─────────────┘   │
│           │              │          │
│           └──────────────┘          │
│              Local Network          │
└─────────────────────────────────────┘
```plaintext

## Files in This Example

- `settings.ncl` - Infrastructure definition
- `config.toml` - Environment configuration
- `deploy.sh` - Deployment script
- `verify.sh` - Verification script
- `cleanup.sh` - Resource cleanup script
- `check-requirements.sh` - Prerequisites checker

## Step-by-Step Deployment

### Step 1: Check Prerequisites

```bash
# Check system requirements
./check-requirements.sh

# Should show:
# ✅ Provisioning available
# ✅ Local provider configured
# ✅ Sufficient disk space
# ✅ Docker available (if using containers)
```plaintext

### Step 2: Review Configuration

```bash
# Examine the infrastructure definition
cat settings.ncl

# Check environment configuration
cat config.toml

# Understand what will be created
provisioning show settings --settings settings.ncl
```plaintext

### Step 3: Validate Configuration

```bash
# Validate the configuration
provisioning validate config --settings settings.ncl

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

### Step 4: Deploy (Dry Run)

```bash
# First, see what would be created
./deploy.sh --check

# Or manually:
provisioning server create --settings settings.ncl --check

# Review the planned changes
```plaintext

### Step 5: Deploy for Real

```bash
# Deploy the infrastructure
./deploy.sh

# Monitor progress
provisioning server list --settings settings.ncl

# Wait for servers to be ready (should be quick for local)
```plaintext

### Step 6: Install Services

```bash
# Install basic services
provisioning taskserv create containerd --settings settings.ncl
provisioning taskserv create nginx --servers web-dev-01 --settings settings.ncl
provisioning taskserv create postgresql --servers db-dev-01 --settings settings.ncl

# Verify installations
provisioning taskserv list --settings settings.ncl --installed
```plaintext

### Step 7: Verify Deployment

```bash
# Run verification tests
./verify.sh

# Manual verification
provisioning server ssh web-dev-01 --settings settings.ncl --command "curl -I localhost"
provisioning server ssh db-dev-01 --settings settings.ncl --command "pg_isready"
```plaintext

## Working with the Development Environment

### Accessing Servers

```bash
# SSH to web server
provisioning server ssh web-dev-01 --settings settings.ncl

# SSH to database server
provisioning server ssh db-dev-01 --settings settings.ncl

# Execute commands remotely
provisioning server ssh web-dev-01 --settings settings.ncl --command "systemctl status nginx"
```plaintext

### Deploying Code

```bash
# Copy files to web server
provisioning server copy ./my-app/ web-dev-01:/var/www/html/ --settings settings.ncl

# Restart services
provisioning server ssh web-dev-01 --settings settings.ncl --command "sudo systemctl restart nginx"
```plaintext

### Database Operations

```bash
# Connect to database
provisioning server ssh db-dev-01 --settings settings.ncl --command "psql -U postgres"

# Create development database
provisioning server ssh db-dev-01 --settings settings.ncl --command "createdb myapp_development"
```plaintext

### Monitoring and Logs

```bash
# Check server status
provisioning server list --settings settings.ncl

# View service logs
provisioning taskserv logs nginx --settings settings.ncl
provisioning taskserv logs postgresql --settings settings.ncl

# Check resource usage
provisioning show costs --settings settings.ncl
```plaintext

## Configuration Details

### Infrastructure Definition (settings.ncl)

```kcl
import models.server
import models.taskserv

# Development infrastructure metadata
metadata: {
    name = "local-development"
    description = "Local development environment"
    environment = "development"
    owner = "developer"
}

# Server definitions
servers: [
    server.Server {
        name = "web-dev-01"
        provider = "local"
        plan = "development"  # Small resources for local dev
        os = "ubuntu-22.04"

        # Development-specific settings
        auto_start = True
        development_mode = True

        # Network configuration
        network = {
            private_ip = "192.168.100.10"
            ports = [80, 443, 22, 3000, 8080]  # Common dev ports
        }

        # Storage for development
        storage = {
            size = "10 GB"
            type = "local"
        }

        tags = {
            environment = "development"
            role = "web-server"
            team = "engineering"
        }
    }

    server.Server {
        name = "db-dev-01"
        provider = "local"
        plan = "development"
        os = "ubuntu-22.04"

        auto_start = True
        development_mode = True

        network = {
            private_ip = "192.168.100.11"
            ports = [5432, 6379, 22]  # PostgreSQL, Redis, SSH
        }

        storage = {
            size = "15 GB"  # Extra space for database
            type = "local"
        }

        tags = {
            environment = "development"
            role = "database-server"
            team = "engineering"
        }
    }
]

# Network configuration
network: {
    vpc_cidr = "192.168.100.0/24"
    subnets = [
        {name = "development", cidr = "192.168.100.0/28"}
    ]
}

# Development-specific task service configurations
taskservs: {
    # Nginx configuration optimized for development
    nginx: {
        development_mode = True
        auto_reload = True
        error_log_level = "debug"
        document_root = "/var/www/html"
    }

    # PostgreSQL configuration for development
    postgresql: {
        version = "14"
        development_mode = True
        log_statement = "all"  # Log all queries for debugging
        max_connections = 20   # Lower limit for local dev
        shared_buffers = "64 MB"
    }

    # Redis for session storage/caching
    redis: {
        development_mode = True
        save_disabled = True  # No persistence needed in dev
        maxmemory = "128 MB"
    }
}
```plaintext

### Environment Configuration (config.toml)

```toml
[core]
name = "local-development"

[paths]
base = "/usr/local/provisioning"
# Use current directory for this example
infra = "./infrastructure"

[debug]
# Enable debug mode for learning
enabled = true
log_level = "debug"
metadata = true

[providers]
# Use local provider exclusively
default = "local"

[providers.local]
# Local provider configuration
interface = "CLI"
container_runtime = "docker"  # or "podman"
network_driver = "bridge"

[output]
# Human-readable format
format = "yaml"
file_viewer = "less"

# Development-specific settings
[development]
auto_approve = true      # Skip confirmations for faster iteration
cleanup_on_error = true # Clean up failed deployments automatically
debug_on_error = true   # Auto-enable debug mode on failures

# Resource limits for local development
[limits]
max_servers = 5
max_memory = "2 GB"
max_disk = "50 GB"

[notifications]
# Disable notifications for local dev
enabled = false
```plaintext

## Troubleshooting

### Common Issues

#### Issue: Local Provider Not Available

```bash
# Check if Docker/container runtime is running
docker version
systemctl status docker

# Configure local provider
provisioning provider test local
```plaintext

#### Issue: Port Conflicts

```bash
# Check for port conflicts
sudo netstat -tulpn | grep :80
sudo ss -tulpn | grep :80

# Change ports in settings.ncl if needed
```plaintext

#### Issue: Insufficient Resources

```bash
# Check available resources
free -h
df -h

# Reduce server resources in settings.ncl
plan = "minimal"  # Instead of "development"
```plaintext

#### Issue: Permission Errors

```bash
# Fix Docker permissions
sudo usermod -aG docker $USER
newgrp docker

# Or use podman instead
```plaintext

### Getting Help

```bash
# Check system status
provisioning env

# Debug deployment
provisioning --debug server create --settings settings.ncl

# Check logs
provisioning show logs --settings settings.ncl

# Validate configuration
provisioning validate config --settings settings.ncl --detailed
```plaintext

## Cleanup

When you're done experimenting:

```bash
# Clean up all resources
./cleanup.sh

# Or manually
provisioning server delete --settings settings.ncl --yes
provisioning taskserv delete --all --settings settings.ncl --yes

# Verify cleanup
provisioning server list --settings settings.ncl
```plaintext

## Next Steps

After completing this example:

1. **Explore other examples**: Try the LAMP Stack example
2. **Learn about cloud providers**: Try the AWS basics example
3. **Add more services**: Experiment with additional task services
4. **Customize configuration**: Modify settings.ncl for your specific needs
5. **Version control**: Put your configurations in git

## Learning Resources

- Configuration Guide - Understand configuration in depth
- CLI Reference - Complete command reference
- Infrastructure Management - Advanced infrastructure patterns

This local development setup gives you a safe environment to learn provisioning concepts without cloud costs or complexity. Happy learning! 🚀
