nx9-wg/docs/INSTALLATION.md

nx9-wg Production Installation & Deployment Guide

This guide provides the complete, authoritative reference for installing, configuring, securing, maintaining, upgrading, and uninstallation of the nx9-wg WireGuard Appliance Management Engine on Linux.

---

Prerequisites & Runtime Environment

Requirement	Specification	Details
Operating System	Linux (Kernel 5.6+)	Native in-tree WireGuard module support (wireguard.ko).
Architecture	x86_64 or aarch64	Native 64-bit Linux executable.
Packet Filtering	nftables / libnftables.so.1	Native Netfilter execution plane for firewall and NAT masquerade.
Linux Capabilities	CAP_NET_ADMIN, CAP_NET_BIND_SERVICE	Required for RTNETLINK, Generic Netlink, and low-port UDP binding.
Database	SQLite 3 (Embedded)	Statically bundled in binary; zero external database server required.
Process Model	Single Native Executable	Zero external subprocess invocations (no wg, ip, nft, bash, Python, or Node.js).

---

1. Quick Installation via Release Archive

Download and extract the official release archive:

# 1. Download release archive (replace with current version/arch)
tar -xzf nx9-wg-v1.1.0-linux-x86_64.tar.gz
cd nx9-wg-v1.1.0-linux-x86_64

# 2. Run the automated installer as root
sudo bash install.sh

The installer automatically:

• Installs /usr/local/bin/nx9-wg (mode 0755)
• Creates /etc/nx9-wg (mode 0750) and installs /etc/nx9-wg/config.toml (mode 0640) if absent
• Creates /var/lib/nx9-wg (mode 0700) and /var/lib/nx9-wg/backups (mode 0700)
• Bootstraps the initial administrator with a secure random password (/var/lib/nx9-wg/admin-initial-password)
• Installs /etc/systemd/system/nx9-wg.service (mode 0644)
• Enables and starts the nx9-wg service

---

2. Manual Step-by-Step Installation

If you prefer to perform each step manually:

Step 2.1 — Install Binary

sudo install -m 0755 target/release/nx9-wg /usr/local/bin/nx9-wg

Step 2.2 — Create Filesystem Layout & Set Strict Permissions

sudo install -d -m 0750 /etc/nx9-wg
sudo install -d -m 0700 /var/lib/nx9-wg
sudo install -d -m 0700 /var/lib/nx9-wg/backups
sudo install -d -m 0750 /var/log/nx9-wg

Step 2.3 — Install Configuration File

if [ ! -f /etc/nx9-wg/config.toml ]; then
  sudo install -m 0640 config.example.toml /etc/nx9-wg/config.toml
fi

Step 2.4 — Bootstrap Initial Administrator Account

Generate a cryptographically secure 24-character random password written to a restricted file:

sudo /usr/local/bin/nx9-wg \
  --config /etc/nx9-wg/config.toml \
  --data-dir /var/lib/nx9-wg \
  init --generate-password --write-password-file /var/lib/nx9-wg/admin-password

sudo chmod 0600 /var/lib/nx9-wg/admin-password

Step 2.5 — Deploy & Start systemd Service

sudo cp nx9-wg.service /etc/systemd/system/nx9-wg.service
sudo systemctl daemon-reload
sudo systemctl enable --now nx9-wg

---

3. Verification & First Operational Workflow

Step 3.1 — Check Service Status

sudo systemctl status nx9-wg

Step 3.2 — Check Operational Health via CLI

sudo /usr/local/bin/nx9-wg system health
sudo /usr/local/bin/nx9-wg diagnostics all

Step 3.3 — Log in via Web User Interface

Open your browser at http://<server-ip>:8080/ and log in with:

• Username: admin
• Password: Found in /var/lib/nx9-wg/admin-password

Step 3.4 — Create First WireGuard Interface (wg0)

sudo /usr/local/bin/nx9-wg interface create \
  --address-v4 10.100.0.1/24 \
  --port 51820 \
  --mtu 1420 \
  wg0

Step 3.5 — Enroll Client Peer

sudo /usr/local/bin/nx9-wg peer create \
  --interface wg0 \
  --name alice-mobile \
  --profile full_tunnel \
  --mtu 1280

Step 3.6 — Apply Reconciliation

sudo /usr/local/bin/nx9-wg reconcile apply

---

4. Production Backup & Recovery

Mandatory Pre-Upgrade Backup

Always create an authoritative database backup before applying system updates or binary upgrades:

sudo /usr/local/bin/nx9-wg backup create --description "Pre-upgrade snapshot"
sudo /usr/local/bin/nx9-wg backup list

Restoring from Backup

# 1. Stop active service
sudo systemctl stop nx9-wg

# 2. Restore database from backup snapshot
sudo /usr/local/bin/nx9-wg backup restore <BACKUP_ID>

# 3. Restart service & reconcile state
sudo systemctl start nx9-wg
sudo /usr/local/bin/nx9-wg reconcile apply

---

5. Upgrading nx9-wg

The nx9-wg persistence model utilizes SQLite with automatic schema migrations executed upon startup.

# 1. Stop service
sudo systemctl stop nx9-wg

# 2. Create backup
sudo /usr/local/bin/nx9-wg backup create --description "Pre-upgrade backup"

# 3. Install new binary
sudo install -m 0755 nx9-wg-new /usr/local/bin/nx9-wg

# 4. Restart service (automatic migration)
sudo systemctl start nx9-wg

# 5. Verify convergence
sudo /usr/local/bin/nx9-wg reconcile plan
sudo /usr/local/bin/nx9-wg system health

---

6. Rollback Procedure

If a new binary fails or encounters incompatibility:

1. Stop the active service:

   sudo systemctl stop nx9-wg
   

2. Re-install the previous working binary:

   sudo install -m 0755 nx9-wg-previous /usr/local/bin/nx9-wg
   

3. Restore the pre-upgrade database backup if schema changes occurred:

   sudo /usr/local/bin/nx9-wg backup restore <PRE_UPGRADE_BACKUP_ID>
   

4. Start service and verify:

   sudo systemctl start nx9-wg
   sudo /usr/local/bin/nx9-wg system health
   

---

7. Safe Uninstallation

Standard Uninstallation (Preserves Database & Configuration)

sudo bash uninstall.sh

Stops and disables the service, removes /usr/local/bin/nx9-wg and the systemd unit file, while preserving /etc/nx9-wg and /var/lib/nx9-wg.

Total Purge (Destructive)

sudo bash uninstall.sh --purge

Requires explicit interactive confirmation before permanently deleting all database files, backups, logs, and configuration.