# 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:

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
nix profile install nixpkgs#nickel
# Automatically installs arm64 binary
```

### Linux (x86_64/arm64)

```bash
nix profile install nixpkgs#nickel
# Automatically installs correct architecture
```

### CI/CD Environments

For GitHub Actions or other CI/CD:

```yaml
# .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:

```bash
# 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