Developer Guide & Repository Reference

This guide provides instructions for building, testing, linting, and contributing to the nx9-wg codebase.

1. Workspace Layout

The repository is organized as a Cargo workspace containing 6 crates and the root application binary:

crates/nx9-wg-core: Common domain entities, RFC validators, cryptography, and configuration.
crates/nx9-wg-db: SQLite database persistence layer, migration SQL scripts, and repository implementations.
crates/nx9-wireguard: WireGuard Generic Netlink execution, RTNETLINK link management, config builder, and QR engine.
crates/nx9-wg-network: RTNETLINK route management, libnftables.so.1 integration, and procfs forwarding.
crates/nx9-wg-api: Axum REST API router, WebSocket broadcaster, authentication middleware, and reconciliation engine.
crates/nx9-wg-ui: Design tokens, CSS stylesheet compiler, view models, and SPA asset integration.
src/main.rs: Root CLI command parser and daemon entry point.

2. Prerequisites & Build Commands

Prerequisites

Rust Toolchain: 1.85+ (Edition 2024).
C Compiler: gcc or clang (for SQLite C amalgamation).
Linux Libraries: libnftables-dev (Debian/Ubuntu) or nftables-devel / libnftables (Fedora/Arch).

Build Commands

# Debug build
cargo build --workspace

# Release build
cargo build --release

# Format check
cargo fmt --all -- --check

# Clippy linter
cargo clippy --workspace --all-targets --all-features -- -D warnings

3. Test Execution & SAFE Mode (`LIVE=0`) vs Privileged Mode (`LIVE=1`)

To prevent accidental modifications to developer workstations, all integration and live kernel test scripts default to SAFE mode (LIVE=0):

# 1. Run full workspace unit & integration tests
cargo test --workspace

# 2. Run Comprehensive CLI Verification Suite (210 checks)
LIVE=0 bash scripts/test-cli-comprehensive.sh

# 3. Run Native Linux Integration Test Suite (20 checks)
LIVE=0 bash scripts/test-native-integration.sh

# 4. Run Dedicated Live Kernel Test Suite (24 checks)
LIVE=0 bash scripts/test-live-kernel.sh

Privileged Real-Kernel Testing (`LIVE=1`)

Caution

LIVE=1 tests must ONLY be executed on a dedicated disposable Linux virtual machine or container with CAP_NET_ADMIN. Never execute LIVE=1 on a production host.

# On a dedicated disposable VM as root:
sudo LIVE=1 bash scripts/test-live-kernel.sh

4. Release Packaging

To build the self-contained release distribution archives:

bash scripts/package-release.sh

Outputs .tar.gz, .tar.xz, and .sha256 files in target/dist/.

2.6 KiB Raw Blame History