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:

```bash
# 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
```bash
sudo install -m 0755 target/release/nx9-wg /usr/local/bin/nx9-wg
```

### Step 2.2 — Create Filesystem Layout & Set Strict Permissions
```bash
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
```bash
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:
```bash
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
```bash
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
```bash
sudo systemctl status nx9-wg
```

### Step 3.2 — Check Operational Health via CLI
```bash
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)
```bash
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
```bash
sudo /usr/local/bin/nx9-wg peer create \
  --interface wg0 \
  --name alice-mobile \
  --profile full_tunnel \
  --mtu 1280
```

### Step 3.6 — Apply Reconciliation
```bash
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:
```bash
sudo /usr/local/bin/nx9-wg backup create --description "Pre-upgrade snapshot"
sudo /usr/local/bin/nx9-wg backup list
```

### Restoring from Backup
```bash
# 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.

```bash
# 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:
   ```bash
   sudo systemctl stop nx9-wg
   ```
2. Re-install the previous working binary:
   ```bash
   sudo install -m 0755 nx9-wg-previous /usr/local/bin/nx9-wg
   ```
3. Restore the pre-upgrade database backup if schema changes occurred:
   ```bash
   sudo /usr/local/bin/nx9-wg backup restore <PRE_UPGRADE_BACKUP_ID>
   ```
4. Start service and verify:
   ```bash
   sudo systemctl start nx9-wg
   sudo /usr/local/bin/nx9-wg system health
   ```

---

## 7. Safe Uninstallation

### Standard Uninstallation (Preserves Database & Configuration)
```bash
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)
```bash
sudo bash uninstall.sh --purge
```
*Requires explicit interactive confirmation before permanently deleting all database files, backups, logs, and configuration.*