provisioning/tools/nickel-installation-guide.md

Nickel Installation Guide

Overview

Nickel is a configuration language that complements KCL in the provisioning system. It provides:

• Lazy evaluation for efficient configuration processing
• Modern functional programming paradigms
• Excellent integration with the CLI daemon for config rendering

Installation Methods

Recommended: Nix (Official Method)

Nickel is maintained by Tweag and officially recommends Nix for installation. This avoids all dependency issues:

# Install Nix (one-time setup) - Using official NixOS installer
curl https://nixos.org/nix/install | sh

# Install Nickel via Nix
nix profile install nixpkgs#nickel

# Verify installation
nickel --version

Why Nix?

• Isolated, reproducible environments
• No system library conflicts
• Official Nickel distribution method
• Works on macOS, Linux, and other Unix-like systems
• Pre-built binaries available

Alternative: Automatic Installation

The provisioning system can automate installation:

# Via tools-install script (uses Nix if available)
$PROVISIONING/core/cli/tools-install nickel

# Check installation status
$PROVISIONING/core/cli/tools-install check

Alternative: Manual Installation from Source

If you have a Rust toolchain:

cargo install nickel-lang-cli

Note: This requires Rust compiler (slower than pre-built binaries)

Troubleshooting

"Library not loaded: /nix/store/..." Error

This occurs when using pre-built binaries without Nix installed. Solution: Install Nix or use Cargo:

# Option 1: Install Nix (recommended) - Using official NixOS installer
curl https://nixos.org/nix/install | sh

# Then install Nickel
nix profile install nixpkgs#nickel

# Option 2: Build from source with Cargo
cargo install nickel-lang-cli

Command Not Found

Ensure Nix is properly installed and in PATH:

# Check if Nix is installed
which nix

# If not found, install Nix first using official NixOS installer:
curl https://nixos.org/nix/install | sh

# Then install Nickel
nix profile install nixpkgs#nickel

Version Mismatch

To ensure you're using the correct version:

# Check installed version
nickel --version

# Expected version (from provisioning/core/versions)
echo $NICKEL_VERSION

# Update to latest
nix profile upgrade '*'

Integration with Provisioning System

CLI Daemon Integration

Nickel is integrated into the CLI daemon for configuration rendering:

# Render Nickel configuration via daemon
curl -X POST http://localhost:9091/config/render 
  -H "Content-Type: application/json" 
  -d '{
    "language": "nickel",
    "content": "{name = \"my-config\", enabled = true}",
    "context": {"env": "prod"}
  }'

Comparison with KCL

Feature	KCL	Nickel
Type System	Gradual, OOP-style	Gradual, Functional
Evaluation	Eager	Lazy (partial evaluation)
Performance	Fast	Very fast (lazy)
Learning Curve	Moderate	Functional programming knowledge helps
Use Cases	Infrastructure schemas	Configuration merging, lazy evaluation

Deployment Considerations

macOS M1/M2/M3 (arm64)

Nix automatically handles architecture:

nix profile install nixpkgs#nickel
# Automatically installs arm64 binary

Linux (x86_64/arm64)

nix profile install nixpkgs#nickel
# Automatically installs correct architecture

CI/CD Environments

For GitHub Actions or other CI/CD:

# .github/workflows/example.yml
- name: Install Nickel
  run: |
    curl https://nixos.org/nix/install | sh
    nix profile install nixpkgs#nickel

Resources

• Official Website: https://nickel-lang.org
• Getting Started: https://nickel-lang.org/getting-started
• User Manual: https://nickel-lang.org/user-manual
• GitHub: https://github.com/tweag/nickel
• Nix Package: https://search.nixos.org/packages?query=nickel

Version Information

Current provisioning system configuration:

# View configured version
cat $PROVISIONING/core/versions | grep NICKEL_VERSION

# Current: 1.15.1

Support

For issues related to:

• Nickel language: See https://github.com/tweag/nickel/issues
• Nix installation: See https://github.com/DeterminateSystems/nix-installer
• Provisioning integration: See the provisioning system documentation