# Nix Integration Section for CLAUDE.md

Add this section to CLAUDE.md under the "Development Environment" or "Essential Commands" section.

---

## Nix Flakes Integration

Towerops supports both traditional development setup and Nix flakes for reproducible environments.

### Using Nix for Development

**Enter development environment:**

```bash
# With direnv (automatic)
cp .envrc.example .envrc
direnv allow

# Without direnv (manual)
nix develop
```

**The Nix shell provides:**
- Auto-started PostgreSQL 16 (`.nix-postgres/`, port 5432)
- Auto-started Redis (`.nix-redis/`, port 6379)
- Pre-installed Elixir, LSPs, formatters, and all development tools
- Pre-configured environment variables (DATABASE_URL, REDIS_URL, etc.)
- Pre-commit hooks (mix format, credo, nixfmt)

**Service management:**

```bash
start-services  # Start PostgreSQL and Redis
stop-services   # Stop services
```

Services auto-start when entering the Nix shell and auto-stop on exit.

### Building with Nix

**Build Elixir release:**

```bash
nix build .#towerops
./result/bin/towerops start
```

**Build Docker image:**

```bash
nix build .#dockerImage
docker load < result
```

**Build C NIF separately:**

```bash
nix build .#towerops-nif
ls -lh result/lib/towerops_nif.so
```

### Nix File Structure

```
flake.nix              # Main flake definition
├── nix/
│   ├── c-nif.nix      # C NIF derivation (cached separately)
│   ├── build.nix      # Mix release derivation
│   ├── docker.nix     # OCI image using dockerTools.buildLayeredImage
│   └── shell.nix      # Development shell
├── flake.lock         # Locked dependency versions
├── .envrc.example     # direnv configuration example
└── shell.nix          # Compatibility shim for nix-shell
```

### Updating Dependencies

**Update Nix flake inputs:**

```bash
nix flake update          # Update all inputs
nix flake update nixpkgs  # Update specific input
```

**Update Mix dependencies:**

Mix dependencies are managed via `mix.exs` and `mix.lock` as usual. After updating `mix.lock`, rebuild:

```bash
mix deps.update --all
nix build .#towerops --rebuild
```

### CI/CD with Nix

The project includes Nix-based CI configuration in `.gitlab-ci.yml.nix`. To activate:

1. Set up NixOS GitLab Runner with `nix` tag
2. Configure Cachix (see docs/nix.md)
3. Add `CACHIX_AUTH_TOKEN` to GitLab CI/CD variables
4. Activate Nix CI: `mv .gitlab-ci.yml.nix .gitlab-ci.yml`

### Key Benefits

- **Reproducible builds**: Identical across dev, CI, and production
- **Faster CI**: Binary caching via Cachix (~60% faster builds)
- **Smaller images**: ~150-200 MB (vs ~500 MB Debian-based)
- **One-command setup**: `nix develop` provides full environment
- **No system pollution**: All dependencies isolated in Nix store

### Important Notes

- **C NIF**: Pre-built in Nix and copied into release (no rebuild needed)
- **MIB files**: Bundled from `priv/mibs/` into release
- **Vendored deps**: `vendor/` directory included in source
- **Assets**: Built via Mix aliases (esbuild, tailwind)
- **Services**: Auto-started in dev shell, manual in production

**For comprehensive Nix documentation, see [docs/nix.md](docs/nix.md).**

---

Insert this section into CLAUDE.md after the "Essential Commands" section.