44648e3206
- Remove KCL ecosystem (~220 files deleted) - Migrate all infrastructure to Nickel schema system - Consolidate documentation: legacy docs → provisioning/docs/src/ - Add CI/CD workflows (.github/) and Rust build config (.cargo/) - Update core system for Nickel schema parsing - Update README.md and CHANGES.md for v5.0.0 release - Fix pre-commit hooks: end-of-file, trailing-whitespace - Breaking changes: KCL workspaces require migration - Migration bridge available in docs/src/development/
188 lines
4.3 KiB
Markdown
188 lines
4.3 KiB
Markdown
# 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
|