towerops/docs/NIX-VERIFICATION.md

Nix Flakes Verification Checklist

This document provides a comprehensive checklist for verifying the Nix flakes integration.

Prerequisites

• Nix installed with flakes enabled
• direnv installed (optional)
• Docker installed (for image testing)
• Cachix account created (for binary caching)

Phase 1: Core Flake Setup

Verify flake.nix

• nix flake check passes without errors
• nix flake show displays all packages and devShells
• nix flake metadata shows correct inputs

cd towerops-web
nix flake check
nix flake show
nix flake metadata

Expected output:

packages
├── aarch64-darwin
│   ├── dockerImage
│   ├── default: package 'towerops-0.1.0'
│   ├── towerops: package 'towerops-0.1.0'
│   └── towerops-nif: package 'towerops-nif-0.1.0'
└── x86_64-linux
    ├── dockerImage
    ├── default: package 'towerops-0.1.0'
    ├── towerops: package 'towerops-0.1.0'
    └── towerops-nif: package 'towerops-nif-0.1.0'

Phase 2: C NIF Build

Build C NIF

• nix build .#towerops-nif completes successfully
• Output binary exists at result/lib/towerops_nif.so
• Binary links against libnetsnmp

nix build .#towerops-nif
ls -lh result/lib/towerops_nif.so
ldd result/lib/towerops_nif.so | grep netsnmp

Expected output:

-rwxr-xr-x  1 user  group   50K Feb  7 12:00 result/lib/towerops_nif.so
libnetsnmp.so.40 => /nix/store/.../lib/libnetsnmp.so.40

Verify NIF Functionality

• NIF loads without errors
• Can call MIB resolution functions

nix develop
iex -S mix
# In IEx:
ToweropsNative.load_mib_directory("priv/mibs")
# Should return: {:ok, _} or {:error, :already_initialized}

Phase 3: Mix Release Build

Build Elixir Release

• nix build .#towerops completes successfully
• Release binary exists at result/bin/towerops
• Release contains MIB files
• Release contains vendored Oban packages

nix build .#towerops
ls -lh result/bin/towerops
find result -name "*.mib" | head -5
find result -name "oban_*" -type d

Expected output:

-rwxr-xr-x  1 user  group  10K result/bin/towerops
result/lib/towerops-0.1.0/priv/mibs/SNMPv2-MIB.mib
result/lib/towerops-0.1.0/priv/mibs/IF-MIB.mib
...
result/lib/oban_pro-1.6.0
result/lib/oban_web-2.11.0
result/lib/oban_met-1.0.0

Test Release Execution

• Release starts without errors
• RPC commands work
• MIB directory is accessible

# Test RPC
./result/bin/towerops rpc "1 + 1"
# Expected: 2

# Test MIB loading (requires database connection)
# Set up DATABASE_URL, SECRET_KEY_BASE, etc. first
export DATABASE_URL="ecto://user@localhost/towerops_dev"
export SECRET_KEY_BASE="test_secret_key_base_at_least_64_bytes_long_for_phoenix"
export CLOAK_KEY="test_cloak_key_base64_32bytes="

./result/bin/towerops eval "Application.ensure_all_started(:towerops)"

Phase 4: Docker Image Build

Build Docker Image

• nix build .#dockerImage completes successfully
• Image size is < 250 MB (target: 150-200 MB)
• Image loads into Docker successfully

nix build .#dockerImage
nix path-info -S .#dockerImage
docker load < result
docker images | grep towerops

Expected output:

/nix/store/...-docker-image-towerops-latest.tar.gz  180.5 MiB
registry.gitlab.com/towerops/towerops   latest   abc123def456   190MB

Verify Image Contents

• Image contains towerops release
• Image contains net-snmp runtime
• Image contains MIB files
• Image runs as non-root user

# Check contents
docker run --rm registry.gitlab.com/towerops/towerops:latest ls -la /

# Check user
docker run --rm registry.gitlab.com/towerops/towerops:latest id
# Expected: uid=65534(nobody) gid=65534(nobody)

# Check MIB files
docker run --rm registry.gitlab.com/towerops/towerops:latest \
  find / -name "*.mib" 2>/dev/null | head -5

# Check snmptranslate
docker run --rm registry.gitlab.com/towerops/towerops:latest which snmptranslate

Test Image Execution

• Image starts with healthcheck passing
• Phoenix server responds on port 4000
• RPC commands work inside container

# Start container (requires database)
docker run --rm -p 4000:4000 \
  -e DATABASE_URL="ecto://user@host.docker.internal/towerops_dev" \
  -e SECRET_KEY_BASE="test_secret_key_base_at_least_64_bytes_long" \
  -e CLOAK_KEY="test_cloak_key_base64_32bytes=" \
  -e PHX_HOST="localhost" \
  registry.gitlab.com/towerops/towerops:latest

# Test healthcheck (in another terminal)
docker ps --filter "name=towerops" --format "{{.Status}}"
# Should show "healthy" after ~30 seconds

# Test RPC
docker exec <container-id> /nix/store/.../bin/towerops rpc "1 + 1"

Phase 5: Development Shell

Enter Development Shell

• nix develop completes successfully
• PostgreSQL auto-starts
• Redis auto-starts
• Databases are created
• Welcome message displays

nix develop
# Should auto-start services and show welcome message

Expected output:

🚀 Starting development services...
📦 Initializing PostgreSQL database...
🐘 Starting PostgreSQL on port 5432...
✓ PostgreSQL started successfully
📮 Starting Redis on port 6379...
✓ Redis started successfully
✨ Development environment ready!

╔═══════════════════════════════════════════════════════════╗
║                                                           ║
║  Towerops Development Environment                        ║
║                                                           ║
╚═══════════════════════════════════════════════════════════╝

Verify Services

• PostgreSQL responds to connections
• Redis responds to PING
• Databases exist
• TimescaleDB extension available (optional)

# In Nix shell
pg_isready -h localhost -p 5432
# Expected: localhost:5432 - accepting connections

redis-cli ping
# Expected: PONG

psql -U $USER -h localhost -p 5432 -l | grep towerops
# Expected: towerops_dev, towerops_test

psql -U $USER -h localhost -p 5432 -d towerops_dev -c "SELECT * FROM pg_extension WHERE extname = 'timescaledb';"
# Expected: 1 row if TimescaleDB available, 0 rows if not (ok for dev)

Test Mix Commands

• mix deps.get works
• mix compile works
• mix ecto.migrate works
• mix phx.server starts
• mix test runs

mix deps.get
mix compile
mix ecto.migrate
mix phx.server &
sleep 5
curl http://localhost:4000
kill %1  # Stop Phoenix

mix test --only quick || mix test | head -50

Verify Pre-commit Hooks

• Pre-commit hooks are installed
• mix format hook works
• credo hook works
• nixfmt hook works

# Make a formatting violation
echo "defmodule Foo do end" >> lib/foo.ex
git add lib/foo.ex
git commit -m "test"
# Should fail with formatting error

# Fix and retry
mix format
git add lib/foo.ex
git commit -m "test"
# Should pass or fail on other hooks

# Clean up
git reset HEAD~1
rm lib/foo.ex

Phase 6: direnv Integration

Configure direnv

• .envrc.example exists
• Can copy to .envrc
• direnv loads environment automatically

cp .envrc.example .envrc
direnv allow
cd ..
cd towerops-web
# Should auto-load environment and start services

echo $MIX_ENV
# Expected: dev

which mix
# Expected: /nix/store/.../bin/mix

Verify Environment Variables

• DATABASE_URL is set
• REDIS_URL is set
• MIX_ENV is set to dev
• SECRET_KEY_BASE is set

echo $DATABASE_URL
echo $REDIS_URL
echo $MIX_ENV
echo $SECRET_KEY_BASE | head -c 32

Phase 7: Legacy Compatibility

Test shell.nix Compatibility

• nix-shell works (without flakes)
• Environment is identical to nix develop

nix-shell
# Should enter same environment as `nix develop`

echo $MIX_ENV
which mix
exit

Phase 8: Cachix Integration

Set Up Cachix

• Cachix account created
• Cache created: cachix create towerops
• Keypair generated
• Public key added to flake.nix

cachix create towerops
cachix generate-keypair towerops
cachix get towerops
# Copy public key to flake.nix

Test Local Cachix Push

• Can push builds to cache
• Can pull builds from cache

# Push build to cache
nix build .#dockerImage
nix path-info --json .#dockerImage | jq -r '.[].path' | cachix push towerops

# Verify push
cachix info towerops
# Should show recent push

# Clean local store
nix-collect-garbage -d

# Rebuild (should pull from cache)
time nix build .#dockerImage
# Should be much faster (seconds vs minutes)

Configure GitLab CI

• CACHIX_AUTH_TOKEN added to GitLab variables
• .gitlab-ci.yml.nix updated with correct public key
• Ready to activate Nix CI

# Get auth token
cachix authtoken
# Add to GitLab: Settings → CI/CD → Variables

# Verify .gitlab-ci.yml.nix has correct key
grep "towerops.cachix.org-1:" .gitlab-ci.yml.nix

Phase 9: Documentation

Verify Documentation

• docs/nix.md exists and is comprehensive
• docs/README-nix-section.md created for README update
• docs/CLAUDE-nix-section.md created for CLAUDE.md update
• All code examples in docs are accurate

ls -lh docs/nix.md docs/README-nix-section.md docs/CLAUDE-nix-section.md

# Test commands from docs
# (Run through "Quick Start" section)

Performance Benchmarks

Measure Build Times

• C NIF build time
• Elixir release build time
• Docker image build time
• Total clean build time

# Clean builds
nix-collect-garbage -d

time nix build .#towerops-nif
# Target: < 1 minute

time nix build .#towerops
# Target: < 10 minutes (first build)

time nix build .#dockerImage
# Target: < 15 minutes (first build)

# Cached rebuilds (after changing one Elixir file)
echo "# comment" >> lib/towerops_web/router.ex
time nix build .#towerops --rebuild
# Target: < 5 minutes

Measure Image Size

• Docker image size < 250 MB
• Compare to previous Debian-based image

nix path-info -S .#dockerImage
docker images | grep towerops

# Compare to old image (if available)
# Target: ~50% reduction

Production Deployment Test

Deploy to Staging/Production

• Build image with Nix
• Push to GitLab registry
• Deploy to Kubernetes
• Health checks pass
• Application functionality verified

# Build and tag
nix build .#dockerImage
docker load < result
docker tag registry.gitlab.com/towerops/towerops:latest \
  registry.gitlab.com/towerops/towerops:nix-test

# Push to registry
docker push registry.gitlab.com/towerops/towerops:nix-test

# Deploy to staging (adjust namespace/deployment as needed)
kubectl set image deployment/towerops \
  towerops=registry.gitlab.com/towerops/towerops:nix-test \
  -n towerops-staging

# Verify deployment
kubectl get pods -n towerops-staging
kubectl logs -n towerops-staging deployment/towerops --tail=50

# Check health
kubectl exec -n towerops-staging deployment/towerops -- \
  /nix/store/.../bin/towerops rpc "1 + 1"

Success Criteria Summary

All items below must pass:

• nix flake check passes
• C NIF builds and links correctly
• Mix release builds with assets and MIB files
• Docker image builds and is < 250 MB
• Development shell starts services automatically
• direnv integration works seamlessly
• Cachix push/pull works
• Documentation is comprehensive
• Production deployment succeeds

Issues Tracker

Document any issues encountered during verification:

Phase	Issue	Resolution	Status
Example	Error XYZ	Fixed by ABC	Resolved

Final Sign-Off

• All verification steps completed
• All issues resolved or documented
• Ready for production use
• Team trained on Nix workflows

Verified by: _______________ Date: _______________ Nix version: _______________ Platform: _______________