provisioning/docs/src/guides/infrastructure-setup.md

# Infrastructure Setup Quick Reference

**Complete guide to provisioning infrastructure with Nickel + ConfigLoader + TypeDialog**

---

## Quick Start

### 1. Generate Infrastructure Configs (Solo Mode)

```bash
cd project-provisioning

# Generate solo deployment (Docker Compose, Nginx, Prometheus, OCI Registry)
nickel export --format json provisioning/schemas/infrastructure/examples-solo-deployment.ncl > /tmp/solo-infra.json

# Verify JSON structure
jq . /tmp/solo-infra.json
```

### 2. Validate Generated Configs

```bash
# Solo deployment validation
bash provisioning/platform/scripts/validate-infrastructure.nu --config-dir provisioning/platform/infrastructure

# Output shows validation status for Docker, K8s, Nginx, Prometheus
```

### 3. Compare Solo vs Enterprise

```bash
# Export both examples
nickel export --format json provisioning/schemas/infrastructure/examples-solo-deployment.ncl > /tmp/solo.json
nickel export --format json provisioning/schemas/infrastructure/examples-enterprise-deployment.ncl > /tmp/enterprise.json

# Compare orchestrator resources
echo "=== Solo Resources ===" && jq '.docker_compose_services.orchestrator.deploy.resources.limits' /tmp/solo.json
echo "=== Enterprise Resources ===" && jq '.docker_compose_services.orchestrator.deploy.resources.limits' /tmp/enterprise.json

# Compare prometheus monitoring
echo "=== Solo Prometheus Jobs ===" && jq '.prometheus_config.scrape_configs | length' /tmp/solo.json
echo "=== Enterprise Prometheus Jobs ===" && jq '.prometheus_config.scrape_configs | length' /tmp/enterprise.json
```

---

## Infrastructure Components

### Available Schemas (6)

| Schema | Purpose | Mode Presets |
|--------|---------|--------------|
| `docker-compose.ncl` | Container orchestration | solo, multiuser, enterprise |
| `kubernetes.ncl` | K8s manifest generation | solo, enterprise |
| `nginx.ncl` | Reverse proxy & load balancer | solo, enterprise |
| `prometheus.ncl` | Metrics & monitoring | solo, multiuser, enterprise |
| `systemd.ncl` | System service units | solo, enterprise |
| `oci-registry.ncl` | Container registry (Zot/Harbor) | solo, multiuser, enterprise |

### Configuration Examples (2)

| Example | Type | Services | CPU | Memory |
|---------|------|----------|-----|--------|
| `examples-solo-deployment.ncl` | Dev/Testing | 5 | 1.0 | 1024M |
| `examples-enterprise-deployment.ncl` | Production | 6 | 4.0 | 4096M |

### Automation Scripts (3)

| Script | Purpose | Usage |
|--------|---------|-------|
| `generate-infrastructure-configs.nu` | Generate all configs | `--mode solo --format yaml` |
| `validate-infrastructure.nu` | Validate configs | `--config-dir /path` |
| `setup-with-forms.sh` | Interactive setup | Auto-detects TypeDialog |

---

## Workflow: Platform Config + Infrastructure Config

### Two-Tier Configuration System

**Platform Config Layer** (Service-Internal):
```bash
Orchestrator port, database host, logging level
    ↓
ConfigLoader (Rust)
    ↓
Service reads TOML from runtime/generated/
```

**Infrastructure Config Layer** (Deployment-External):
```bash
Docker Compose services, Nginx routing, Prometheus scrape jobs
    ↓
nickel export → YAML/JSON
    ↓
Docker/Kubernetes/Nginx deploys infrastructure
```

### Complete Deployment Workflow

```bash
1. Choose platform config mode
   provisioning/platform/config/examples/orchestrator.solo.example.ncl
                                        ↓
2. Generate platform config TOML
   nickel export --format toml → runtime/generated/orchestrator.solo.toml
                                        ↓
3. Choose infrastructure mode
   provisioning/schemas/infrastructure/examples-solo-deployment.ncl
                                        ↓
4. Generate infrastructure JSON/YAML
   nickel export --format json → docker-compose-solo.json
                                        ↓
5. Deploy infrastructure
   docker-compose -f docker-compose-solo.yaml up
                                        ↓
6. Services start with configs
   ConfigLoader reads platform config TOML
   Docker/Nginx read infrastructure configs
```

---

## Resource Allocation Reference

### Solo Mode (Development)

```bash
Orchestrator:      1.0 CPU, 1024M RAM (1 replica)
Control Center:    0.5 CPU,  512M RAM
CoreDNS:           0.25 CPU, 256M RAM
KMS:               0.5 CPU,  512M RAM
OCI Registry:      0.5 CPU,  512M RAM (Zot - filesystem)
─────────────────────────────────────
Total:             2.75 CPU, 2624M RAM
Use Case:          Development, testing, PoCs
```

### Enterprise Mode (Production)

```bash
Orchestrator:      4.0 CPU, 4096M RAM (3 replicas)
Control Center:    2.0 CPU, 2048M RAM (HA)
CoreDNS:           1.0 CPU, 1024M RAM
KMS:               2.0 CPU, 2048M RAM
OCI Registry:      2.0 CPU, 2048M RAM (Harbor - S3)
─────────────────────────────────────
Total:            11.0 CPU, 10240M RAM (+ replicas)
Use Case:          Production deployments, high availability
```

---

## Common Tasks

### Generate Solo Infrastructure

```bash
nickel export --format json provisioning/schemas/infrastructure/examples-solo-deployment.ncl
```

### Generate Enterprise Infrastructure

```bash
nickel export --format json provisioning/schemas/infrastructure/examples-enterprise-deployment.ncl
```

### Validate JSON Structure

```bash
jq '.docker_compose_services | keys' /tmp/infra.json
jq '.prometheus_config.scrape_configs | length' /tmp/infra.json
jq '.oci_registry_config.backend' /tmp/infra.json
```

### Check Resource Limits

```bash
# All services in solo mode
jq '.docker_compose_services[] | {name: .name, cpu: .deploy.resources.limits.cpus, memory: .deploy.resources.limits.memory}' /tmp/solo.json

# Just orchestrator
jq '.docker_compose_services.orchestrator.deploy.resources.limits' /tmp/solo.json
```

### Compare Modes

```bash
# Services count
jq '.docker_compose_services | length' /tmp/solo.json      # 5 services
jq '.docker_compose_services | length' /tmp/enterprise.json # 6 services

# Prometheus jobs
jq '.prometheus_config.scrape_configs | length' /tmp/solo.json      # 4 jobs
jq '.prometheus_config.scrape_configs | length' /tmp/enterprise.json # 7 jobs

# Registry backend
jq -r '.oci_registry_config.backend' /tmp/solo.json      # Zot
jq -r '.oci_registry_config.backend' /tmp/enterprise.json # Harbor
```

---

## Validation Commands

### Type Check Schemas

```bash
nickel typecheck provisioning/schemas/infrastructure/docker-compose.ncl
nickel typecheck provisioning/schemas/infrastructure/kubernetes.ncl
nickel typecheck provisioning/schemas/infrastructure/nginx.ncl
nickel typecheck provisioning/schemas/infrastructure/prometheus.ncl
nickel typecheck provisioning/schemas/infrastructure/systemd.ncl
nickel typecheck provisioning/schemas/infrastructure/oci-registry.ncl
```

### Validate Examples

```bash
nickel typecheck provisioning/schemas/infrastructure/examples-solo-deployment.ncl
nickel typecheck provisioning/schemas/infrastructure/examples-enterprise-deployment.ncl
```

### Test Export

```bash
nickel export --format json provisioning/schemas/infrastructure/examples-solo-deployment.ncl | jq .
```

---

## Platform Config Examples

### Solo Platform Config

```bash
nickel export --format toml provisioning/platform/config/examples/orchestrator.solo.example.ncl
# Output: TOML with [database], [logging], [monitoring], [workspace] sections
```

### Enterprise Platform Config

```bash
nickel export --format toml provisioning/platform/config/examples/orchestrator.enterprise.example.ncl
# Output: TOML with HA, S3, Redis, tracing configuration
```

---

## Configuration Files Reference

### Platform Configs (services internally)

```bash
provisioning/platform/config/
├── runtime/generated/*.toml          # Auto-generated by ConfigLoader
├── examples/                         # Reference implementations
│   ├── orchestrator.solo.example.ncl
│   ├── orchestrator.multiuser.example.ncl
│   └── orchestrator.enterprise.example.ncl
└── README.md
```

### Infrastructure Schemas

```bash
provisioning/schemas/infrastructure/
├── docker-compose.ncl                # 232 lines
├── kubernetes.ncl                    # 376 lines
├── nginx.ncl                         # 233 lines
├── prometheus.ncl                    # 280 lines
├── systemd.ncl                       # 235 lines
├── oci-registry.ncl                  # 221 lines
├── examples-solo-deployment.ncl      # 27 lines
├── examples-enterprise-deployment.ncl # 27 lines
└── README.md
```

### TypeDialog Integration

```bash
provisioning/platform/.typedialog/provisioning/platform/
├── forms/                            # Ready for auto-generated forms
├── templates/service-form.template.j2
├── schemas/ → ../../schemas          # Symlink
├── constraints/constraints.toml       # Validation rules
└── README.md
```

### Automation Scripts

```bash
provisioning/platform/scripts/
├── generate-infrastructure-configs.nu  # Generate all configs
├── validate-infrastructure.nu          # Validate with tools
└── setup-with-forms.sh                # Interactive wizard
```

---

## Integration Status

| Component | Status | Details |
|-----------|--------|---------|
| **Infrastructure Schemas** | ✅ Complete | 6 schemas, 1,577 lines, all validated |
| **Deployment Examples** | ✅ Complete | 2 examples (solo + enterprise), tested |
| **Generation Scripts** | ✅ Complete | Auto-generate configs for all modes |
| **Validation Scripts** | ✅ Complete | Validate Docker, K8s, Nginx, Prometheus |
| **Platform Config** | ✅ Complete | 36 TOML files in runtime/generated/ |
| **TypeDialog Ready** | ✅ Ready | Structure prepared, awaiting binary |
| **FormInquire** | ✅ Active | Alternative setup wizard functional |
| **Documentation** | ✅ Complete | All guides updated with examples |

---

## Next Steps

### Now Available
- Generate infrastructure configs for solo/enterprise modes
- Validate generated configs with format-specific tools
- Use interactive setup wizard with FormInquire
- Deploy with Docker/Kubernetes using generated configs

### When TypeDialog Becomes Available
- Install TypeDialog binary
- Auto-generate forms from infrastructure schemas
- Use form-based configuration for all services
- Upgrade setup wizard to TypeDialog

---

## Key Files

**Schemas**:
- `provisioning/schemas/infrastructure/` - All infrastructure schemas

**Examples**:
- `provisioning/schemas/infrastructure/examples-solo-deployment.ncl`
- `provisioning/schemas/infrastructure/examples-enterprise-deployment.ncl`

**Platform Configs**:
- `provisioning/platform/config/examples/` - Platform config examples
- `provisioning/platform/config/runtime/generated/` - Generated TOML files

**Scripts**:
- `provisioning/platform/scripts/generate-infrastructure-configs.nu`
- `provisioning/platform/scripts/validate-infrastructure.nu`
- `provisioning/platform/scripts/setup-with-forms.sh`

**Documentation**:
- `provisioning/docs/src/guides/infrastructure-setup.md` - This guide
- `provisioning/schemas/infrastructure/README.md` - Infrastructure schema reference
- `provisioning/platform/config/examples/README.md` - Platform config guide
- `provisioning/platform/.typedialog/README.md` - TypeDialog integration guide

---

**Version**: 1.0.0
**Last Updated**: 2025-01-06
**Status**: Production Ready