Devbox Development Environment¶

This document describes how to use the provided devbox.json configuration to quickly set up a development environment with all necessary tools for consuming BIND DNS services.

What is Devbox?¶

Devbox is a command-line tool that creates isolated, reproducible development environments using Nix. It ensures that all team members have the same tool versions and dependencies.

Prerequisites¶

Install Devbox:

# macOS
brew install jetpack-io/devbox/devbox

# Linux
curl -fsSL https://get.jetpack.io/devbox | bash

Install Nix (if not already installed):

sh <(curl -L https://nixos.org/nix/install)

Quick Start¶

Clone the repository and navigate to the project directory:
```
git clone <repository-url>
cd private-dns-zone
```
Start the devbox environment:
```
devbox shell
```

This will: - Install all required packages (dig, DNSControl, Python, Go, Docker, etc.) - Set up octoDNS Python virtual environment - Install DNSControl - Verify all installations - Display quick start commands

Included Tools¶

The devbox environment includes:

Core DNS Tools¶

BIND utilities (dig, nslookup, nsupdate) with TSIG support
Docker & Docker Compose for running BIND DNS server

DNS Management Clients¶

DNSControl - JavaScript-based declarative DNS management
octoDNS - Python-based DNS-as-code with multi-provider support
External-DNS (documentation and examples)

Development Tools¶

Go (for DNSControl and external-dns)
Python 3 with pip (for octoDNS)
Node.js and npm (for JavaScript tooling)
curl, jq, yq (for API interactions and data processing)

Available Scripts¶

The devbox environment provides several convenient scripts:

Activate octoDNS Environment¶

devbox run activate-octodns

Test DNS Resolution¶

devbox run test-dns

Validate All Configurations¶

devbox run validate-all

Setup Example Directories¶

devbox run setup-examples

Usage Examples¶

Testing BIND DNS Server with TSIG¶

Start the BIND DNS server:

./env-manager.sh generate-keys
docker-compose up -d

Test basic DNS resolution:
```
dig @localhost example.local A
```

Test with TSIG authentication:

# Get TSIG key from environment
TSIG_KEY=$(grep EXTERNAL_DNS_TSIG_KEY_SECRET .env | cut -d'=' -f2)

# Test with TSIG
dig @localhost -y hmac-sha256:external-dns-key:$TSIG_KEY example.local A

Using DNSControl¶

Create a basic configuration:

cat > dnsconfig.js << 'EOF'
var REG_NONE = NewRegistrar("none");
var DSP_BIND = NewDnsProvider("bind", {
    "server": "127.0.0.1:53",
    "tsig_key_name": "external-dns-key",
    "tsig_key_algorithm": "hmac-sha256",
    "tsig_key_secret": env.TSIG_KEY_SECRET
});

D("example.local", REG_NONE, DnsProvider(DSP_BIND),
    A("@", "192.168.1.100"),
    A("www", "192.168.1.100")
);
EOF

Validate and apply:

dnscontrol check
dnscontrol preview
dnscontrol push

Using octoDNS¶

Activate the octoDNS environment:
```
source ~/.octodns-env/bin/activate
```

Create a basic configuration:

cat > config.yaml << 'EOF'
providers:
  bind:
    class: octodns_bind.BindProvider
    host: 127.0.0.1
    port: 53
    key_name: external-dns-key
    key_algorithm: HMAC-SHA256
    key_secret: env/TSIG_KEY_SECRET

zones:
  example.local.:
    sources:
      - bind
    targets:
      - bind
EOF

Create zone file:

mkdir -p zones
cat > zones/example.local.yaml << 'EOF'
---
'':
  - type: A
    value: 192.168.1.100
www:
  - type: A
    value: 192.168.1.100
EOF

Validate and apply:

octodns-validate --config-file config.yaml
octodns-sync --config-file config.yaml --plan
octodns-sync --config-file config.yaml

Environment Variables¶

The devbox environment sets several useful variables:

DNS_SERVER=localhost - Default DNS server for testing
DNS_PORT=53 - Default DNS port
PYTHONPATH - Includes octoDNS virtual environment paths

Troubleshooting¶

Common Issues¶

DNSControl not found:

# Install manually via Go
go install github.com/StackExchange/dnscontrol/v4@latest

octoDNS command not found:

# Activate the virtual environment
source ~/.octodns-env/bin/activate

TSIG authentication fails:

# Verify TSIG key is correctly set
grep TSIG .env
# Test with nsupdate
echo -e "server localhost\nupdate add test.example.local 300 A 192.168.1.200\nsend" | nsupdate -y hmac-sha256:external-dns-key:$TSIG_KEY

Verification Commands¶

# Check all tools are installed
devbox run validate-all

# Test DNS server is running
dig @localhost example.local SOA

# Verify TSIG support
dig -y hmac-sha256:external-dns-key:$TSIG_KEY @localhost example.local SOA

Benefits of Using Devbox¶

Consistent Environment - All team members get the same tool versions
Fast Setup - One command installs everything needed
Isolated - No conflicts with system packages
Reproducible - Environment can be recreated anywhere
Version Controlled - devbox.json tracks exact dependencies

Next Steps¶

After setting up the devbox environment:

Review the Use Cases documentation
Follow specific integration guides:
UC-001: External-DNS Integration
UC-002: DNSControl Integration
UC-003: octoDNS Integration
Explore the example configurations in the examples/ directory

The devbox environment provides everything you need to develop, test, and deploy DNS management solutions with your BIND DNS server.