Docker Compose (docker-compose.ncl) - Container orchestration via Docker Compose
Kubernetes (kubernetes.ncl) - Kubernetes manifest generation (Deployments, Services, ConfigMaps)
Nginx (nginx.ncl) - Reverse proxy and load balancer configuration
Prometheus (prometheus.ncl) - Metrics collection and monitoring
Systemd (systemd.ncl) - System service units for standalone deployments
OCI Registry (oci-registry.ncl) - Container registry backend configuration (Zot, Distribution, Harbor)

Key Features

1. Mode-Based Presets

Each schema includes presets for different deployment modes:

solo: Single-node deployments (minimal resources)
multiuser: Staging/small production (2 replicas, HA)
enterprise: Large-scale production (3+ replicas, distributed storage)
cicd: CI/CD pipeline deployments

2. Type Safety

# All fields are strongly typed with validation
ResourceLimits = {
  cpus | String,               # Type: string
  memory | String,
},

# Enum validation
ServiceType = [| 'ClusterIP, 'NodePort, 'LoadBalancer |],

# Numeric range validation
Port = Number | {
  predicate = fun n => n > 0 && n < 65536,
}

3. Export Formats

Schemas export to multiple formats:

# Export as YAML (K8s, Docker Compose)
nickel export --format yaml provisioning/schemas/infrastructure/kubernetes.ncl

# Export as JSON (OCI Registry, Prometheus configs)
nickel export --format json provisioning/schemas/infrastructure/oci-registry.ncl

# Export as TOML (systemd, Nginx)
nickel export --format toml provisioning/schemas/infrastructure/systemd.ncl

Single Source of Truth Pattern

Define service configuration once, generate multiple infrastructure outputs:

orchestrator.ncl (Platform Service Schema)
    ↓
Infrastructure Schemas (Docker, Kubernetes, Nginx, etc.)
    ↓
[Multiple Outputs]
├─→ docker-compose.yaml
├─→ kubernetes/deployment.yaml
├─→ nginx.conf
├─→ prometheus.yml
└─→ systemd/orchestrator.service

Example: Service Port Definition

# Platform service schema (provisioning/schemas/platform/schemas/orchestrator.ncl)
server = {
  port | Number,  # Define port once
}

# Used in Docker Compose
docker-compose = {
  services.orchestrator = {
    ports = ["%{orchestrator.server.port}:8080"],
  }
}

# Used in Kubernetes
kubernetes = {
  containers.ports = [{
    containerPort = orchestrator.server.port,
  }]
}

# Used in Nginx
nginx = {
  upstreams.orchestrator.servers = [{
    address = "orchestrator:%{orchestrator.server.port}",
  }]
}

Benefit: Change port in one place, all infrastructure configs update automatically.

Validation Before Deployment

# Type check schema
nickel typecheck provisioning/schemas/infrastructure/docker-compose.ncl

# Validate export
nickel export --format json provisioning/schemas/infrastructure/kubernetes.ncl 
  | jq .  # Validate JSON structure

# Check generated YAML
nickel export --format yaml provisioning/schemas/infrastructure/kubernetes.ncl 
  | kubectl apply --dry-run=client -f -

File Structure

infrastructure/
├── README.md                        # This file
├── docker-compose.ncl               # Docker Compose schema (232 lines)
├── kubernetes.ncl                   # Kubernetes manifests (376 lines)
├── nginx.ncl                        # Nginx configuration (233 lines)
├── prometheus.ncl                   # Prometheus configuration (280 lines)
├── systemd.ncl                      # Systemd service units (235 lines)
└── oci-registry.ncl                 # OCI Registry configuration (221 lines)

Total: 1,577 lines of type-safe infrastructure schemas

Usage Patterns

1. Generate Solo Mode Infrastructure

# Export docker-compose for solo deployment
nickel export --format yaml provisioning/schemas/infrastructure/docker-compose.ncl 
  | tee provisioning/platform/infrastructure/docker/docker-compose.solo.yaml

# Validate with Docker
docker-compose -f docker-compose.solo.yaml config --quiet

2. Generate Enterprise HA Kubernetes

# Export Kubernetes manifests
nickel export --format yaml provisioning/schemas/infrastructure/kubernetes.ncl 
  > provisioning/platform/infrastructure/kubernetes/deployment.yaml

# Validate and apply
kubectl apply --dry-run=client -f deployment.yaml
kubectl apply -f deployment.yaml

3. Generate Monitoring Stack

# Prometheus configuration
nickel export --format yaml provisioning/schemas/infrastructure/prometheus.ncl 
  > provisioning/platform/infrastructure/prometheus/prometheus.yml

# Validate Prometheus config
promtool check config provisioning/platform/infrastructure/prometheus/prometheus.yml

4. Auto-Generate Infrastructure from Service Schemas

# Composition function: generate Docker Compose from service port
let service = import "../platform/schemas/orchestrator.ncl" in
{
  services.orchestrator = {
    image = "provisioning/orchestrator:latest",
    ports = ["%{service.server.port}:8080"],
    deploy.resources.limits = service.deploy.resources.limits,
  }
}

Documentation

Inline Schema Documentation

Each schema field includes inline documentation (via | doc):

field | Type | doc "description" | default = value

Important: With Nickel, | doc must come BEFORE | default:

✅ CORRECT:   cpus | String | doc "CPU limit" | default = "2.0"
❌ INCORRECT: cpus | String | default = "2.0" | doc "CPU limit"

For details, see .claude/guidelines/nickel.md

Validation Rules

Docker Compose

✅ Valid service names, port ranges
✅ Resource limits: CPU and memory strings
✅ Health check configuration
✅ Environment variables typed as strings

Kubernetes

✅ Valid API versions (apps/v1, v1)
✅ Container resource requests/limits
✅ Valid restart policies (Always, OnFailure, Never)
✅ Port ranges (1-65535)

Nginx

✅ Upstream server addresses
✅ Rate limiting zones and rules
✅ TLS configuration validation
✅ Security headers structure

Prometheus

✅ Scrape job configuration
✅ Alert manager targets
✅ Scrape intervals (duration format)
✅ Relabel configuration

Systemd

✅ Unit dependencies (after, requires, wants)
✅ Resource limits (CPU quota, memory)
✅ Restart policies
✅ Service types (simple, forking, oneshot, etc.)

OCI Registry

✅ Registry backends (Zot, Distribution, Harbor)
✅ Storage backend selection (filesystem, S3, Azure)
✅ Authentication methods (none, basic, bearer, OIDC)
✅ Access control policies

Deployment Examples

Two comprehensive infrastructure examples are provided demonstrating solo and enterprise configurations:

Solo Deployment Example

File: examples-solo-deployment.ncl

Minimal single-node setup for development/testing:

# Exports 4 infrastructure components
docker_compose_services  # 5 services: orchestrator, control-center, coredns, kms, oci_registry
nginx_config             # Simple upstream routing to localhost services
prometheus_config        # 4 scrape jobs for basic monitoring
oci_registry_config      # Zot backend with filesystem storage

Resource Allocation:

Orchestrator: 1.0 CPU, 1024M RAM
Control Center: 0.5 CPU, 512M RAM
Other services: 0.25-0.5 CPU, 256-512M RAM

Export to JSON:

nickel export --format json provisioning/schemas/infrastructure/examples-solo-deployment.ncl
# Output: 198 lines of configuration

Enterprise Deployment Example

File: examples-enterprise-deployment.ncl

High-availability production-grade deployment:

# Exports 4 infrastructure components (HA versions)
docker_compose_services  # 6 services with 3 replicas for HA
nginx_config             # Multiple upstreams with rate limiting and failover
prometheus_config        # 7 scrape jobs with remote storage
oci_registry_config      # Harbor backend with S3 replication

Resource Allocation:

Orchestrator: 4.0 CPU, 4096M RAM (3 replicas)
Control Center: 2.0 CPU, 2048M RAM (HA)
Services scale appropriately for production load

Export to JSON:

nickel export --format json provisioning/schemas/infrastructure/examples-enterprise-deployment.ncl
# Output: 313 lines of configuration

Example Comparison

Aspect	Solo	Enterprise
Services	5	6
Orchestrator CPU	1.0	4.0
Orchestrator Memory	1024M	4096M
Prometheus Jobs	4	7
Registry Backend	Zot	Harbor
Use Case	Dev/Testing	Production
JSON Size	198 lines	313 lines

Validation Results

Both examples have been tested and validated:

✅ Solo Deployment (examples-solo-deployment.ncl):

Type-checks without errors
Exports to valid JSON (198 lines)
All resource limits validated
Port range validation: 8080, 9090, 5432, 53
JSON structure: docker_compose_services, nginx_config, prometheus_config, oci_registry_config

✅ Enterprise Deployment (examples-enterprise-deployment.ncl):

Type-checks without errors
Exports to valid JSON (313 lines)
HA configuration with 3 replicas
Enhanced monitoring: 7 vs 4 scrape jobs
Distributed storage backend (Harbor vs Zot)
Full JSON structure validated with jq

Automation Scripts

Generate all infrastructure configs in one command:

# Generate all formats for all modes
provisioning/platform/scripts/generate-infrastructure-configs.nu

# Generate specific mode/format
provisioning/platform/scripts/generate-infrastructure-configs.nu --mode solo --format yaml

# Specify output directory
provisioning/platform/scripts/generate-infrastructure-configs.nu --output-dir /tmp/infra

See provisioning/platform/scripts/generate-infrastructure-configs.nu for implementation details.

Validation and Testing

Test Generated Configs

# Export solo deployment
nickel export --format json provisioning/schemas/infrastructure/examples-solo-deployment.ncl 
  > solo-infra.json

# Validate JSON structure
jq . solo-infra.json

# Inspect specific component (Docker Compose services)
jq '.docker_compose_services | keys' solo-infra.json

# Check resource allocation
jq '.docker_compose_services.orchestrator.deploy.resources.limits' solo-infra.json

Validate with Docker/Kubectl

# Export and validate Docker Compose
nickel export --format yaml examples-solo-deployment.ncl 
  | docker-compose config --quiet

# Validate Kubernetes (if applicable)
nickel export --format yaml examples-enterprise-deployment.ncl 
  | kubectl apply --dry-run=client -f -

# Validate Prometheus config
nickel export --format yaml prometheus.ncl 
  | promtool check config -

Integration with ConfigLoader

Infrastructure schemas are independent from platform config schemas:

Platform configs → Service-specific settings (port, timeouts, auth)
Infrastructure schemas → Deployment-specific settings (replicas, resources, networking)

ConfigLoader automatically loads platform configs. Infrastructure configs are generated separately and deployed via infrastructure tools:

Platform Schema (Nickel)
    ↓ nickel export → TOML
    ↓ ConfigLoader → Service reads config

Infrastructure Schema (Nickel)
    ↓ nickel export → YAML/JSON
    ↓ Docker/Kubernetes/Nginx CLI

Next Steps

Use these schemas in your infrastructure-as-code pipeline
Generate configs with the automation script
Validate before deployment using format-specific tools
Maintain single source of truth by updating schemas, not generated files

Version: 1.1.0 (Infrastructure Examples & Validation Added) Total Schemas: 6 core files, 1,577 lines Deployment Examples: 2 files, 54 lines (solo + enterprise) Validated: All schemas and examples pass type-checking and export validation Last Updated: 2025-01-06 Nickel Version: Latest